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, Bindings, LocalFunctionHandler,
104 NonLocalFunctionHandler) ->
105 {value, Value, NewBindings}
106 expr(Expression, Bindings, LocalFunctionHandler,
108 NonLocalFunctionHandler, ReturnFormat) ->
109 {value, Value, NewBindings} | Value
110 Types:
112 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 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 Returns {value, Value, NewBindings} by default. If ReturnFormat
128 is value, only Value is returned.
129 expr_list(ExpressionList, Bindings) -> {ValueList, NewBindings}
131 expr_list(ExpressionList, Bindings, LocalFunctionHandler) ->
133 {ValueList, NewBindings}
134 expr_list(ExpressionList, Bindings, LocalFunctionHandler,
136 NonLocalFunctionHandler) ->
137 {ValueList, NewBindings}
138 Types:
140 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 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 Returns {ValueList, NewBindings}.
155 exprs(Expressions, Bindings) -> {value, Value, NewBindings}
157 exprs(Expressions, Bindings, LocalFunctionHandler) ->
159 {value, Value, NewBindings}
160 exprs(Expressions, Bindings, LocalFunctionHandler,
162 NonLocalFunctionHandler) ->
163 {value, Value, NewBindings}
164 Types:
166 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 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 Returns {value, Value, NewBindings}
182 new_bindings() -> binding_struct()
184 Returns an empty binding structure.
186
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 {value,Func}:
195 This defines a local function handler that is called with:
196 Func(Name, Arguments)
198 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 {eval,Func}:
206 This defines a local function handler that is called with:
207 Func(Name, Arguments, Bindings)
209 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 {value,Value,NewBindings}
215 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 none:
223 There is no local function handler.
224
226 The optional argument NonLocalFunctionHandler can be used to define a
227 function that is called in the following cases:
228 * A functional object (fun) is called.
230 * A built-in function is called.
232 * A function is called using the M:F syntax, where M and F are atoms
234 or expressions.
235 * An operator Op/A is called (this is handled as a call to function
237 erlang:Op/A).
238 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 {value,Func}:
244 This defines a non-local function handler that is called with:
245 Func(FuncSpec, Arguments)
247 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 none:
255 There is no non-local function handler.
256 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 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 Calls to functions defined by evaluating fun expressions "fun ... end"
270 are also hidden from non-local function handlers.
271 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
279 Undocumented functions in this module are not to be used.
280Ericsson AB stdlib 3.10 erl_eval(3)