1erl_eval(3)                Erlang Module Definition                erl_eval(3)
2
3
4

NAME

6       erl_eval - The Erlang meta interpreter.
7

DESCRIPTION

9       This module provides an interpreter for Erlang expressions. The expres‐
10       sions are in the abstract syntax as returned by erl_parse,  the  Erlang
11       parser, or io.
12

DATA TYPES

14       bindings() = [{name(), value()}]
15
16       binding_struct() = orddict:orddict() | map()
17
18              A  binding structure. It is either a map or an orddict. erl_eval
19              will always return the same type as the one given.
20
21       expression() = erl_parse:abstract_expr()
22
23       expressions() = [erl_parse:abstract_expr()]
24
25              As returned by erl_parse:parse_exprs/1 or io:parse_erl_exprs/2.
26
27       expression_list() = [expression()]
28
29       func_spec() =
30           {Module :: module(), Function :: atom()} | function()
31
32       lfun_eval_handler() =
33           fun((Name :: atom(),
34                Arguments :: expression_list(),
35                Bindings :: binding_struct()) ->
36                   {value,
37                    Value :: value(),
38                    NewBindings :: binding_struct()})
39
40       lfun_value_handler() =
41           fun((Name :: atom(), Arguments :: [term()]) ->
42                   Value :: value())
43
44       local_function_handler() =
45           {value, lfun_value_handler()} |
46           {eval, lfun_eval_handler()} |
47           none
48
49              Further described in section  Local  Function  Handler  in  this
50              module
51
52       name() = term()
53
54       nlfun_handler() =
55           fun((FuncSpec :: func_spec(), Arguments :: [term()]) -> term()) |
56           fun((Anno :: erl_anno:anno(),
57                FuncSpec :: func_spec(),
58                Arguments :: [term()]) ->
59                   term())
60
61       non_local_function_handler() = {value, nlfun_handler()} | none
62
63              Further described in section  Non-Local Function Handler in this
64              module.
65
66       value() = term()
67

EXPORTS

69       add_binding(Name, Value, BindingStruct) -> binding_struct()
70
71              Types:
72
73                 Name = name()
74                 Value = value()
75                 BindingStruct = binding_struct()
76
77              Adds binding Name=Value to  BindingStruct.  Returns  an  updated
78              binding structure.
79
80       binding(Name, BindingStruct) -> {value, value()} | unbound
81
82              Types:
83
84                 Name = name()
85                 BindingStruct = binding_struct()
86
87              Returns the binding of Name in BindingStruct.
88
89       bindings(BindingStruct :: binding_struct()) -> bindings()
90
91              Returns the list of bindings contained in the binding structure.
92
93       del_binding(Name, BindingStruct) -> binding_struct()
94
95              Types:
96
97                 Name = name()
98                 BindingStruct = binding_struct()
99
100              Removes the binding of Name in BindingStruct. Returns an updated
101              binding structure.
102
103       expr(Expression, Bindings) -> {value, Value, NewBindings}
104
105       expr(Expression, Bindings, LocalFunctionHandler) ->
106               {value, Value, NewBindings}
107
108       expr(Expression, Bindings, LocalFunctionHandler,
109            NonLocalFunctionHandler) ->
110               {value, Value, NewBindings}
111
112       expr(Expression, Bindings, LocalFunctionHandler,
113            NonLocalFunctionHandler, ReturnFormat) ->
114               {value, Value, NewBindings} | Value
115
116              Types:
117
118                 Expression = expression()
119                 Bindings = binding_struct()
120                 LocalFunctionHandler = local_function_handler()
121                 NonLocalFunctionHandler = non_local_function_handler()
122                 ReturnFormat = none | value
123                 Value = value()
124                 NewBindings = binding_struct()
125
126              Evaluates Expression with the set of bindings Bindings.  Expres‐
127              sion  is an expression in abstract syntax. For an explanation of
128              when and how to use arguments LocalFunctionHandler and NonLocal‐
129              FunctionHandler,  see sections  Local Function Handler and  Non-
130              Local Function Handler in this module.
131
132              Returns {value, Value, NewBindings} by default. If  ReturnFormat
133              is value, only Value is returned.
134
135       expr_list(ExpressionList, Bindings) -> {ValueList, NewBindings}
136
137       expr_list(ExpressionList, Bindings, LocalFunctionHandler) ->
138                    {ValueList, NewBindings}
139
140       expr_list(ExpressionList, Bindings, LocalFunctionHandler,
141                 NonLocalFunctionHandler) ->
142                    {ValueList, NewBindings}
143
144              Types:
145
146                 ExpressionList = expression_list()
147                 Bindings = binding_struct()
148                 LocalFunctionHandler = local_function_handler()
149                 NonLocalFunctionHandler = non_local_function_handler()
150                 ValueList = [value()]
151                 NewBindings = binding_struct()
152
153              Evaluates a list of expressions in parallel, using the same ini‐
154              tial bindings for each expression. Attempts are  made  to  merge
155              the  bindings  returned  from  each evaluation. This function is
156              useful in LocalFunctionHandler, see section  Local Function Han‐
157              dler in this module.
158
159              Returns {ValueList, NewBindings}.
160
161       exprs(Expressions, Bindings) -> {value, Value, NewBindings}
162
163       exprs(Expressions, Bindings, LocalFunctionHandler) ->
164                {value, Value, NewBindings}
165
166       exprs(Expressions, Bindings, LocalFunctionHandler,
167             NonLocalFunctionHandler) ->
168                {value, Value, NewBindings}
169
170              Types:
171
172                 Expressions = expressions()
173                 Bindings = binding_struct()
174                 LocalFunctionHandler = local_function_handler()
175                 NonLocalFunctionHandler = non_local_function_handler()
176                 Value = value()
177                 NewBindings = binding_struct()
178
179              Evaluates  Expressions  with the set of bindings Bindings, where
180              Expressions is a sequence of expressions (in abstract syntax) of
181              a  type that can be returned by io:parse_erl_exprs/2. For an ex‐
182              planation of when and how to use arguments  LocalFunctionHandler
183              and  NonLocalFunctionHandler,  see sections  Local Function Han‐
184              dler and  Non-Local Function Handler in this module.
185
186              Returns {value, Value, NewBindings}
187
188       new_bindings() -> binding_struct()
189
190              Returns an empty binding structure.
191

