1erl_eval(3) Erlang Module Definition erl_eval(3)
2
6 erl_eval - The Erlang meta interpreter.
7
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
14 bindings() = [{name(), value()}]
15 binding_struct() = orddict:orddict() | map()
17 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 expression() = erl_parse:abstract_expr()
22 expressions() = [erl_parse:abstract_expr()]
24 As returned by erl_parse:parse_exprs/1 or io:parse_erl_exprs/2.
26 expression_list() = [expression()]
28 func_spec() =
30 {Module :: module(), Function :: atom()} | function()
31 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 lfun_value_handler() =
41 fun((Name :: atom(), Arguments :: [term()]) ->
42 Value :: value())
43 local_function_handler() =
45 {value, lfun_value_handler()} |
46 {eval, lfun_eval_handler()} |
47 none
48 Further described in section Local Function Handler in this
50 module
51 name() = term()
53 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 non_local_function_handler() = {value, nlfun_handler()} | none
62 Further described in section Non-Local Function Handler in this
64 module.
65 value() = term()
67
69 add_binding(Name, Value, BindingStruct) -> binding_struct()
70 Types:
72 Name = name()
74 Value = value()
75 BindingStruct = binding_struct()
76 Adds binding Name=Value to BindingStruct. Returns an updated
78 binding structure.
79 binding(Name, BindingStruct) -> {value, value()} | unbound
81 Types:
83 Name = name()
85 BindingStruct = binding_struct()
86 Returns the binding of Name in BindingStruct.
88 bindings(BindingStruct :: binding_struct()) -> bindings()
90 Returns the list of bindings contained in the binding structure.
92 del_binding(Name, BindingStruct) -> binding_struct()
94 Types:
96 Name = name()
98 BindingStruct = binding_struct()
99 Removes the binding of Name in BindingStruct. Returns an updated
101 binding structure.
102 expr(Expression, Bindings) -> {value, Value, NewBindings}
104 expr(Expression, Bindings, LocalFunctionHandler) ->
106 {value, Value, NewBindings}
107 expr(Expression, Bindings, LocalFunctionHandler,
109 NonLocalFunctionHandler) ->
110 {value, Value, NewBindings}
111 expr(Expression, Bindings, LocalFunctionHandler,
113 NonLocalFunctionHandler, ReturnFormat) ->
114 {value, Value, NewBindings} | Value
115 Types:
117 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 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 Returns {value, Value, NewBindings} by default. If ReturnFormat
133 is value, only Value is returned.
134 expr_list(ExpressionList, Bindings) -> {ValueList, NewBindings}
136 expr_list(ExpressionList, Bindings, LocalFunctionHandler) ->
138 {ValueList, NewBindings}
139 expr_list(ExpressionList, Bindings, LocalFunctionHandler,
141 NonLocalFunctionHandler) ->
142 {ValueList, NewBindings}
143 Types:
145 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 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 Returns {ValueList, NewBindings}.
160 exprs(Expressions, Bindings) -> {value, Value, NewBindings}
162 exprs(Expressions, Bindings, LocalFunctionHandler) ->
164 {value, Value, NewBindings}
165 exprs(Expressions, Bindings, LocalFunctionHandler,
167 NonLocalFunctionHandler) ->
168 {value, Value, NewBindings}
169 Types:
171 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 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 Returns {value, Value, NewBindings}
187 new_bindings() -> binding_struct()
189 Returns an empty binding structure.
191
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 {value,Func}:
200 This defines a local function handler that is called with:
201 Func(Name, Arguments)
203 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 {eval,Func}:
211 This defines a local function handler that is called with:
212 Func(Name, Arguments, Bindings)
214 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 {value,Value,NewBindings}
220 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 none:
228 There is no local function handler.
229
231 The optional argument NonLocalFunctionHandler can be used to define a
232 function that is called in the following cases:
233 * A functional object (fun) is called.
235 * A built-in function is called.
237 * A function is called using the M:F syntax, where M and F are atoms
239 or expressions.
240 * An operator Op/A is called (this is handled as a call to function
242 erlang:Op/A).
243 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 {value,Func}:
249 This defines a non-local function handler. The function may be
250 called with two arguments:
251 Func(FuncSpec, Arguments)
253 or three arguments:
255 Func(Anno, FuncSpec, Arguments)
257 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 none:
265 There is no non-local function handler.
266 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 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 Calls to functions defined by evaluating fun expressions "fun ... end"
280 are also hidden from non-local function handlers.
281 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
289 Undocumented functions in this module are not to be used.
290Ericsson AB stdlib 4.2 erl_eval(3)