# erl_eval

### MODULE

erl_eval

### MODULE SUMMARY

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.

### AUTHORS

Robert Virding - support@erlang.ericsson.se

stdlib 1.10.1
Copyright © 1991-2002 Ericsson Utvecklings AB