View Source erl_eval (stdlib v6.0)

The Erlang meta interpreter.

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.

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.

Summary

Types

A binding structure. It is either a map or an orddict. erl_eval will always return the same type as the one given.

Further described in section Local Function Handler in this module

Further described in section Non-Local Function Handler in this module.

Functions

Adds binding Name=Value to BindingStruct. Returns an updated binding structure.

Returns the binding of Name in BindingStruct.

Returns the list of bindings contained in the binding structure.

Removes the binding of Name in BindingStruct. Returns an updated binding structure.

Evaluates Expression with the set of bindings Bindings. Expression is an expression in abstract syntax.

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.

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.

Returns an empty binding structure.

Types

-type 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.

Link to this type

bindings()

View Source (not exported)
-type bindings() :: [{name(), value()}].
Link to this type

expression()

View Source (not exported)
-type expression() :: erl_parse:abstract_expr().
Link to this type

expression_list()

View Source (not exported)
-type expression_list() :: [expression()].
Link to this type

expressions()

View Source (not exported)
-type expressions() :: [erl_parse:abstract_expr()].

As returned by erl_parse:parse_exprs/1 or io:parse_erl_exprs/2.

Link to this type

func_spec()

View Source (not exported)
-type func_spec() :: {Module :: module(), Function :: atom()} | function().
Link to this type

lfun_eval_handler()

View Source (not exported)
-type lfun_eval_handler() ::
    fun((Name :: atom(), Arguments :: expression_list(), Bindings :: binding_struct()) ->
            {value, Value :: value(), NewBindings :: binding_struct()}).
Link to this type

lfun_value_handler()

View Source (not exported)
-type lfun_value_handler() :: fun((Name :: atom(), Arguments :: [term()]) -> Value :: value()).
Link to this type

local_function_handler()

View Source (not exported)
-type local_function_handler() :: {value, lfun_value_handler()} | {eval, lfun_eval_handler()} | none.

Further described in section Local Function Handler in this module

-type name() :: term().
Link to this type

nlfun_handler()

View Source (not exported)
-type nlfun_handler() ::
    fun((FuncSpec :: func_spec(), Arguments :: [term()]) -> term()) |
    fun((Anno :: erl_anno:anno(), FuncSpec :: func_spec(), Arguments :: [term()]) -> term()).
Link to this type

non_local_function_handler()

View Source (not exported)
-type non_local_function_handler() :: {value, nlfun_handler()} | none.

Further described in section Non-Local Function Handler in this module.

Link to this type

value()

View Source (not exported)
-type value() :: term().

Functions

Link to this function

add_binding(Name, Value, BindingStruct)

View Source
-spec add_binding(Name, Value, BindingStruct) -> binding_struct()
               when Name :: name(), Value :: value(), BindingStruct :: binding_struct().

Adds binding Name=Value to BindingStruct. Returns an updated binding structure.

Link to this function

binding(Name, BindingStruct)

View Source
-spec binding(Name, BindingStruct) -> {value, value()} | unbound
           when Name :: name(), BindingStruct :: binding_struct().

Returns the binding of Name in BindingStruct.

-spec bindings(BindingStruct :: binding_struct()) -> bindings().

Returns the list of bindings contained in the binding structure.

Link to this function

del_binding(Name, BindingStruct)

View Source
-spec del_binding(Name, BindingStruct) -> binding_struct()
               when Name :: name(), BindingStruct :: binding_struct().

Removes the binding of Name in BindingStruct. Returns an updated binding structure.

Link to this function

expr(Expression, Bindings)

View Source
-spec expr(Expression, Bindings) -> {value, Value, NewBindings}
        when
            Expression :: expression(),
            Bindings :: binding_struct(),
            Value :: value(),
            NewBindings :: binding_struct().

Equivalent to expr(Expression, Bindings, none).

Link to this function

expr(Expression, Bindings, LocalFunctionHandler)

View Source
-spec expr(Expression, Bindings, LocalFunctionHandler) -> {value, Value, NewBindings}
        when
            Expression :: expression(),
            Bindings :: binding_struct(),
            LocalFunctionHandler :: local_function_handler(),
            Value :: value(),
            NewBindings :: binding_struct().

Equivalent to expr(Expression, Bindings, LocalFunctionHandler, none).

Link to this function

expr(Expression, Bindings, LocalFunctionHandler, NonLocalFunctionHandler)

View Source
-spec expr(Expression, Bindings, LocalFunctionHandler, NonLocalFunctionHandler) ->
        {value, Value, NewBindings}
        when
            Expression :: expression(),
            Bindings :: binding_struct(),
            LocalFunctionHandler :: local_function_handler(),
            NonLocalFunctionHandler :: non_local_function_handler(),
            Value :: value(),
            NewBindings :: binding_struct().

Equivalent to expr(Expression, Bindings, LocalFunctionHandler, NonLocalFunctionHandler, none).

Link to this function

expr(Expression, Bindings, LocalFunctionHandler, NonLocalFunctionHandler, ReturnFormat)

View Source
-spec expr(Expression, Bindings, LocalFunctionHandler, NonLocalFunctionHandler, ReturnFormat) ->
        {value, Value, NewBindings} | Value
        when
            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.

Link to this function

expr_list(ExpressionList, Bindings)

View Source
-spec expr_list(ExpressionList, Bindings) -> {ValueList, NewBindings}
             when
                 ExpressionList :: expression_list(),
                 Bindings :: binding_struct(),
                 ValueList :: [value()],
                 NewBindings :: binding_struct().

Equivalent to expr_list(ExpressionList, Bindings, none).

Link to this function

expr_list(ExpressionList, Bindings, LocalFunctionHandler)

View Source
-spec expr_list(ExpressionList, Bindings, LocalFunctionHandler) -> {ValueList, NewBindings}
             when
                 ExpressionList :: expression_list(),
                 Bindings :: binding_struct(),
                 LocalFunctionHandler :: local_function_handler(),
                 ValueList :: [value()],
                 NewBindings :: binding_struct().

Equivalent to expr_list(ExpressionList, Bindings, LocalFunctionHandler, none).

Link to this function

expr_list(ExpressionList, Bindings, LocalFunctionHandler, NonLocalFunctionHandler)

View Source
-spec expr_list(ExpressionList, Bindings, LocalFunctionHandler, NonLocalFunctionHandler) ->
             {ValueList, NewBindings}
             when
                 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}.

Link to this function

exprs(Expressions, Bindings)

View Source
-spec exprs(Expressions, Bindings) -> {value, Value, NewBindings}
         when
             Expressions :: expressions(),
             Bindings :: binding_struct(),
             Value :: value(),
             NewBindings :: binding_struct().

Equivalent to exprs(Expressions, Bindings, none).

Link to this function

exprs(Expressions, Bindings, LocalFunctionHandler)

View Source
-spec exprs(Expressions, Bindings, LocalFunctionHandler) -> {value, Value, NewBindings}
         when
             Expressions :: expressions(),
             Bindings :: binding_struct(),
             LocalFunctionHandler :: local_function_handler(),
             Value :: value(),
             NewBindings :: binding_struct().

Equivalent to exprs(Expressions, Bindings, LocalFunctionHandler, none).

Link to this function

exprs(Expressions, Bindings, LocalFunctionHandler, NonLocalFunctionHandler)

View Source
-spec exprs(Expressions, Bindings, LocalFunctionHandler, NonLocalFunctionHandler) ->
         {value, Value, NewBindings}
         when
             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}

-spec new_bindings() -> binding_struct().

Returns an empty binding structure.