erl_eval(3erl) Erlang Module Definition erl_eval(3erl)
NAME
erl_eval - The Erlang meta interpreter.
DESCRIPTION
This module provides an interpreter for Erlang expressions. The expres-
sions are in the abstract syntax as returned by erl_parse, the Erlang
parser, or io.
DATA TYPES
bindings() = [{name(), value()}]
binding_struct() = orddict:orddict()
A binding structure.
expression() = erl_parse:abstract_expr()
expressions() = [erl_parse:abstract_expr()]
As returned by erl_parse:parse_exprs/1 or io:parse_erl_exprs/2.
expression_list() = [expression()]
func_spec() =
{Module :: module(), Function :: atom()} | function()
lfun_eval_handler() =
fun((Name :: atom(),
Arguments :: expression_list(),
Bindings :: binding_struct()) ->
{value,
Value :: value(),
NewBindings :: binding_struct()})
lfun_value_handler() =
fun((Name :: atom(), Arguments :: [term()]) ->
Value :: value())
local_function_handler() =
{value, lfun_value_handler()} |
{eval, lfun_eval_handler()} |
none
Further described in section Local Function Handler in this
module
name() = term()
nlfun_handler() =
fun((FuncSpec :: func_spec(), Arguments :: [term()]) -> term())
non_local_function_handler() = {value, nlfun_handler()} | none
Further described in section Non-Local Function Handler in this
module.
value() = term()
EXPORTS
add_binding(Name, Value, BindingStruct) -> binding_struct()
Types:
Name = name()
Value = value()
BindingStruct = binding_struct()
Adds binding Name=Value to BindingStruct. Returns an updated
binding structure.
binding(Name, BindingStruct) -> {value, value()} | unbound
Types:
Name = name()
BindingStruct = binding_struct()
Returns the binding of Name in BindingStruct.
bindings(BindingStruct :: binding_struct()) -> bindings()
Returns the list of bindings contained in the binding structure.
del_binding(Name, BindingStruct) -> binding_struct()
Types:
Name = name()
BindingStruct = binding_struct()
Removes the binding of Name in BindingStruct. Returns an updated
binding structure.
expr(Expression, Bindings) -> {value, Value, NewBindings}
expr(Expression, Bindings, LocalFunctionHandler) ->
{value, Value, NewBindings}
expr(Expression, Bindings, LocalFunctionHandler,
NonLocalFunctionHandler) ->
{value, Value, NewBindings}
expr(Expression, Bindings, LocalFunctionHandler,
NonLocalFunctionHandler, ReturnFormat) ->
{value, Value, NewBindings} | Value
Types:
Expression = expression()
Bindings = binding_struct()
LocalFunctionHandler = local_function_handler()
NonLocalFunctionHandler = non_local_function_handler()
ReturnFormat = none | value
Value = value()
NewBindings = binding_struct()
Evaluates Expression with the set of bindings Bindings. Expres-
sion is an expression in abstract syntax. For an explanation of
when and how to use arguments LocalFunctionHandler and NonLocal-
FunctionHandler, see sections Local Function Handler and Non-
Local Function Handler in this module.
Returns {value, Value, NewBindings} by default. If ReturnFormat
is value, only Value is returned.
expr_list(ExpressionList, Bindings) -> {ValueList, NewBindings}
expr_list(ExpressionList, Bindings, LocalFunctionHandler) ->
{ValueList, NewBindings}
expr_list(ExpressionList, Bindings, LocalFunctionHandler,
NonLocalFunctionHandler) ->
{ValueList, NewBindings}
Types:
ExpressionList = expression_list()
Bindings = binding_struct()
LocalFunctionHandler = local_function_handler()
NonLocalFunctionHandler = non_local_function_handler()
ValueList = [value()]
NewBindings = binding_struct()
Evaluates a list of expressions in parallel, using the same ini-
tial bindings for each expression. Attempts are made to merge
the bindings returned from each evaluation. This function is
useful in LocalFunctionHandler, see section Local Function Han-
dler in this module.
Returns {ValueList, NewBindings}.
exprs(Expressions, Bindings) -> {value, Value, NewBindings}
exprs(Expressions, Bindings, LocalFunctionHandler) ->
{value, Value, NewBindings}
exprs(Expressions, Bindings, LocalFunctionHandler,
NonLocalFunctionHandler) ->
{value, Value, NewBindings}
Types:
Expressions = expressions()
Bindings = binding_struct()
LocalFunctionHandler = local_function_handler()
NonLocalFunctionHandler = non_local_function_handler()
Value = value()
NewBindings = binding_struct()
Evaluates Expressions with the set of bindings Bindings, where
Expressions is a sequence of expressions (in abstract syntax) of
a type that can be returned by io:parse_erl_exprs/2. For an ex-
planation of when and how to use arguments LocalFunctionHandler
and NonLocalFunctionHandler, see sections Local Function Han-
dler and Non-Local Function Handler in this module.
Returns {value, Value, NewBindings}
new_bindings() -> binding_struct()
Returns an empty binding structure.
LOCAL FUNCTION HANDLER
During evaluation of a function, no calls can be made to local func-
tions. An undefined function error would be generated. However, the op-
tional argument LocalFunctionHandler can be used to define a function
that is called when there is a call to a local function. The argument
can have the following formats:
{value,Func}:
This defines a local function handler that is called with:
Func(Name, Arguments)
Name is the name of the local function (an atom) and Arguments is a
list of the evaluated arguments. The function handler returns the
value of the local function. In this case, the current bindings
cannot be accessed. To signal an error, the function handler calls
exit/1 with a suitable exit value.
{eval,Func}:
This defines a local function handler that is called with:
Func(Name, Arguments, Bindings)
Name is the name of the local function (an atom), Arguments is a
list of the unevaluated arguments, and Bindings are the current
variable bindings. The function handler returns:
{value,Value,NewBindings}
Value is the value of the local function and NewBindings are the
updated variable bindings. In this case, the function handler must
itself evaluate all the function arguments and manage the bindings.
To signal an error, the function handler calls exit/1 with a suit-
able exit value.
none:
There is no local function handler.
NON-LOCAL FUNCTION HANDLER
The optional argument NonLocalFunctionHandler can be used to define a
function that is called in the following cases:
* A functional object (fun) is called.
* A built-in function is called.
* A function is called using the M:F syntax, where M and F are atoms
or expressions.
* An operator Op/A is called (this is handled as a call to function
erlang:Op/A).
Exceptions are calls to erlang:apply/2,3; neither of the function han-
dlers are called for such calls. The argument can have the following
formats:
{value,Func}:
This defines a non-local function handler that is called with:
Func(FuncSpec, Arguments)
FuncSpec is the name of the function on the form {Module,Function}
or a fun, and Arguments is a list of the evaluated arguments. The
function handler returns the value of the function. To signal an
error, the function handler calls exit/1 with a suitable exit
value.
none:
There is no non-local function handler.
Note:
For calls such as erlang:apply(Fun, Args) or erlang:apply(Module, Func-
tion, Args), the call of the non-local function handler corresponding
to the call to erlang:apply/2,3 itself (Func({erlang, apply}, [Fun,
Args]) or Func({erlang, apply}, [Module, Function, Args])) never takes
place.
The non-local function handler is however called with the evaluated ar-
guments of the call to erlang:apply/2,3: Func(Fun, Args) or Func({Mod-
ule, Function}, Args) (assuming that {Module, Function} is not {erlang,
apply}).
Calls to functions defined by evaluating fun expressions "fun ... end"
are also hidden from non-local function handlers.
The non-local function handler argument is probably not used as fre-
quently as the local function handler argument. A possible use is to
call exit/1 on calls to functions that for some reason are not allowed
to be called.
KNOWN LIMITATION
Undocumented functions in this module are not to be used.
Ericsson AB stdlib 3.13 erl_eval(3erl)