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()
17 A binding structure.
19 expression() = erl_parse:abstract_expr()
21 expressions() = [erl_parse:abstract_expr()]
23 As returned by erl_parse:parse_exprs/1 or io:parse_erl_exprs/2.
25 expression_list() = [expression()]
27 func_spec() =
29 {Module :: module(), Function :: atom()} | function()
30 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 lfun_value_handler() =
40 fun((Name :: atom(), Arguments :: [term()]) ->
41 Value :: value())
42 local_function_handler() =
44 {value, lfun_value_handler()} |
45 {eval, lfun_eval_handler()} |
46 none
47 Further described in section Local Function Handler in this
49 module
50 name() = term()
52 nlfun_handler() =
54 fun((FuncSpec :: func_spec(), Arguments :: [term()]) -> term())
55 non_local_function_handler() = {value, nlfun_handler()} | none
57 Further described in section Non-Local Function Handler in this
59 module.
60 value() = term()
62
64 add_binding(Name, Value, BindingStruct) -> binding_struct()
65 Types:
67 Name = name()
69 Value = value()
70 BindingStruct = binding_struct()
71 Adds binding Name=Value to BindingStruct. Returns an updated
73 binding structure.
74 binding(Name, BindingStruct) -> {value, value()} | unbound
76 Types:
78 Name = name()
80 BindingStruct = binding_struct()
81 Returns the binding of Name in BindingStruct.
83 bindings(BindingStruct :: binding_struct()) -> bindings()
85 Returns the list of bindings contained in the binding structure.
87 del_binding(Name, BindingStruct) -> binding_struct()
89 Types:
91 Name = name()
93 BindingStruct = binding_struct()
94 Removes the binding of Name in BindingStruct. Returns an updated
96 binding structure.
97 expr(Expression, Bindings) -> {value, Value, NewBindings}
99 expr(Expression, Bindings, LocalFunctionHandler) ->
101 {value, Value, NewBindings}
102 expr(Expression,
104 Bindings,
105 LocalFunctionHandler,
106 NonLocalFunctionHandler) ->
107 {value, Value, NewBindings}
108 expr(Expression,
110 Bindings,
111 LocalFunctionHandler,
112 NonLocalFunctionHandler,
113 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,
141 Bindings,
142 LocalFunctionHandler,
143 NonLocalFunctionHandler) ->
144 {ValueList, NewBindings}
145 Types:
147 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 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 Returns {ValueList, NewBindings}.
162 exprs(Expressions, Bindings) -> {value, Value, NewBindings}
164 exprs(Expressions, Bindings, LocalFunctionHandler) ->
166 {value, Value, NewBindings}
167 exprs(Expressions,
169 Bindings,
170 LocalFunctionHandler,
171 NonLocalFunctionHandler) ->
172 {value, Value, NewBindings}
173 Types:
175 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 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 Returns {value, Value, NewBindings}
191 new_bindings() -> binding_struct()
193 Returns an empty binding structure.
195
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 {value,Func}:
204 This defines a local function handler that is called with:
205 Func(Name, Arguments)
207 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 {eval,Func}:
215 This defines a local function handler that is called with:
216 Func(Name, Arguments, Bindings)
218 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 {value,Value,NewBindings}
224 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 none:
232 There is no local function handler.
233
235 The optional argument NonLocalFunctionHandler can be used to define a
236 function that is called in the following cases:
237 * A functional object (fun) is called.
239 * A built-in function is called.
241 * A function is called using the M:F syntax, where M and F are atoms
243 or expressions.
244 * An operator Op/A is called (this is handled as a call to function
246 erlang:Op/A).
247 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 {value,Func}:
253 This defines a non-local function handler that is called with:
254 Func(FuncSpec, Arguments)
256 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 none:
264 There is no non-local function handler.
265 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 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 Calls to functions defined by evaluating fun expressions "fun ... end"
279 are also hidden from non-local function handlers.
280 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
288 Undocumented functions in this module are not to be used.
289Ericsson AB stdlib 3.8.2.1 erl_eval(3)