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,
104            Bindings,
105            LocalFunctionHandler,
106            NonLocalFunctionHandler) ->
107               {value, Value, NewBindings}
108
109       expr(Expression,
110            Bindings,
111            LocalFunctionHandler,
112            NonLocalFunctionHandler,
113            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,
141                 Bindings,
142                 LocalFunctionHandler,
143                 NonLocalFunctionHandler) ->
144                    {ValueList, NewBindings}
145
146              Types:
147
148                 ExpressionList = expression_list()
149                 Bindings = binding_struct()
150                 LocalFunctionHandler = local_function_handler()
151                 NonLocalFunctionHandler = non_local_function_handler()
152                 ValueList = [value()]
153                 NewBindings = binding_struct()
154
155              Evaluates a list of expressions in parallel, using the same ini‐
156              tial  bindings  for  each expression. Attempts are made to merge
157              the bindings returned from each  evaluation.  This  function  is
158              useful in LocalFunctionHandler, see section  Local Function Han‐
159              dler in this module.
160
161              Returns {ValueList, NewBindings}.
162
163       exprs(Expressions, Bindings) -> {value, Value, NewBindings}
164
165       exprs(Expressions, Bindings, LocalFunctionHandler) ->
166                {value, Value, NewBindings}
167
168       exprs(Expressions,
169             Bindings,
170             LocalFunctionHandler,
171             NonLocalFunctionHandler) ->
172                {value, Value, NewBindings}
173
174              Types:
175
176                 Expressions = expressions()
177                 Bindings = binding_struct()
178                 LocalFunctionHandler = local_function_handler()
179                 NonLocalFunctionHandler = non_local_function_handler()
180                 Value = value()
181                 NewBindings = binding_struct()
182
183              Evaluates Expressions with the set of bindings  Bindings,  where
184              Expressions is a sequence of expressions (in abstract syntax) of
185              a type that can be  returned  by  io:parse_erl_exprs/2.  For  an
186              explanation  of  when and how to use arguments LocalFunctionHan‐
187              dler and NonLocalFunctionHandler, see sections   Local  Function
188              Handler and  Non-Local Function Handler in this module.
189
190              Returns {value, Value, NewBindings}
191
192       new_bindings() -> binding_struct()
193
194              Returns an empty binding structure.
195

LOCAL FUNCTION HANDLER

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

NON-LOCAL FUNCTION HANDLER

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

KNOWN LIMITATION

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