File: erl_eval.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (348 lines) | stat: -rw-r--r-- 9,955 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>erl_eval</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>erl_eval</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
erl_eval
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
The Erlang Meta Interpreter
</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P>This module provides an interpreter for Erlang expressions. The
expressions are in the abstract syntax as returned by
<CODE>erl_parse</CODE>, the Erlang parser, or a call to
<CODE>io:parse_erl_exprs/2</CODE>.

</DIV>

<H3>EXPORTS</H3>

<P><A NAME="exprs/2"><STRONG><CODE>exprs(Expressions, Bindings) -&#62; {value, Value, NewBindings}</CODE></STRONG></A><BR>
<A NAME="exprs/3"><STRONG><CODE>exprs(Expressions, Bindings, LocalFunctionHandler) -&#62; 
{value, Value, NewBindings}</CODE></STRONG></A><BR>
<A NAME="exprs/4"><STRONG><CODE>exprs(Expressions, Bindings, LocalFunctionHandler, 
NonlocalFunctionHandler) -&#62; {value, Value, NewBindings}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Expressions = as returned by erl_parse or io:parse_erl_exprs/2</CODE></STRONG><BR>
<STRONG><CODE>Bindings = as returned by bindings/1</CODE></STRONG><BR>
<STRONG><CODE>LocalFunctionHandler = {value, Func} | {eval, Func} | none</CODE></STRONG><BR>
<STRONG><CODE>NonlocalFunctionHandler = {value, Func} | none</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Evaluates <CODE>Expressions</CODE> with the set of bindings
<CODE>Bindings</CODE>, where <CODE>Expressions</CODE> is a sequence of
expressions (in abstract syntax) of a type which may be
returned by <CODE>io:parse_erl_exprs/2</CODE>. See below for an
explanation of how and when to use the arguments
<CODE>LocalFunctionHandler</CODE> and <CODE>NonlocalFunctionHandler</CODE>.


<P>Returns <CODE>{value, Value, NewBindings}</CODE>

</DIV>

<P><A NAME="expr/2"><STRONG><CODE>expr(Expression, Bindings) -&#62; { value, Value, NewBindings }</CODE></STRONG></A><BR>
<A NAME="expr/3"><STRONG><CODE>expr(Expression, Bindings, LocalFunctionHandler) -&#62; 
{ value, Value, NewBindings }</CODE></STRONG></A><BR>
<A NAME="expr/4"><STRONG><CODE>expr(Expression, Bindings, LocalFunctionHandler, 
NonlocalFunctionHandler) -&#62; { value, Value, NewBindings }</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Expression = as returned by io:parse_erl_form/2, for example</CODE></STRONG><BR>
<STRONG><CODE>Bindings = as returned by bindings/1</CODE></STRONG><BR>
<STRONG><CODE>LocalFunctionHandler = {value, Func} | {eval, Func} | none</CODE></STRONG><BR>
<STRONG><CODE>NonlocalFunctionHandler = {value, Func} | none</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

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


<P>Returns <CODE>{value, Value, NewBindings}</CODE>.

</DIV>

<P><A NAME="expr_list/2"><STRONG><CODE>expr_list(ExpressionList, Bindings) -&#62; 
{ValueList, NewBindings}</CODE></STRONG></A><BR>
<A NAME="expr_list/3"><STRONG><CODE>expr_list(ExpressionList, Bindings, LocalFunctionHandler) -&#62; 
{ValueList, NewBindings}</CODE></STRONG></A><BR>
<A NAME="expr_list/4"><STRONG><CODE>expr_list(ExpressionList, Bindings, LocalFunctionHandler, 
NonlocalFunctionHandler) -&#62; {ValueList, NewBindings}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>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 <CODE>LocalFunctionHandler</CODE>. See below.


<P>Returns <CODE>{ValueList, NewBindings}</CODE>.

</DIV>

<P><A NAME="new_bindings/0"><STRONG><CODE>new_bindings() -&#62; BindingStruct</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns an empty binding structure.

</DIV>

<P><A NAME="bindings/1"><STRONG><CODE>bindings(BindingStruct) -&#62; Bindings</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns the list of bindings contained in the binding
structure.

</DIV>

<P><A NAME="binding/2"><STRONG><CODE>binding(Name, BindingStruct) -&#62; Binding</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Returns the binding of <CODE>Name</CODE> in <CODE>BindingStruct</CODE>.

</DIV>

<P><A NAME="add_binding/3"><STRONG><CODE>add_binding(Name, Value, Bindings) -&#62; BindingStruct</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Adds the binding <CODE>Name = Value</CODE> to <CODE>Bindings</CODE>.
Returns an updated binding structure.

