Search documentation of stdlib

# erl_eval (stdlib v7.3)

Copy Markdown View Source

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 of 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

binding_struct()

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

bindings()
expression()
expression_list()
expressions()

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

func_spec()
lfun_eval_handler()
lfun_value_handler()
local_function_handler()

Further described in section Local Function Handler in this module

name()
nlfun_handler()
non_local_function_handler()

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

value()

### Functions

add_binding(Name, Value, BindingStruct)

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

binding(Name, BindingStruct)

Returns the binding of `Name` in `BindingStruct`.

bindings(BindingStruct)

Returns the list of bindings contained in the binding structure.

del_binding(Name, BindingStruct)

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

expr(Expression, Bindings)

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

expr(Expression, Bindings, LocalFunctionHandler)

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

expr(Expression, Bindings, LocalFunctionHandler, NonLocalFunctionHandler)

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

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

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

expr_list(ExpressionList, Bindings)

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

expr_list(ExpressionList, Bindings, LocalFunctionHandler)

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

expr_list(ExpressionList, Bindings, LocalFunctionHandler, NonLocalFunctionHandler)

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.

exprs(Expressions, Bindings)

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

exprs(Expressions, Bindings, LocalFunctionHandler)

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

exprs(Expressions, Bindings, LocalFunctionHandler, NonLocalFunctionHandler)

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

new_bindings()

Returns an empty binding structure.

## Types

# binding_struct()

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

# bindings()

(not exported)

    -type bindings() :: [{name(), value()}].

# expression()

(not exported)

    -type expression() :: erl_parse:abstract_expr().

# expression_list()

(not exported)

    -type expression_list() :: [expression()].

# expressions()

(not exported)

    -type expressions() :: [erl_parse:abstract_expr()].

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

# func_spec()

(not exported)

    -type func_spec() :: {Module :: module(), Function :: atom()} | function().

# lfun_eval_handler()

(not exported)

    -type lfun_eval_handler() ::
              fun((Name :: atom(), Arguments :: expression_list(), Bindings :: binding_struct()) ->
                      {value, Value :: value(), NewBindings :: binding_struct()}).

# lfun_value_handler()

(not exported)

    -type lfun_value_handler() :: fun((Name :: atom(), Arguments :: [term()]) -> Value :: value()).

# local_function_handler()

(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

# name()

(not exported)

    -type name() :: term().

# nlfun_handler()

(not exported)

    -type nlfun_handler() ::
              fun((FuncSpec :: func_spec(), Arguments :: [term()]) -> term()) |
              fun((Anno :: erl_anno:anno(), FuncSpec :: func_spec(), Arguments :: [term()]) -> term()).

# non_local_function_handler()

(not exported)

    -type non_local_function_handler() :: {value, nlfun_handler()} | none.

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

# value()

(not exported)

    -type value() :: term().

## Functions

# add_binding(Name, Value, BindingStruct)

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

# binding(Name, BindingStruct)

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

Returns the binding of `Name` in `BindingStruct`.

# bindings(BindingStruct)

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

Returns the list of bindings contained in the binding structure.

# del_binding(Name, BindingStruct)

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

# expr(Expression, Bindings)

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

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

# expr(Expression, Bindings, LocalFunctionHandler)

    -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)`.

# expr(Expression, Bindings, LocalFunctionHandler, NonLocalFunctionHandler)

    -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)`.

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

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

# expr_list(ExpressionList, Bindings)

    -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)`.

# expr_list(ExpressionList, Bindings, LocalFunctionHandler)

    -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)`.

# expr_list(ExpressionList, Bindings, LocalFunctionHandler, NonLocalFunctionHandler)

    -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}`.

# exprs(Expressions, Bindings)

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

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

# exprs(Expressions, Bindings, LocalFunctionHandler)

    -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)`.

# exprs(Expressions, Bindings, LocalFunctionHandler, NonLocalFunctionHandler)

    -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}`

# new_bindings()

    -spec new_bindings() -> binding_struct().

Returns an empty binding structure.