erl_eval(3erl)						     Erlang Module Definition						    erl_eval(3erl)

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

EXPORTS

       exprs(Expressions, Bindings) -> {value, Value, NewBindings}
       exprs(Expressions, Bindings, LocalFunctionHandler) -> {value, Value, NewBindings}
       exprs(Expressions, Bindings, LocalFunctionHandler, NonlocalFunctionHandler) -> {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
		     NonlocalFunctionHandler = {value, 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 arguments LocalFunc-
	      tionHandler and NonlocalFunctionHandler .

	      Returns {value, Value, NewBindings}

       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 = as returned by io:parse_erl_form/2, for example
		     Bindings = as returned by bindings/1
		     LocalFunctionHandler = {value, Func} | {eval, Func} | none
		     NonlocalFunctionHandler = {value, Func} | none
		     ReturnFormat = value | 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 arguments LocalFunctionHandler and Nonlo-
	      calFunctionHandler .

	      Returns {value, Value, NewBindings} by default. But if the ReturnFormat is value only the Value is returned.

       expr_list(ExpressionList, Bindings) -> {ValueList, NewBindings}
       expr_list(ExpressionList, Bindings, LocalFunctionHandler) -> {ValueList, NewBindings}
       expr_list(ExpressionList, Bindings, LocalFunctionHandler, NonlocalFunctionHandler) -> {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 argu-
       ment 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 (an atom) 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 (an atom), Arguments is a list of the unevaluated arguments, and Bindings are the current vari-
	   able 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.

NON-LOCAL FUNCTION HANDLER
       The optional argument NonlocalFunctionHandler may be used to define a function which 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 oper-
       ator Op/A is called (this is handled as a call to the function erlang:Op/A ). Exceptions are calls to erlang:apply/2,3  ;  neither  of  the
       function handlers will be called for such calls. The argument can have the following formats:

	 {value,Func} :
	   This defines an nonlocal function handler which is called with:

	 Func(FuncSpec, Arguments)

	   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 just calls exit/1  with  a  suitable  exit
	   value.

	 none :
	   There is no nonlocal 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]) --will never
       take  place. The non-local function handler will however be 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 nonlocal 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.

BUGS

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

       Any undocumented functions in erl_eval should not be used.

Ericsson AB							   stdlib 1.17.3						    erl_eval(3erl)