--- name: "erl_eval" section: "3erl" platform: "linux" package: "erlang-manpages" version: "1:25.2.3+dfsg-1+deb12u4" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/erl_eval" --- # erl\_eval(3erl) The Erlang meta interpreter. ## 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() | map() ``` A binding structure. It is either a *map* or an *orddict*. *erl\_eval* will always return the same type as the one given. ``` 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()) | fun((Anno :: erl_anno:anno(), 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*. *Expression* is an expression in abstract syntax. For an explanation of when and how to use arguments *LocalFunctionHandler* and *NonLocalFunctionHandler*, 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 initial 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 Handler 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 explanation of when and how to use arguments *LocalFunctionHandler* and *NonLocalFunctionHandler*, see sections Local Function Handler 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 functions. An undefined function error would be generated. However, the optional 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 suitable 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 handlers are called for such calls. The argument can have the following formats: - ***{value,Func}*:** This defines a non-local function handler. The function may be called with two arguments: ``` Func(FuncSpec, Arguments) ``` or three arguments: ``` Func(Anno, FuncSpec, Arguments) ``` *Anno* is the *erl\_anno:anno()* of the node, *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, 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\])*) never takes place. The non-local function handler *is* however 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 non-local 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. ## KNOWN LIMITATION Undocumented functions in this module are not to be used.