LOCAL FUNCTION HANDLER

193       During evaluation of a function, no calls can be made  to  local  func‐
194       tions. An undefined function error would be generated. However, the op‐
195       tional argument LocalFunctionHandler can be used to define  a  function
196       that  is  called when there is a call to a local function. The argument
197       can have the following formats:
198
199         {value,Func}:
200           This defines a local function handler that is called with:
201
202         Func(Name, Arguments)
203
204           Name is the name of the local function (an atom) and Arguments is a
205           list  of  the evaluated arguments. The function handler returns the
206           value of the local function. In this  case,  the  current  bindings
207           cannot  be accessed. To signal an error, the function handler calls
208           exit/1 with a suitable exit value.
209
210         {eval,Func}:
211           This defines a local function handler that is called with:
212
213         Func(Name, Arguments, Bindings)
214
215           Name is the name of the local function (an atom),  Arguments  is  a
216           list  of  the  unevaluated  arguments, and Bindings are the current
217           variable bindings. The function handler returns:
218
219         {value,Value,NewBindings}
220
221           Value is the value of the local function and  NewBindings  are  the
222           updated  variable bindings. In this case, the function handler must
223           itself evaluate all the function arguments and manage the bindings.
224           To  signal an error, the function handler calls exit/1 with a suit‐
225           able exit value.
226
227         none:
228           There is no local function handler.
229

NON-LOCAL FUNCTION HANDLER

231       The optional argument NonLocalFunctionHandler can be used to  define  a
232       function that is called in the following cases:
233
234         * A functional object (fun) is called.
235
236         * A built-in function is called.
237
238         * A  function is called using the M:F syntax, where M and F are atoms
239           or expressions.
240
241         * An operator Op/A is called (this is handled as a call  to  function
242           erlang:Op/A).
243
244       Exceptions  are calls to erlang:apply/2,3; neither of the function han‐
245       dlers are called for such calls. The argument can  have  the  following
246       formats:
247
248         {value,Func}:
249           This  defines  a  non-local  function  handler. The function may be
250           called with two arguments:
251
252         Func(FuncSpec, Arguments)
253
254           or three arguments:
255
256         Func(Anno, FuncSpec, Arguments)
257
258           Anno is the erl_anno:anno() of the node, FuncSpec is  the  name  of
259           the  function on the form {Module,Function} or a fun, and Arguments
260           is a list of the evaluated arguments. The function handler  returns
261           the value of the function. To signal an error, the function handler
262           calls exit/1 with a suitable exit value.
263
264         none:
265           There is no non-local function handler.
266
267   Note:
268       For calls such as erlang:apply(Fun, Args) or erlang:apply(Module, Func‐
269       tion,  Args),  the call of the non-local function handler corresponding
270       to the call to erlang:apply/2,3  itself  (Func({erlang,  apply},  [Fun,
271       Args])  or Func({erlang, apply}, [Module, Function, Args])) never takes
272       place.
273
274       The non-local function handler is however called with the evaluated ar‐
275       guments  of the call to erlang:apply/2,3: Func(Fun, Args) or Func({Mod‐
276       ule, Function}, Args) (assuming that {Module, Function} is not {erlang,
277       apply}).
278
279       Calls  to functions defined by evaluating fun expressions "fun ... end"
280       are also hidden from non-local function handlers.
281
282
283       The non-local function handler argument is probably not  used  as  fre‐
284       quently  as  the  local function handler argument. A possible use is to
285       call exit/1 on calls to functions that for some reason are not  allowed
286       to be called.
287

KNOWN LIMITATION

289       Undocumented functions in this module are not to be used.
290
291
292
293Ericsson AB                      stdlib 5.1.1                      erl_eval(3)
Impressum