erl_eval(3)

MODULE
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 a call to io:parse_erl_exprs/2.

EXPORTS

exprs(Expressions, Bindings) -> {value, Value, NewBindings}
exprs(Expressions, Bindings, LocalFunctionHandler) -> {value, Value, NewBindings}

    Types
        Expressions = as returned by erl_parse or io:parse_erl_exprs/2
        Bindings = as returned by bindings/1
        LocalFunctionHandler = {value, Func} | {eval, Func} | none

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

    Returns {value, Value, NewBindings}

expr(Expression, Bindings) -> { value, Value, NewBindings }
expr(Expression, Bindings, LocalFunctionHandler) -> { value, Value, NewBindings }

    Types
        Expression = as returned by io:parse_erl_form/2, for example
        Bindings = as returned by bindings/1
        LocalFunctionHandler = {value, Func} | {eval, Func} | none

    Evaluates Expression with the set of bindings Bindings. Expression is an expression (in abstract syntax) of a type which may be returned by io:parse_erl_form/2. See below for an explanation of how and when to use the argument LocalFunctionHandler.

    Returns {value, Value, NewBindings}.

expr_list(ExpressionList, Bindings) -> {ValueList, NewBindings}
expr_list(ExpressionList, Bindings, LocalFunctionHandler) -> {ValueList, NewBindings}

    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() -> BindingStruct

    Returns an empty binding structure.

bindings(BindingStruct) -> Bindings

    Returns the list of bindings contained in the binding structure.

binding(Name, BindingStruct) -> Binding

    Returns the binding of Name in BindingStruct.

add_binding(Name, Value, Bindings) -> BindingStruct

    Adds the binding Name = Value to Bindings. Returns an updated binding structure.

del_binding(Name, Bindings) -> BindingStruct

    Removes the binding of Name in Bindings. 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 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, 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.

Bugs

The evaluator is not complete. receive cannot be handled properly.

Any undocumented functions in erl_eval should not be used.

AUTHOR
Robert Virding - rv@erix.ericsson.se