From 68d53c01b0b8e9a007a6a30158c19e34b2d2a34e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Wed, 18 May 2016 15:53:35 +0200 Subject: Update STDLIB documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder. --- lib/stdlib/doc/src/erl_eval.xml | 245 ++++++++++++++++++++++------------------ 1 file changed, 134 insertions(+), 111 deletions(-) (limited to 'lib/stdlib/doc/src/erl_eval.xml') 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 @@ 1 Bjarne Däcker - 97-01-21 + 1997-01-21 B - erl_eval.sgml + erl_eval.xml erl_eval - The Erlang Meta Interpreter + The Erlang meta interpreter.

This module provides an interpreter for Erlang expressions. The expressions are in the abstract syntax as returned by erl_parse, - the Erlang parser, or - io.

+ the Erlang parser, or io.

 + @@ -73,9 +73,9 @@ -

Further described - below.

- +

Further described in section + + Local Function Handler in this module

 @@ -85,152 +85,164 @@ -

Further described - below.

- +

Further described in section + + Non-Local Function Handler in this module.

 + - - - - Evaluate expressions + + Add a binding. -

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 - LocalFunctionHandler and - NonLocalFunctionHandler. -

-

Returns {value, Value, NewBindings} -

+

Adds binding Name=Value + to BindingStruct. + Returns an updated binding structure.

 + + + + Return bindings. + +

Returns the binding of Name + in BindingStruct.

+ + + + + + Return bindings. + +

Returns the list of bindings contained in the binding + structure.

+ + + + + + Delete a binding. + +

Removes the binding of Name + in BindingStruct. + Returns an updated binding structure.

+ + + - Evaluate expression + Evaluate expression.

Evaluates Expression with the set of bindings - Bindings. Expression - is an expression in - abstract syntax. See below for an explanation of - how and when to use the arguments + Bindings. Expression is an + expression in abstract syntax. + For an explanation of when and how to use arguments LocalFunctionHandler and - NonLocalFunctionHandler. -

-

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

+ NonLocalFunctionHandler, see sections + + Local Function Handler and + + Non-Local Function Handler in this module.

+

Returns {value, Value, NewBindings} + by default. If ReturnFormat is value, + only Value is returned.

 + - Evaluate a list of expressions + Evaluate a list of expressions.

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

+ merge the bindings returned from each evaluation. This + function is useful in LocalFunctionHandler, see section + + Local Function Handler in this module.

Returns {ValueList, NewBindings}.

+ - - Return a bindings structure - -

Returns an empty binding structure.

- - - - - Return bindings - -

Returns the list of bindings contained in the binding - structure.

- - - - - Return bindings - -

Returns the binding of Name - in BindingStruct.

- - - - - Add a binding + + + + Evaluate expressions. -

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

+

Evaluates Expressions with the set of bindings + Bindings, where Expressions + is a sequence of expressions (in abstract syntax) of a type that can + be returned by + io:parse_erl_exprs/2. + For an explanation of when and how to use arguments + LocalFunctionHandler and + NonLocalFunctionHandler, see sections + + Local Function Handler and + + Non-Local Function Handler in this module.

+

Returns {value, Value, NewBindings} +

+ - - Delete a binding + + Return a bindings structure. -

Removes the binding of Name - in BindingStruct. - Returns an updated binding structure.

+

Returns an empty binding structure.
+ Local Function Handler -

- During evaluation of a function, no calls can be made to local +

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 + LocalFunctionHandler 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:

{value,Func} -

This defines a local function handler which is called with:

+

This defines a local function handler that is called with:

-Func(Name, Arguments) +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.

+ local function. In this case, the current bindings cannot be + accessed. To signal an error, the function + handler calls exit/1 with a suitable exit value.

 {eval,Func} -

This defines a local function handler which is called with:

+

This defines a local function handler that is called with:

-Func(Name, Arguments, Bindings) +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 variable bindings. The function handler returns:

-{value,Value,NewBindings} +{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 + error, the function handler calls exit/1 with a suitable exit value.

 none @@ -241,55 +253,66 @@ Func(Name, Arguments, Bindings)
- 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 operator 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. + + Non-Local Function Handler +

The optional argument NonLocalFunctionHandler can be + used to define a function that 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 + function erlang:Op/A).

 + +

Exceptions are calls to erlang:apply/2,3; neither of the + function handlers are called for such calls. The argument can have the following formats:

{value,Func} -

This defines an nonlocal function handler which is called with:

+

This defines a non-local function handler that is called with:

-Func(FuncSpec, Arguments) +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 + signal an error, the function handler calls exit/1 with a suitable exit value.

 none -

There is no nonlocal function handler.

+

There is no non-local function handler.

For calls such as erlang:apply(Fun, Args) or - erlang:apply(Module, Function, Args) the call of the + 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 + erlang:apply/2,3 itself + (Func({erlang, apply}, [Fun, Args]) or + Func({erlang, apply}, [Module, Function, Args])) + never takes place.

+

The non-local function handler is however 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 +

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 + handlers.

+ +

The non-local 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 -

Undocumented functions in erl_eval should not be used.

+ Known Limitation +

Undocumented functions in this module are not to be used.

-- cgit v1.2.3