diff options
Diffstat (limited to 'lib/stdlib/doc/src/erl_eval.xml')
| -rw-r--r-- | lib/stdlib/doc/src/erl_eval.xml | 245 |
1 files changed, 134 insertions, 111 deletions
diff --git a/lib/stdlib/doc/src/erl_eval.xml b/lib/stdlib/doc/src/erl_eval.xml index d60b04b510..1c0f7f062f 100644 --- a/lib/stdlib/doc/src/erl_eval.xml +++ b/lib/stdlib/doc/src/erl_eval.xml @@ -28,19 +28,19 @@ <docno>1</docno> <approved>Bjarne Däcker</approved> <checked></checked> - <date>97-01-21</date> + <date>1997-01-21</date> <rev>B</rev> - <file>erl_eval.sgml</file> + <file>erl_eval.xml</file> </header> <module>erl_eval</module> - <modulesummary>The Erlang Meta Interpreter</modulesummary> + <modulesummary>The Erlang meta interpreter.</modulesummary> <description> <p>This module provides an interpreter for Erlang expressions. The expressions are in the abstract syntax as returned by <seealso marker="erl_parse"><c>erl_parse</c></seealso>, - the Erlang parser, or <seealso marker="io"> - <c>io</c></seealso>.</p> + the Erlang parser, or <seealso marker="io"><c>io</c></seealso>.</p> </description> + <datatypes> <datatype> <name name="bindings"/> @@ -73,9 +73,9 @@ </datatype> <datatype> <name name="local_function_handler"/> - <desc><p>Further described - <seealso marker="#local_function_handler">below.</seealso></p> - </desc> + <desc><p>Further described in section + <seealso marker="#local_function_handler"> + Local Function Handler</seealso> in this module</p></desc> </datatype> <datatype> <name name="name"/> @@ -85,152 +85,164 @@ </datatype> <datatype> <name name="non_local_function_handler"/> - <desc><p>Further described - <seealso marker="#non_local_function_handler">below.</seealso></p> - </desc> + <desc><p>Further described in section + <seealso marker="#non_local_function_handler"> + Non-Local Function Handler</seealso> in this module.</p></desc> </datatype> <datatype> <name name="value"/> </datatype> </datatypes> + <funcs> <func> - <name name="exprs" arity="2"/> - <name name="exprs" arity="3"/> - <name name="exprs" arity="4"/> - <fsummary>Evaluate expressions</fsummary> + <name name="add_binding" arity="3"/> + <fsummary>Add a binding.</fsummary> <desc> - <p>Evaluates <c><anno>Expressions</anno></c> with the set of bindings - <c><anno>Bindings</anno></c>, where <c><anno>Expressions</anno></c> - is a sequence of - expressions (in abstract syntax) of a type which may be - returned by <seealso marker="io#parse_erl_exprs/2"> - <c>io:parse_erl_exprs/2</c></seealso>. See below for an - explanation of how and when to use the arguments - <c><anno>LocalFunctionHandler</anno></c> and - <c><anno>NonLocalFunctionHandler</anno></c>. - </p> - <p>Returns <c>{value, <anno>Value</anno>, <anno>NewBindings</anno>}</c> - </p> + <p>Adds binding <c><anno>Name</anno>=<anno>Value</anno></c> + to <c><anno>BindingStruct</anno></c>. + Returns an updated binding structure.</p> </desc> </func> + + <func> + <name name="binding" arity="2"/> + <fsummary>Return bindings.</fsummary> + <desc> + <p>Returns the binding of <c><anno>Name</anno></c> + in <c><anno>BindingStruct</anno></c>.</p> + </desc> + </func> + + <func> + <name name="bindings" arity="1"/> + <fsummary>Return bindings.</fsummary> + <desc> + <p>Returns the list of bindings contained in the binding + structure.</p> + </desc> + </func> + + <func> + <name name="del_binding" arity="2"/> + <fsummary>Delete a binding.</fsummary> + <desc> + <p>Removes the binding of <c><anno>Name</anno></c> + in <c><anno>BindingStruct</anno></c>. + Returns an updated binding structure.</p> + </desc> + </func> + <func> <name name="expr" arity="2"/> <name name="expr" arity="3"/> <name name="expr" arity="4"/> <name name="expr" arity="5"/> - <fsummary>Evaluate expression</fsummary> + <fsummary>Evaluate expression.</fsummary> <desc> <p>Evaluates <c><anno>Expression</anno></c> with the set of bindings - <c><anno>Bindings</anno></c>. <c><anno>Expression</anno></c> - is an expression in - abstract syntax. See below for an explanation of - how and when to use the arguments + <c><anno>Bindings</anno></c>. <c><anno>Expression</anno></c> is an + expression in abstract syntax. + For an explanation of when and how to use arguments <c><anno>LocalFunctionHandler</anno></c> and - <c><anno>NonLocalFunctionHandler</anno></c>. - </p> - <p>Returns <c>{value, <anno>Value</anno>, - <anno>NewBindings</anno>}</c> by default. But if the - <c><anno>ReturnFormat</anno></c> is <c>value</c> only - the <c><anno>Value</anno></c> is returned.</p> + <c><anno>NonLocalFunctionHandler</anno></c>, see sections + <seealso marker="#local_function_handler"> + Local Function Handler</seealso> and + <seealso marker="#non_local_function_handler"> + Non-Local Function Handler</seealso> in this module.</p> + <p>Returns <c>{value, <anno>Value</anno>, <anno>NewBindings</anno>}</c> + by default. If <c><anno>ReturnFormat</anno></c> is <c>value</c>, + only <c><anno>Value</anno></c> is returned.</p> </desc> </func> + <func> <name name="expr_list" arity="2"/> <name name="expr_list" arity="3"/> <name name="expr_list" arity="4"/> - <fsummary>Evaluate a list of expressions</fsummary> + <fsummary>Evaluate a list of expressions.</fsummary> <desc> <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 <c>LocalFunctionHandler</c>. See below. - </p> + merge the bindings returned from each evaluation. This + function is useful in <c>LocalFunctionHandler</c>, see section + <seealso marker="#local_function_handler"> + Local Function Handler</seealso> in this module.</p> <p>Returns <c>{<anno>ValueList</anno>, <anno>NewBindings</anno>}</c>. </p> </desc> </func> + <func> - <name name="new_bindings" arity="0"/> - <fsummary>Return a bindings structure</fsummary> - <desc> - <p>Returns an empty binding structure.</p> - </desc> - </func> - <func> - <name name="bindings" arity="1"/> - <fsummary>Return bindings</fsummary> - <desc> - <p>Returns the list of bindings contained in the binding - structure.</p> - </desc> - </func> - <func> - <name name="binding" arity="2"/> - <fsummary>Return bindings</fsummary> - <desc> - <p>Returns the binding of <c><anno>Name</anno></c> - in <c><anno>BindingStruct</anno></c>.</p> - </desc> - </func> - <func> - <name name="add_binding" arity="3"/> - <fsummary>Add a binding</fsummary> + <name name="exprs" arity="2"/> + <name name="exprs" arity="3"/> + <name name="exprs" arity="4"/> + <fsummary>Evaluate expressions.</fsummary> <desc> - <p>Adds the binding <c><anno>Name</anno> = <anno>Value</anno></c> - to <c><anno>BindingStruct</anno></c>. - Returns an updated binding structure.</p> + <p>Evaluates <c><anno>Expressions</anno></c> with the set of bindings + <c><anno>Bindings</anno></c>, where <c><anno>Expressions</anno></c> + is a sequence of expressions (in abstract syntax) of a type that can + be returned by <seealso marker="io#parse_erl_exprs/2"> + <c>io:parse_erl_exprs/2</c></seealso>. + For an explanation of when and how to use arguments + <c><anno>LocalFunctionHandler</anno></c> and + <c><anno>NonLocalFunctionHandler</anno></c>, see sections + <seealso marker="#local_function_handler"> + Local Function Handler</seealso> and + <seealso marker="#non_local_function_handler"> + Non-Local Function Handler</seealso> in this module.</p> + <p>Returns <c>{value, <anno>Value</anno>, <anno>NewBindings</anno>}</c> + </p> </desc> </func> + <func> - <name name="del_binding" arity="2"/> - <fsummary>Delete a binding</fsummary> + <name name="new_bindings" arity="0"/> + <fsummary>Return a bindings structure.</fsummary> <desc> - <p>Removes the binding of <c><anno>Name</anno></c> - in <c><anno>BindingStruct</anno></c>. - Returns an updated binding structure.</p> + <p>Returns an empty binding structure.</p> </desc> </func> </funcs> <section> + <marker id="local_function_handler"></marker> <title>Local Function Handler</title> - <p><marker id="local_function_handler"></marker> - During evaluation of a function, no calls can be made to local + <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 - <c>LocalFunctionHandler</c> may be used to define a function - which is called when there is a call to a local function. The + <c>LocalFunctionHandler</c> 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:</p> <taglist> <tag><c>{value,Func}</c></tag> <item> - <p>This defines a local function handler which is called with:</p> + <p>This defines a local function handler that is called with:</p> <code type="none"> -Func(Name, Arguments) </code> +Func(Name, Arguments)</code> <p><c>Name</c> is the name of the local function (an atom) and <c>Arguments</c> is a list of the <em>evaluated</em> 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 <c>exit/1</c> with a suitable exit value.</p> + local function. In this case, the current bindings cannot be + accessed. To signal an error, the function + handler calls <c>exit/1</c> with a suitable exit value.</p> </item> <tag><c>{eval,Func}</c></tag> <item> - <p>This defines a local function handler which is called with:</p> + <p>This defines a local function handler that is called with:</p> <code type="none"> -Func(Name, Arguments, Bindings) </code> +Func(Name, Arguments, Bindings)</code> <p><c>Name</c> is the name of the local function (an atom), <c>Arguments</c> is a list of the <em>unevaluated</em> arguments, and <c>Bindings</c> are the current variable bindings. The function handler returns:</p> <code type="none"> -{value,Value,NewBindings} </code> +{value,Value,NewBindings}</code> <p><c>Value</c> is the value of the local function and <c>NewBindings</c> 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 <c>exit/1</c> with a + error, the function handler calls <c>exit/1</c> with a suitable exit value.</p> </item> <tag><c>none</c></tag> @@ -241,55 +253,66 @@ Func(Name, Arguments, Bindings) </code> </section> <section> - <title>Non-local Function Handler</title> - <p><marker id="non_local_function_handler"></marker> - The optional argument <c>NonlocalFunctionHandler</c> 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 operator Op/A is called - (this is handled as a call to the function <c>erlang:Op/A</c>). - Exceptions are calls to <c>erlang:apply/2,3</c>; neither of the - function handlers will be called for such calls. + <marker id="non_local_function_handler"></marker> + <title>Non-Local Function Handler</title> + <p>The optional argument <c>NonLocalFunctionHandler</c> can be + used to define a function that is called in the following + cases:</p> + <list type="bulleted"> + <item><p>A functional object (fun) is called.</p></item> + <item><p>A built-in function is called.</p></item> + <item><p>A function is called using the <c>M:F</c> syntax, where <c>M</c> + and <c>F</c> are atoms or expressions.</p></item> + <item><p>An operator <c>Op/A</c> is called (this is handled as a call to + function <c>erlang:Op/A</c>).</p></item> + </list> + <p>Exceptions are calls to <c>erlang:apply/2,3</c>; neither of the + function handlers are called for such calls. The argument can have the following formats:</p> <taglist> <tag><c>{value,Func}</c></tag> <item> - <p>This defines an nonlocal function handler which is called with:</p> + <p>This defines a non-local function handler that is called with:</p> <code type="none"> -Func(FuncSpec, Arguments) </code> +Func(FuncSpec, Arguments)</code> <p><c>FuncSpec</c> is the name of the function on the form <c>{Module,Function}</c> or a fun, and <c>Arguments</c> is a list of the <em>evaluated</em> arguments. The function handler returns the value of the function. To - signal an error, the function handler just calls + signal an error, the function handler calls <c>exit/1</c> with a suitable exit value.</p> </item> <tag><c>none</c></tag> <item> - <p>There is no nonlocal function handler.</p> + <p>There is no non-local function handler.</p> </item> </taglist> <note> <p>For calls such as <c>erlang:apply(Fun, Args)</c> or - <c>erlang:apply(Module, Function, Args)</c> the call of the + <c>erlang:apply(Module, Function, Args)</c>, the call of the non-local function handler corresponding to the call to - <c>erlang:apply/2,3</c> itself--<c>Func({erlang, apply}, [Fun, Args])</c> or <c>Func({erlang, apply}, [Module, Function, Args])</c>--will never take place. The non-local function - handler <em>will</em> however be called with the evaluated - arguments of the call to <c>erlang:apply/2,3</c>: <c>Func(Fun, Args)</c> or <c>Func({Module, Function}, Args)</c> (assuming + <c>erlang:apply/2,3</c> itself + (<c>Func({erlang, apply}, [Fun, Args])</c> or + <c>Func({erlang, apply}, [Module, Function, Args])</c>) + never takes place.</p> + <p>The non-local function handler <em>is</em> however called with the + evaluated arguments of the call to + <c>erlang:apply/2,3</c>: <c>Func(Fun, Args)</c> or + <c>Func({Module, Function}, Args)</c> (assuming that <c>{Module, Function}</c> is not <c>{erlang, apply}</c>).</p> - <p>Calls to functions defined by evaluating fun expressions + <p>Calls to functions defined by evaluating fun expressions <c>"fun ... end"</c> are also hidden from non-local function - handlers.</p> </note> - <p>The nonlocal function handler argument is probably not used as + handlers.</p> + </note> + <p>The non-local function handler argument is probably not used as frequently as the local function handler argument. A possible use is to call <c>exit/1</c> on calls to functions that for some reason are not allowed to be called.</p> </section> <section> - <title>Bugs</title> - <p>Undocumented functions in <c>erl_eval</c> should not be used.</p> + <title>Known Limitation</title> + <p>Undocumented functions in this module are not to be used.</p> </section> </erlref> |