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 non_local_function_handler() = {value, nlfun_handler()} | none
58 Further described in section Non-Local Function Handler in this
60 module.
61 value() = term()
63
65 add_binding(Name, Value, BindingStruct) -> binding_struct()
66 Types:
68 Name = name()
70 Value = value()
71 BindingStruct = binding_struct()
72 Adds binding Name=Value to BindingStruct. Returns an updated
74 binding structure.
75 binding(Name, BindingStruct) -> {value, value()} | unbound
77 Types:
79 Name = name()
81 BindingStruct = binding_struct()
82 Returns the binding of Name in BindingStruct.
84 bindings(BindingStruct :: binding_struct()) -> bindings()
86 Returns the list of bindings contained in the binding structure.
88 del_binding(Name, BindingStruct) -> binding_struct()
90 Types:
92 Name = name()
94 BindingStruct = binding_struct()
95 Removes the binding of Name in BindingStruct. Returns an updated
97 binding structure.
98 expr(Expression, Bindings) -> {value, Value, NewBindings}
100 expr(Expression, Bindings, LocalFunctionHandler) ->
102 {value, Value, NewBindings}
103 expr(Expression, Bindings, LocalFunctionHandler,
105 NonLocalFunctionHandler) ->
106 {value, Value, NewBindings}
107 expr(Expression, Bindings, LocalFunctionHandler,
109 NonLocalFunctionHandler, ReturnFormat) ->
110 {value, Value, NewBindings} | Value
111 Types:
113 Expression = expression()
115 Bindings = binding_struct()
116 LocalFunctionHandler = local_function_handler()
117 NonLocalFunctionHandler = non_local_function_handler()
118 ReturnFormat = none | value
119 Value = value()
120 NewBindings = binding_struct()
121 Evaluates Expression with the set of bindings Bindings. Expres‐
123 sion is an expression in abstract syntax. For an explanation of
124 when and how to use arguments LocalFunctionHandler and NonLocal‐
125 FunctionHandler, see sections Local Function Handler and Non-
126 Local Function Handler in this module.
127 Returns {value, Value, NewBindings} by default. If ReturnFormat
129 is value, only Value is returned.
130 expr_list(ExpressionList, Bindings) -> {ValueList, NewBindings}
132 expr_list(ExpressionList, Bindings, LocalFunctionHandler) ->
134 {ValueList, NewBindings}
135 expr_list(ExpressionList, Bindings, LocalFunctionHandler,
137 NonLocalFunctionHandler) ->
138 {ValueList, NewBindings}
139 Types:
141 ExpressionList = expression_list()
143 Bindings = binding_struct()
144 LocalFunctionHandler = local_function_handler()
145 NonLocalFunctionHandler = non_local_function_handler()
146 ValueList = [value()]
147 NewBindings = binding_struct()
148 Evaluates a list of expressions in parallel, using the same ini‐
150 tial bindings for each expression. Attempts are made to merge
151 the bindings returned from each evaluation. This function is
152 useful in LocalFunctionHandler, see section Local Function Han‐
153 dler in this module.
154 Returns {ValueList, NewBindings}.
156 exprs(Expressions, Bindings) -> {value, Value, NewBindings}
158 exprs(Expressions, Bindings, LocalFunctionHandler) ->
160 {value, Value, NewBindings}
161 exprs(Expressions, Bindings, LocalFunctionHandler,
163 NonLocalFunctionHandler) ->
164 {value, Value, NewBindings}
165 Types:
167 Expressions = expressions()
169 Bindings = binding_struct()
170 LocalFunctionHandler = local_function_handler()
171 NonLocalFunctionHandler = non_local_function_handler()
172 Value = value()
173 NewBindings = binding_struct()
174 Evaluates Expressions with the set of bindings Bindings, where
176 Expressions is a sequence of expressions (in abstract syntax) of
177 a type that can be returned by io:parse_erl_exprs/2. For an ex‐
178 planation of when and how to use arguments LocalFunctionHandler
179 and NonLocalFunctionHandler, see sections Local Function Han‐
180 dler and Non-Local Function Handler in this module.
181 Returns {value, Value, NewBindings}
183 new_bindings() -> binding_struct()
185 Returns an empty binding structure.
187
189 During evaluation of a function, no calls can be made to local func‐
190 tions. An undefined function error would be generated. However, the op‐
191 tional argument LocalFunctionHandler can be used to define a function
192 that is called when there is a call to a local function. The argument
193 can have the following formats:
194 {value,Func}:
196 This defines a local function handler that is called with:
197 Func(Name, Arguments)
199 Name is the name of the local function (an atom) and Arguments is a
201 list of the evaluated arguments. The function handler returns the
202 value of the local function. In this case, the current bindings
203 cannot be accessed. To signal an error, the function handler calls
204 exit/1 with a suitable exit value.
205 {eval,Func}:
207 This defines a local function handler that is called with:
208 Func(Name, Arguments, Bindings)
210 Name is the name of the local function (an atom), Arguments is a
212 list of the unevaluated arguments, and Bindings are the current
213 variable bindings. The function handler returns:
214 {value,Value,NewBindings}
216 Value is the value of the local function and NewBindings are the
218 updated variable bindings. In this case, the function handler must
219 itself evaluate all the function arguments and manage the bindings.
220 To signal an error, the function handler calls exit/1 with a suit‐
221 able exit value.
222 none:
224 There is no local function handler.
225
227 The optional argument NonLocalFunctionHandler can be used to define a
228 function that is called in the following cases:
229 * A functional object (fun) is called.
231 * A built-in function is called.
233 * A function is called using the M:F syntax, where M and F are atoms
235 or expressions.
236 * An operator Op/A is called (this is handled as a call to function
238 erlang:Op/A).
239 Exceptions are calls to erlang:apply/2,3; neither of the function han‐
241 dlers are called for such calls. The argument can have the following
242 formats:
243 {value,Func}:
245 This defines a non-local function handler that is called with:
246 Func(FuncSpec, Arguments)
248 FuncSpec is the name of the function on the form {Module,Function}
250 or a fun, and Arguments is a list of the evaluated arguments. The
251 function handler returns the value of the function. To signal an
252 error, the function handler calls exit/1 with a suitable exit
253 value.
254 none:
256 There is no non-local function handler.
257 Note:
259 For calls such as erlang:apply(Fun, Args) or erlang:apply(Module, Func‐
260 tion, Args), the call of the non-local function handler corresponding
261 to the call to erlang:apply/2,3 itself (Func({erlang, apply}, [Fun,
262 Args]) or Func({erlang, apply}, [Module, Function, Args])) never takes
263 place.
264 The non-local function handler is however called with the evaluated ar‐
266 guments of the call to erlang:apply/2,3: Func(Fun, Args) or Func({Mod‐
267 ule, Function}, Args) (assuming that {Module, Function} is not {erlang,
268 apply}).
269 Calls to functions defined by evaluating fun expressions "fun ... end"
271 are also hidden from non-local function handlers.
272 The non-local function handler argument is probably not used as fre‐
275 quently as the local function handler argument. A possible use is to
276 call exit/1 on calls to functions that for some reason are not allowed
277 to be called.
278
280 Undocumented functions in this module are not to be used.
281Ericsson AB stdlib 3.16.1 erl_eval(3)