Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2.2_all 
NAME
erl_eval - The Erlang Meta Interpreter
DESCRIPTION
This module provides an interpreter for Erlang expressions. The expressions 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 below.
name() = term()
nlfun_handler() =
fun((FuncSpec :: func_spec(), Arguments :: [term()]) -> term())
non_local_function_handler() = {value, nlfun_handler()} | none
Further described below.
value() = term()
EXPORTS
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 which may be returned by
io:parse_erl_exprs/2. See below for an explanation of how and when to use the
arguments LocalFunctionHandler and NonLocalFunctionHandler.
Returns {value, Value, NewBindings}
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. Expression is an expression
in abstract syntax. See below for an explanation of how and when to use the
arguments LocalFunctionHandler and NonLocalFunctionHandler.
Returns {value, Value, NewBindings} by default. But if the ReturnFormat is value
only the 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 initial bindings for
each expression. Attempts are made to merge the bindings returned from each
evaluation. This function is useful in the LocalFunctionHandler. See below.
Returns {ValueList, NewBindings}.
new_bindings() -> binding_struct()
Returns an empty binding structure.
bindings(BindingStruct :: binding_struct()) -> bindings()
Returns the list of bindings contained in the binding structure.
binding(Name, BindingStruct) -> {value, value()} | unbound
Types:
Name = name()
BindingStruct = binding_struct()
Returns the binding of Name in BindingStruct.
add_binding(Name, Value, BindingStruct) -> binding_struct()
Types:
Name = name()
Value = value()
BindingStruct = binding_struct()
Adds the binding Name = Value to BindingStruct. Returns an updated 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.
LOCAL FUNCTION HANDLER
During evaluation of a function, no calls can be made to local functions. An undefined
function error would be generated. However, the optional argument LocalFunctionHandler may
be used to define a function which 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 which 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, it is not possible to access the current bindings. To signal an error, the
function handler just calls exit/1 with a suitable exit value.
{eval,Func}:
This defines a local function handler which 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 just calls
exit/1 with a suitable exit value.
none:
There is no local function handler.
NON-LOCAL FUNCTION HANDLER
The optional argument NonlocalFunctionHandler may be used to define a function which 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 the function erlang:Op/A).
Exceptions are calls to erlang:apply/2,3; neither of the function handlers will be called
for such calls. The argument can have the following formats:
{value,Func}:
This defines an nonlocal function handler which 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 just calls exit/1 with a
suitable exit value.
none:
There is no nonlocal function handler.
Note:
For calls such as erlang:apply(Fun, Args) or erlang:apply(Module, Function, 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])--will never take place. The non-local function handler will however be called with
the evaluated arguments of the call to erlang:apply/2,3: Func(Fun, Args) or Func({Module,
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 nonlocal function handler argument is probably not used as frequently 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.
BUGS
Undocumented functions in erl_eval should not be used.