</DIV>

<P><A NAME="del_binding/2"><STRONG><CODE>del_binding(Name, Bindings) -&#62; BindingStruct</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Removes the binding of <CODE>Name</CODE> in <CODE>Bindings</CODE>.
Returns an updated binding structure.

</DIV>

<H3>Local Function Handler</H3>
<DIV CLASS=REFBODY>

<P>During evaluation of a function, no calls can be made to local
functions. An undefined function error would be
generated. However, the optional argument
<CODE>LocalFunctionHandler</CODE> 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:

<P>
<DL>

<DT>
<CODE>{value,Func}</CODE>
</DT>

<DD>
 This defines a local function handler which is called with:<BR>

<PRE>
Func(Name, Arguments)
</PRE>

<CODE>Name</CODE> is the name of the local function (an atom) and
<CODE>Arguments</CODE> is a list of the <STRONG>evaluated</STRONG>
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 <CODE>exit/1</CODE> with a suitable exit value.
<BR>

</DD>

<DT>
<CODE>{eval,Func}</CODE>
</DT>

<DD>
 This defines a local function handler which is called with:<BR>

<PRE>
Func(Name, Arguments, Bindings)
</PRE>

<CODE>Name</CODE> is the name of the local function (an atom),
<CODE>Arguments</CODE> is a list of the <STRONG>unevaluated</STRONG>
arguments, and <CODE>Bindings</CODE> are the current variable
bindings. The function handler returns:<BR>

<PRE>
{value,Value,NewBindings}
</PRE>

<CODE>Value</CODE> is the value of the local function and
<CODE>NewBindings</CODE> 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 <CODE>exit/1</CODE> with a
suitable exit value.
<BR>

</DD>

<DT>
<CODE>none</CODE>
</DT>

<DD>
There is no local function handler.
<BR>

</DD>

</DL>

</DIV>

<H3>Non-local Function Handler</H3>
<DIV CLASS=REFBODY>

<P>The optional argument <CODE>NonlocalFunctionHandler</CODE> 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. Exceptions are function calls in
guard tests and calls to <CODE>erlang:apply/2,3</CODE>; neither of the
function handlers will be called for such calls. 
The argument can have the following formats:

<P>
<DL>

<DT>
<CODE>{value,Func}</CODE>
</DT>

<DD>
This defines an nonlocal function handler which is called with:<BR>

<PRE>
Func(FuncSpec, Arguments)
</PRE>

<CODE>FuncSpec</CODE> is the name of the function on the form
<CODE>{Module,Function}</CODE> or a fun, and <CODE>Arguments</CODE> is a
list of the <STRONG>evaluated</STRONG> arguments. The function
handler returns the value of the function. To
signal an error, the function handler just calls
<CODE>exit/1</CODE> with a suitable exit value.
<BR>

</DD>

<DT>
<CODE>none</CODE>
</DT>

<DD>
There is no nonlocal function handler.
<BR>

</DD>

</DL>

<P>
<TABLE CELLPADDING=4>
  <TR>
    <TD VALIGN=TOP><IMG ALT="Note!" SRC="note.gif"></TD>
    <TD>

<P>For calls such as <CODE>erlang:apply(Fun, Args)</CODE> or
<CODE>erlang:apply(Module, Function, Args)</CODE> the call of the
non-local function handler corresponding to the call to
<CODE>erlang:apply/2,3</CODE> itself--<CODE>Func({erlang, apply}, [Fun,
Args])</CODE> or <CODE>Func({erlang, apply}, [Module, Function,
Args])</CODE>--will never take place. The non-local function
handler <STRONG>will</STRONG> however be called with the evaluated
arguments of the call to <CODE>erlang:apply/2,3</CODE>: <CODE>Func(Fun,
Args)</CODE> or <CODE>Func({Module, Function}, Args)</CODE> (assuming
that <CODE>{Module, Function}</CODE> is not <CODE>{erlang,
apply}</CODE>).    </TD>
  </TR>
</TABLE>

<P>The nonlocal function handler argument is probably not used as
frequently as the local function handler argument. A possible
use is to call <CODE>exit/1</CODE> on calls to functions that for some
reason are not allowed to be called.
</DIV>

<H3>Bugs</H3>
<DIV CLASS=REFBODY>

<P>The evaluator is not complete. <CODE>receive</CODE> cannot be
handled properly.


<P>Any undocumented functions in <CODE>erl_eval</CODE> should not be used.

</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Robert Virding - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>stdlib 1.14.2<BR>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>