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()
17
18              A binding structure.
19
20       expression() = erl_parse:abstract_expr()
21
22       expressions() = [erl_parse:abstract_expr()]
23
24              As returned by erl_parse:parse_exprs/1 or io:parse_erl_exprs/2.
25
26       expression_list() = [expression()]
27
28       func_spec() =
29           {Module :: module(), Function :: atom()} | function()
30
31       lfun_eval_handler() =
32           fun((Name :: atom(),
33                Arguments :: expression_list(),
34                Bindings :: binding_struct()) ->
35                   {value,
36                    Value :: value(),
37                    NewBindings :: binding_struct()})
38
39       lfun_value_handler() =
40           fun((Name :: atom(), Arguments :: [term()]) ->
41                   Value :: value())
42
43       local_function_handler() =
44           {value, lfun_value_handler()} |
45           {eval, lfun_eval_handler()} |
46           none
47
48              Further  described  in  section   Local Function Handler in this
49              module
50
51       name() = term()
52
53       nlfun_handler() =
54           fun((FuncSpec :: func_spec(), Arguments :: [term()]) -> term())
55
56       non_local_function_handler() = {value, nlfun_handler()} | none
57
58              Further described in section  Non-Local Function Handler in this
59              module.
60
61       value() = term()
62

EXPORTS

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

LOCAL FUNCTION HANDLER

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

NON-LOCAL FUNCTION HANDLER

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

KNOWN LIMITATION

279       Undocumented functions in this module are not to be used.
280
281
282
283Ericsson AB                       stdlib 3.10                      erl_eval(3)
Impressum