Signaling and Handling Conditions

The implementation notes document the JavaScript file /system/core.js, which implements the “core” of the EVLambda programming language and the EVL to XML converter (one of the two components of the documentation generator, the other one being the XSLT stylesheet). The implementation notes and the JavaScript file have the same organization (the same sections, in the same order) and are meant to be read side by side.

A lexical or dynamic environment is represented not by the result of the sequence of extensions leading to the environment but by a recording of the sequence of extensions leading to the environment. A single extension is recorded into a data structure called a frame and a sequence of extensions is recorded into a chain of frames.

Let $\env$ be a lexical or dynamic environment and$$[(\ns_1,[\var_{1,1},\ldots,\var_{1,m_1}],[\obj_{1,1},\ldots,\obj_{1,m_1}]),\ldots,(\ns_n,[\var_{n,1},\ldots,\var_{n,m_n}],[\obj_{n,1},\ldots,\obj_{n,m_n}])]$$be the sequence of extensions leading to the environment. The extensions are applied from left to right and the first extension is applied to an empty environment. The $i$-th extension$$(\ns_i,[\var_{i,1},\ldots,\var_{i,m_i}],[\obj_{i,1},\ldots,\obj_{i,m_i}])$$extends the previous environment by binding, in the namespace $\ns_i$, the variable $\var_{i,j}$ to the object $\obj_{i,j}$ (for all $i$ from $1$ to $n$ and all $j$ from $1$ to $m_i$). We will denote by $\bindingmathop(i,j)$ the binding between $\var_{i,j}$ and $\obj_{i,j}$ created by the $i$-th extension.

Let $\env$ be a lexical or dynamic environment and$$[(\ns_1,[\var_{1,1},\ldots,\var_{1,m_1}],[\obj_{1,1},\ldots,\obj_{1,m_1}]),\ldots,(\ns_n,[\var_{n,1},\ldots,\var_{n,m_n}],[\obj_{n,1},\ldots,\obj_{n,m_n}])]$$be the sequence of extensions leading to the environment. The extensions are applied from left to right and the first extension is applied to an empty environment. The $i$-th extension$$(\ns_i,[\var_{i,1},\ldots,\var_{i,m_i}],[\obj_{i,1},\ldots,\obj_{i,m_i}])$$extends the previous environment by binding, in the namespace $\ns_i$, the variable $\var_{i,j}$ to the object $\obj_{i,j}$ (for all $i$ from $1$ to $n$ and all $j$ from $1$ to $m_i$). We will denote by $\binding(i,j)$ the binding between $\var_{i,j}$ and $\obj_{i,j}$ created by the $i$-th extension.

The binding for the variable $\var$ in the namespace $\ns$ of the environment $\env$ can easily be located using the following lookup rule expressed in pseudocode:

Reference Manual

The reference manual provides a detailed account of the programming language. It supplements and amends the user manual (particularly the sections “Programming Language” and “Listener Buffers”) and the tutorial.

The subforms of a form are the forms that are directly or indirectly contained inside the form but are not contained inside a lambda abstraction. The serial-forms of the body of a lambda abstraction are not considered to be subforms of the lambda abstraction because the evaluation of a lambda abstraction does not entail the evaluation of the serial-forms of its body.

A form is said to be in tail position with respect to a lambda abstraction if and only if one of the following mutually exclusive conditions is satisfied:

Documentation Generator

In this section, the character ⇰ marks the places where line breaks have been added to wrap long lines.

Semantics

Primitive Data Types and Primitive Functions

This section inventories all the primitive data types and all the primitive functions.

For each primitive function, a template function call and a description of the primitive function's behavior are provided.

For each primitive function, a template function call, an indication of the outcome of the corresponding invocation, and a description of the primitive function's behavior are provided.

In template function calls, argument names imply the following type restrictions:

If any argument is not of its required type, then the invocation of the primitive function completes abruptly with a reason of type error.

If any argument is not of its required type, then the invocation of the primitive function completes abruptly for a reason of type error.

Primitive Data Types

Primitive Data Type object and Related Primitive Functions

Primitive Data Type void and Related Primitive Functions

Primitive Data Type boolean and Related Primitive Functions

Primitive Data Type number and Related Primitive Functions

Objects of type number represent mathematical numbers using the floating-point format IEEE 754 binary 64. Some (but not all) of the integers that can be represented exactly by an object of type number are the integers between $-2^{53}=â9,007,199,254,740,992$ and $2^{53}=9,007,199,254,740,992$ (bounds included).

The primitive functions _+, _-, _*, and _/ have an underscore at the beginning of their names to distinguish them from the similarly named nonprimitive functions +, -, *, and /, which all accept a variable number of arguments.

Primitive Data Type character and Related Primitive Functions

Contrary to what was said in the user manual, an object of type character represents a UTF-$16$ code unit (instead of a Unicode character).

Primitive Data Type string and Related Primitive Functions

Contrary to what was said in the user manual, an object of type string represents an indexed sequence of UTF-$16$ code units (instead of an indexed sequence of Unicode characters).

Primitive Data Type symbol and Related Primitive Functions

Primitive Data Type keyword and Related Primitive Functions

Primitive Data Type variable and Related Primitive Functions

Primitive Data Type list and Related Primitive Functions

Primitive Data Type empty-list and Related Primitive Functions

Primitive Data Type cons and Related Primitive Functions

Primitive Data Type vector and Related Primitive Functions

Primitive Data Type function and Related Primitive Functions

Primitive Data Type primitive-function and Related Primitive Functions

Primitive Data Type closure and Related Primitive Functions

Miscellaneous Primitive Functions

Forms

This section supplements and amends the evaluation rules stated in the user manual.

Advanced Control Structures

The two pairs of special forms block/return-from and catch/throw use two additional namespaces: the block-name namespace and the exit-point namespace.

Special Forms block/return-from

Special Forms catch/throw

Special Form _handler-bind

Special Form unwind-protect

Special Form _for-each

Special Form _catch-errors

Function Calls

A spreadable sequence of objects is a nonempty sequence of objects such that the last element of the sequence is a proper list of objects. Let $\mlvar{seq}=[\obj_1,\ldots,\obj_n,\code{(}\obj'_1\ldots\obj'_m\code{)}]$, where $n$ and $m$ are nonnegative integers, be a spreadable sequence of objects. We will denote by $\spread(\mlvar{seq})$ the sequence of objects $[\obj_1,\ldots,\obj_n,\obj'_1,\ldots,\obj'_m]$.

The function calls are evaluated as follows (the differences in behavior between the different types of function calls are highlighted with a gray background):

A primitive function is invoked as described in the user manual. A closure is invoked as described in the user manual except for the way the parameters are paired with the arguments in order to extend the value namespace of the lexical environment captured by the closure (when the corresponding lambda abstraction is a _vlambda-form or an _mlambda-form), the function namespace of the lexical environment captured by the closure (when the corresponding lambda abstraction is an _flambda-form), or the value namespace of the current dynamic environment (when the corresponding lambda abstraction is a _dlambda-form). Let $\arg_1,\ldots,\arg_n$ be the arguments and $var_1,\ldots,\var_m$ be the required parameters. The way the parameters are paired with the arguments depends on the absence or presence of a rest parameter:

Here are some examples, where the bindings are assumed to belong to the value namespace:

Here is one way to reproduce the preceding examples using plain function calls and _vlambda-forms:

Evaluation Rules in Continuation-Passing Style

When we say that a macro does this and that, what we really mean is that the expansion of the macro does this and that. In the case of the macros and and or, it is their expansions that evaluate the test-forms in sequence from left to right, etc.

The macros and and or stop evaluating their operands as soon as they can determine that the result of the macro call is definitively true or definitively false. This short-circuiting behavior is possible only because and and or are macros. When a function call is evaluated, all the operands are always evaluated (unless the evaluation of the operator or the evaluation of one of the operands other than the last one completes abruptly or does not complete).

The macros and and or stop evaluating their operands as soon as they can determine that the result of the macro call is definitively true or definitively false. This short-circuiting behavior is possible only because and and or are macros. When a function call is evaluated, all the operand-forms are always evaluated (unless the evaluation of the operator-form completes abruptly or does not complete, the primary value of the operator-form is not a function, or the evaluation of one of the operand-forms other than the last one completes abruptly or does not complete).

Here are two expansions illustrating the implementations of the macros and and or:

Let $n_\mathrm{init}$ be the the argument of fib-iter and $n$, $a$, and $b$ be the arguments of the invocation of fib-iter-internal under consideration. When processing the invocation of fib-iter-internal from fib-iter, $n=n_\mathrm{init}$, $a=F_0$, and $b=F_1$. If $n_\mathrm{init}=0$, then fib-iter-internal returns $a=F_0$. Otherwise, if $n_\mathrm{init}=1$, then fib-iter-internal returns $b=F_1$. Otherwise, fib-iter-internal invokes itself recursively. On each recursive invocation of fib-iter-internal, $n$ is decremented by $1$, $a$ is replaced by the next Fibonacci number in the sequence $F_0,F_1,F_2,\ldots$, and $b$ is replaced by the next Fibonacci number in the sequence $F_1,F_2,F_3,\ldots$ When processing the $(n_\mathrm{init}-1)$-th recursive invocation of fib-iter-internal, $n=n_\mathrm{init}-(n_\mathrm{init}-1)=1$, $a=F_{0+n_\mathrm{init}-1}=F_{n_\mathrm{init}-1}$, and $b=F_{1+n_\mathrm{init}-1}=F_{n_\mathrm{init}}$ and fib-iter-internal returns $b=F_{n_\mathrm{init}}$.

Let $n_\textrm{init}$ be the the argument of fib-iter and $n$, $a$, and $b$ be the arguments of the invocation of fib-iter-internal under consideration. When processing the invocation of fib-iter-internal from fib-iter, $n=n_\textrm{init}$, $a=F_0$, and $b=F_1$. If $n_\textrm{init}=0$, then fib-iter-internal returns $a=F_0$. Otherwise, if $n_\textrm{init}=1$, then fib-iter-internal returns $b=F_1$. Otherwise, fib-iter-internal invokes itself recursively. On each recursive invocation of fib-iter-internal, $n$ is decremented by $1$, $a$ is replaced by the next Fibonacci number in the sequence $F_0,F_1,F_2,\ldots$, and $b$ is replaced by the next Fibonacci number in the sequence $F_1,F_2,F_3,\ldots$ When processing the $(n_\textrm{init}-1)$-th recursive invocation of fib-iter-internal, $n=n_\textrm{init}-(n_\textrm{init}-1)=1$, $a=F_{0+n_\textrm{init}-1}=F_{n_\textrm{init}-1}$, and $b=F_{1+n_\textrm{init}-1}=F_{n_\textrm{init}}$ and fib-iter-internal returns $b=F_{n_\textrm{init}}$.

The evaluation can get caught in an infinite loop and never complete.

The primary value of a form whose evaluation completed normally is defined as follows: If the result consists of one or more objects, then the primary value of the form is the first object. Otherwise, the primary value of the form is #v.

The abrupt completion of an evaluation has an associated reason, which has a type and carries a payload. An abrupt completion caused by an error has an associated reason of type error, which carries a payload consisting of an object of type string describing the error. An abrupt completion caused by a nonlocal exit has an associated reason of type exit, which carries a payload described in the reference manual.

The abrupt completion of an evaluation has an associated reason, which has a type and carries a payload. An abrupt completion caused by an error has an associated reason of type error, which carries a payload consisting of a string describing the error. An abrupt completion caused by a nonlocal exit has an associated reason of type nonlocal-exit, which carries a payload consisting of a variable (the exit tag identifying the exit point) and a sequence of zero or more objects (the values to propagate to the exit point).

Forms submitted to the evaluator through a listener buffer, through the Evaluate Form command, or through the Load Buffer command are called top-level forms. A consequence of the evaluation rules stated later in this section is that the evaluation of a top-level form usually entails the evaluation of other non-top-level forms.

Execution of EVLambda code is achieved through interpretation or compilation.

An interpreter for a language $X$ is a program capable of directly executing code written in language $X$. Language $X$ is called the source language of the interpreter. A compiler for a language $X$ is a program capable of translating code written in language $X$ into code written in a language $Y$. Language $X$ is called the source language of the compiler and language $Y$ is called the target language of the compiler. Code handed to an interpreter or compiler is called source code. A file containing source code is called a source file. Code produced by a compiler is called compiled code. A file containing compiled code is called a compiled file.

@@ -173,7 +173,7 @@

A consequence of the lookup rules is that a binding in the value/function namespace of the current lexical/dynamic environment will effectively shadow a binding for the same variable in the value/function namespace of the global environment.

A global variable is a binding between a variable and an object (of any type) in the value namespace of the global environment, or the name or value of such binding. A global function is a binding between a variable and a function other than a macro in the function namespace of the global environment, or the name or value of such binding. A global macro is a binding between a variable and a macro in the function namespace of the global environment, or the name or value of such binding. Global variables, global functions, and global macros are created and altered using language constructs called global definitions.

A local variable is a binding between a variable and an object (of any type) in the value namespace of a lexical environment, or the name or value of such binding. A local function is a binding between a variable and a function other than a macro in the function namespace of a lexical environment, or the name or value of such binding. A local macro is a binding between a variable and a macro in the function namespace of a lexical environment, or the name or value of such binding. A dynamic variable is a binding between a variable and an object (of any type) in the value namespace of a dynamic environment, or the name or value of such binding. Local variables, local functions, local macros, and dynamic variables are created (but not altered) using language constructs called binding constructs.

When a form is submitted to the evaluator, the evaluator analyzes the form to determine how to evaluate it. If the form is the empty list, then the evaluation completes abruptly with a reason of type error. Otherwise, if the form is neither a variable nor a cons, then the result of the evaluation is the form itself. (Objects that are neither the empty list, nor a variable, nor a cons are said to be self-evaluating.) Otherwise, if the form is a variable $\var$, then the variable is treated as an abbreviation for either (vref $\var$) or (fref $\var$), depending on the context of its occurrence. Otherwise, the form is necessarily a cons and the evaluation completes abruptly with a reason of type error unless the form matches one of the following patterns:

When a form is submitted to the evaluator, the evaluator analyzes the form to determine how to evaluate it. If the form is the empty list, then the evaluation completes abruptly for a reason of type error. Otherwise, if the form is neither a variable nor a cons, then the result of the evaluation is the form itself. (Objects that are neither the empty list, nor a variable, nor a cons are said to be self-evaluating.) Otherwise, if the form is a variable $\var$, then the variable is treated as an abbreviation for either (vref $\var$) or (fref $\var$), depending on the context of its occurrence. Otherwise, the form is necessarily a cons and the evaluation completes abruptly for a reason of type error unless the form matches one of the following patterns:

(quote $\metavar{literal}$)
(progn $\metavar{serial-forms}$)
(fset! $\metavar{variable}$ $\metavar{value-form}$)
(dref $\metavar{variable}$)
(dset! $\metavar{variable}$ $\metavar{value-form}$)
(block $\metavar{block-name}$ $\metavar{serial-forms}$)
(return-from $\metavar{block-name}$ $\metavar{values-form}$)
(catch $\metavar{exit-tag-form}$ $\metavar{serial-forms}$)
(throw $\metavar{exit-tag-form}$ $\metavar{values-form}$)
(_handler-bind $\metavar{handler-form}$ $\metavar{serial-forms}$)
(unwind-protect $\metavar{protected-form}$ $\metavar{cleanup-forms}$)
(_for-each $\metavar{function-form}$ $\metavar{list-form}$)
(_catch-errors $\metavar{try-form}$)
(apply $\metavar{operator-form}$ $\metavar{operand-forms}$)
(multiple-value-call $\metavar{operator-form}$ $\metavar{operand-forms}$)
(multiple-value-apply $\metavar{operator-form}$ $\metavar{operand-forms}$)
$\metavar{body}$ matches any sequence of zero or more objects
$\metavar{variable}$ matches any variable
$\metavar{value-form}$ matches any object
$\metavar{block-name}$ matches any variable
$\metavar{exit-tag-form}$ matches any object
$\metavar{values-form}$ matches any object
$\metavar{handler-form}$ matches any object
$\metavar{protected-form}$ matches any object
$\metavar{cleanup-forms}$ matches any sequence of zero or more objects
$\metavar{function-form}$ matches any object
$\metavar{list-form}$ matches any object
$\metavar{try-form}$ matches any object
$\metavar{macro-operator}$ matches any variable naming a macro according to the lookup rule used by fref
$\metavar{macro-operands}$ matches any sequence of zero or more objects
$\metavar{operator-form}$ matches any object

By way of example, a form matches the first pattern if and only if it is a list of two elements whose first element is the variable quote.

The patterns are tried in sequence and the first matching pattern wins.

A form matching one of the first eighteen patterns is called a special form and the variables quote, progn, if, _vlambda, _mlambda, _flambda, _dlambda, vref, vset!, fref, fset!, dref, dset!, _for-each, _catch-all, apply, multiple-value-call, and multiple-value-apply are called special operators.

Special forms matching patterns 4 (_vlambda), 5 (_mlambda), 6 (_flambda), and 7 (_dlambda) are called lambda abstractions. Lambda abstractions are the fundamental binding constructs from which all other binding constructs are built. Forms consisting of a variable and special forms matching patterns 8 (vref), 10 (fref), and 12 (dref) are called variable references. Special forms matching patterns 9 (vset!), 11 (fset!), and 13 (dset!) are called variable assignments. Forms matching pattern 19 are called macro calls. Forms matching pattern 20 are called plain function calls.

A form matching one of the first twenty-three patterns is called a special form and the variables quote, progn, if, _vlambda, _mlambda, _flambda, _dlambda, vref, vset!, fref, fset!, dref, dset!, block, return-from, catch, throw, _handler-bind, unwind-protect, _for-each, apply, multiple-value-call, and multiple-value-apply are called special operators.

Special forms matching patterns 4 (_vlambda), 5 (_mlambda), 6 (_flambda), and 7 (_dlambda) are called lambda abstractions. Lambda abstractions are the fundamental binding constructs from which all other binding constructs are built. Forms consisting of a variable and special forms matching patterns 8 (vref), 10 (fref), and 12 (dref) are called variable references. Special forms matching patterns 9 (vset!), 11 (fset!), and 13 (dset!) are called variable assignments. Forms matching pattern 24 are called macro calls. Forms matching pattern 25 are called plain function calls.

The rule regarding forms consisting of a variable is the following: If a variable $\var$ occurs in operator position, then the variable is treated as an abbreviation for (fref $\var$) and the function namespace is used. Otherwise, the variable is treated as an abbreviation for (vref $\var$) and the value namespace is used. For example, the plain function call (f x) would be treated as an abbreviation for ((fref f) (vref x)). The full forms (fref $\var$) and (vref $\var$) can always be used to force the use of a specific namespace.

As we will see below, the evaluation of a form containing subforms entails the evaluation of some or all of the subforms. When a subform is evaluated, the following rules apply:

As we will see below, the evaluation of a form entails the evaluation of some or all of the forms directly contained inside the form. When a direct subform is evaluated, the following rules apply:

The subform is evaluated with respect to the same lexical and dynamic environments as the containing form. (But see below how closures are invoked.)
Generally, if the evaluation of the subform completes abruptly for any reason, then the evaluation of the containing form also completes abruptly for the same reason. The only form that can behave differently is the special form _catch-errors.
If the evaluation of the subform does not complete, then the evaluation of the containing form does not complete either.
The direct subform is evaluated with respect to the same lexical and dynamic environments as the containing form. (But see below how closures are invoked.)
Generally, if the evaluation of the direct subform completes abruptly for any reason, then the evaluation of the containing form immediately completes abruptly for the same reason. The only forms that can behave differently are the special forms block, catch, _handler-bind, and unwind-protect, which are described in the reference manual.
If the evaluation of the direct subform does not complete, then the evaluation of the containing form does not complete either.

Special forms, macro calls, and plain function calls are evaluated as follows:

(progn $\metavar{serial-forms}$): The serial-forms are evaluated in sequence from left to right. If there is at least one serial-form, then the progn-form evaluates to the values of the last serial-form. Otherwise, the progn-form evaluates to #v.
(if $\metavar{test-form}$ $\metavar{then-form}$ $\metavar{else-form}$): The test-form is evaluated. Let $\primval$ be the primary value of the test-form. If $\primval$ is not a boolean, then the evaluation of the if-form completes abruptly with a reason of type error. If $\primval$ is the boolean #t, then the then-form is evaluated and the if-form evaluates to the values of the then-form. If $\primval$ is the boolean #f, then the else-form is evaluated and the if-form evaluates to the values of the else-form.; The test-form is evaluated. Let $\mlvar{test}$ be the primary value of the test-form. If $\mlvar{test}$ is not a boolean, then the evaluation of the if-form completes abruptly for a reason of type error. If $\mlvar{test}$ is the boolean #t, then the then-form is evaluated and the if-form evaluates to the values of the then-form. If $\mlvar{test}$ is the boolean #f, then the else-form is evaluated and the if-form evaluates to the values of the else-form.
(_vlambda $\metavar{parameter-list}$ $\metavar{body}$)
(_mlambda $\metavar{parameter-list}$ $\metavar{body}$)
(_flambda $\metavar{parameter-list}$ $\metavar{body}$)
(_dlambda $\metavar{parameter-list}$ $\metavar{body}$): A lambda abstraction evaluates to a closure recording the following two pieces of information: the lambda abstraction and the current lexical environment (which is said to be captured by the closure). A closure resulting from the evaluation of an _mlambda-form is tagged as being a macro.
(vref $\metavar{variable}$): If there exists a binding for the variable in the value namespace of the current lexical environment, then the vref-form evaluates to the value of that binding. Otherwise, if there exists a binding for the variable in the value namespace of the global environment, then the vref-form evaluates to the value of that binding. Otherwise, the evaluation of the vref-form completes abruptly with a reason of type error.; If there exists a binding for the variable in the value namespace of the current lexical environment, then the vref-form evaluates to the value of that binding. Otherwise, if there exists a binding for the variable in the value namespace of the global environment, then the vref-form evaluates to the value of that binding. Otherwise, the evaluation of the vref-form completes abruptly for a reason of type error.
(vset! $\metavar{variable}$ $\metavar{value-form}$): The value-form is evaluated. Let $\primval$ be the primary value of the value-form. If there exists a binding for the variable in the value namespace of the current lexical environment, then the value of that binding is replaced by $\primval$. Otherwise, if there exists a binding for the variable in the value namespace of the global environment, then the value of that binding is replaced by $\primval$. Otherwise, a new binding between the variable and $\primval$ is added to the value namespace of the global environment. In all three cases, the vset-form evaluates to $\primval$.; The value-form is evaluated. Let $\mlvar{value}$ be the primary value of the value-form. If there exists a binding for the variable in the value namespace of the current lexical environment, then the value of that binding is replaced by $\mlvar{value}$. Otherwise, if there exists a binding for the variable in the value namespace of the global environment, then the value of that binding is replaced by $\mlvar{value}$. Otherwise, a new binding between the variable and $\mlvar{value}$ is added to the value namespace of the global environment. In all three cases, the vset-form evaluates to $\mlvar{value}$.
(fref $\metavar{variable}$): If there exists a binding for the variable in the function namespace of the current lexical environment, then the fref-form evaluates to the value of that binding. Otherwise, if there exists a binding for the variable in the function namespace of the global environment, then the fref-form evaluates to the value of that binding. Otherwise, the evaluation of the fref-form completes abruptly with a reason of type error.; If there exists a binding for the variable in the function namespace of the current lexical environment, then the fref-form evaluates to the value of that binding. Otherwise, if there exists a binding for the variable in the function namespace of the global environment, then the fref-form evaluates to the value of that binding. Otherwise, the evaluation of the fref-form completes abruptly for a reason of type error.
(fset! $\metavar{variable}$ $\metavar{value-form}$): The value-form is evaluated. Let $\primval$ be the primary value of the value-form. If there exists a binding for the variable in the function namespace of the current lexical environment, then the value of that binding is replaced by $\primval$. Otherwise, if there exists a binding for the variable in the function namespace of the global environment, then the value of that binding is replaced by $\primval$. Otherwise, a new binding between the variable and $\primval$ is added to the function namespace of the global environment. In all three cases, the fset-form evaluates to $\primval$.; The value-form is evaluated. Let $\mlvar{value}$ be the primary value of the value-form. If there exists a binding for the variable in the function namespace of the current lexical environment, then the value of that binding is replaced by $\mlvar{value}$. Otherwise, if there exists a binding for the variable in the function namespace of the global environment, then the value of that binding is replaced by $\mlvar{value}$. Otherwise, a new binding between the variable and $\mlvar{value}$ is added to the function namespace of the global environment. In all three cases, the fset-form evaluates to $\mlvar{value}$.
(dref $\metavar{variable}$): If there exists a binding for the variable in the value namespace of the current dynamic environment, then the dref-form evaluates to the value of that binding. Otherwise, if there exists a binding for the variable in the value namespace of the global environment, then the dref-form evaluates to the value of that binding. Otherwise, the evaluation of the dref-form completes abruptly with a reason of type error.; If there exists a binding for the variable in the value namespace of the current dynamic environment, then the dref-form evaluates to the value of that binding. Otherwise, if there exists a binding for the variable in the value namespace of the global environment, then the dref-form evaluates to the value of that binding. Otherwise, the evaluation of the dref-form completes abruptly for a reason of type error.
(dset! $\metavar{variable}$ $\metavar{value-form}$): The value-form is evaluated. Let $\primval$ be the primary value of the value-form. If there exists a binding for the variable in the value namespace of the current dynamic environment, then the value of that binding is replaced by $\primval$. Otherwise, if there exists a binding for the variable in the value namespace of the global environment, then the value of that binding is replaced by $\primval$. Otherwise, a new binding between the variable and $\primval$ is added to the value namespace of the global environment. In all three cases, the dset-form evaluates to $\primval$.; The value-form is evaluated. Let $\mlvar{value}$ be the primary value of the value-form. If there exists a binding for the variable in the value namespace of the current dynamic environment, then the value of that binding is replaced by $\mlvar{value}$. Otherwise, if there exists a binding for the variable in the value namespace of the global environment, then the value of that binding is replaced by $\mlvar{value}$. Otherwise, a new binding between the variable and $\mlvar{value}$ is added to the value namespace of the global environment. In all three cases, the dset-form evaluates to $\mlvar{value}$.
(block $\metavar{block-name}$ $\metavar{serial-forms}$)
(return-from $\metavar{block-name}$ $\metavar{values-form}$)
(catch $\metavar{exit-tag-form}$ $\metavar{serial-forms}$)
(throw $\metavar{exit-tag-form}$ $\metavar{values-form}$)
(_handler-bind $\metavar{handler-form}$ $\metavar{serial-forms}$)
(unwind-protect $\metavar{protected-form}$ $\metavar{cleanup-forms}$): These special forms, which implement advanced control structures, are described in the reference manual.
(_for-each $\metavar{function-form}$ $\metavar{list-form}$): This special form is described in the reference manual.
(_catch-errors $\metavar{try-form}$): This special form is described in the reference manual.; This special form, which is a hack only needed and implemented by some of the interpreters, is described in the reference manual.
(apply $\metavar{operator-form}$ $\metavar{operand-forms}$)
(multiple-value-call $\metavar{operator-form}$ $\metavar{operand-forms}$)
(multiple-value-apply $\metavar{operator-form}$ $\metavar{operand-forms}$): These special forms are variants of the plain function call described below. They are described in the reference manual.; These special forms, which are variants of the plain function call, are described in the reference manual.
($\metavar{macro-operator}$ $\metavar{macro-operands}$): Following the definition of a macro call, the macro-operator matches a variable naming a macro according to the lookup rule used by fref. That macro is invoked on the unevaluated macro-operands. If the invocation completes abruptly for any reason, then the evaluation of the macro call also completes abruptly for the same reason. Otherwise, if the invocation does not complete, then the evaluation of the macro call does not complete either. Otherwise, the primary value of the invocation, which is called the expansion of the macro call, is evaluated with respect to the current lexical and dynamic environments. If the evaluation of the expansion completes abruptly for any reason, then the evaluation of the macro call also completes abruptly for the same reason. Otherwise, if the evaluation of the expansion does not complete, then the evaluation of the macro call does not complete either. Otherwise, the macro call evaluates to the values of the expansion.
($\metavar{operator-form}$ $\metavar{operand-forms}$): The operator-form and the operand-forms are evaluated in sequence from left to right. If the primary value of the operator-form is not a function, then the evaluation of the plain function call completes abruptly with a reason of type error. Otherwise, the primary value of the operator-form is invoked on the primary values of the operand-forms. If the invocation completes abruptly for any reason, then the evaluation of the plain function call also completes abruptly for the same reason. Otherwise, if the invocation does not complete, then the evaluation of the plain function call does not complete either. Otherwise, the plain function call evaluates to the values of the invocation.; The operator-form is evaluated. Let $\mlvar{operator}$ be the primary value of the operator-form. If $\mlvar{operator}$ is not a function, then the evaluation of the plain function call completes abruptly for a reason of type error. Otherwise, the operand-forms are evaluated in sequence from left to right and $\mlvar{operator}$ is invoked on the primary values of the operand-forms. If the invocation completes abruptly for any reason, then the evaluation of the plain function call also completes abruptly for the same reason. Otherwise, if the invocation does not complete, then the evaluation of the plain function call does not complete either. Otherwise, the plain function call evaluates to the values of the invocation.

Invoking a function is what causes the function to compute the output corresponding to an input. The input of an invocation consists of zero or more objects—object references actually—called the arguments of the invocation. (The function is said to be invoked on the arguments and the arguments are said to be passed to the function.) The invocation of a function has three possible outcomes:

Let us assume that, as is the case with all the evaluators currently available, the primitive function is implemented by a JavaScript function accepting (an encoding of) the arguments of the invocation of the primitive function and returning (an encoding of) the values of the invocation of the primitive function. The JavaScript function is invoked on the arguments. If the invocation of the JavaScript function completes abruptly for any reason, then the invocation of the primitive function also completes abruptly for the same reason. Otherwise, if the invocation of the JavaScript function does not complete, then the invocation of the primitive function does not complete either. Otherwise, the primitive function returns the values returned by the JavaScript function.

A closure is invoked as follows:

-
If the number of variables in the parameter list of the lambda abstraction recorded by the closure and the number of arguments are different, then the invocation completes abruptly with a reason of type error. (As we will see in the reference manual, it is actually possible to create closures accepting a variable number of arguments.) Otherwise, let $\var_1,\ldots,\var_n$ be the variables composing the parameter list of the lambda abstraction recorded by the closure, $\arg_1,\ldots,\arg_n$ be the arguments, and $\lexenv$ and $\dynenv$ be the following environments:
+
If the number of variables in the parameter list of the lambda abstraction recorded by the closure and the number of arguments are different, then the invocation completes abruptly for a reason of type error. (As we will see in the reference manual, it is actually possible to create closures accepting a variable number of arguments.) Otherwise, let $\var_1,\ldots,\var_n$ be the variables composing the parameter list of the lambda abstraction recorded by the closure, $\arg_1,\ldots,\arg_n$ be the arguments, and $\lexenv$ and $\dynenv$ be the following environments:

If the closure results from the evaluation of a _vlambda-form or an _mlambda-form, then $\lexenv$ is the environment extending the lexical environment recorded by the closure to bind, in the value namespace, the variable $\var_i$ to the argument $\arg_i$ (for all $i$ from $1$ to $n$) and $\dynenv$ is the current dynamic environment.

If the closure results from the evaluation of an _flambda-form, then $\lexenv$ is the environment extending the lexical environment recorded by the closure to bind, in the function namespace, the variable $\var_i$ to the argument $\arg_i$ (for all $i$ from $1$ to $n$) and $\dynenv$ is the current dynamic environment.

If the closure results from the evaluation of a _dlambda-form, then $\lexenv$ is the lexical environment recorded by the closure and $\dynenv$ is the environment extending the current dynamic environment to bind, in the value namespace, the variable $\var_i$ to the argument $\arg_i$ (for all $i$ from $1$ to $n$).

-
The objects composing the body of the lambda abstraction recorded by the closure are evaluated with respect to $\lexenv$ and $\dynenv$ as if they were the serial-forms of a progn-form. If the evaluation of the progn-form completes abruptly for any reason, then the invocation also completes abruptly for the same reason. Otherwise, if the evaluation of the progn-form does not complete, then the invocation does not complete either. Otherwise, the closure returns the values of the progn-form.
+
The objects composing the body of the lambda abstraction recorded by the closure are evaluated with respect to $\lexenv$ and $\dynenv$ as if they were the serial-forms of a progn-form. (The serial-forms are said to belong to an implicit progn-form.) If the evaluation of the progn-form completes abruptly for any reason, then the invocation also completes abruptly for the same reason. Otherwise, if the evaluation of the progn-form does not complete, then the invocation does not complete either. Otherwise, the closure returns the values of the progn-form.

When the evaluation of a top-level form completes abruptly for a reason of type exit, that reason is immediately converted into a reason of type error. The three possible outcomes of the evaluation of a top-level form are thus the following:

As we will see in the reference manual, the evaluation of a top-level form cannot complete abruptly for a reason of type nonlocal-exit. The three possible outcomes of the evaluation of a top-level form are thus the following:

The evaluation of the top-level form completes normally.
The evaluation of the top-level form completes abruptly for a reason of type error.
The evaluation of the top-level form does not complete.

The special operators _vlambda, _mlambda, _flambda, and _dlambda have an underscore at the beginning of their names to distinguish them from the similarly named macros vlambda, mlambda, flambda, and dlambda. The purpose of those macros is to facilitate the creation of closures accepting a variable number of arguments. The special operator _for-each has an underscore at the beginning of its name because it is a hack only needed and implemented by some of the interpreters. The special operator _catch-errors has an underscore at the beginning of its name because it will eventually be replaced by another special operator.

The special operators _vlambda, _mlambda, _flambda, and _dlambda have an underscore at the beginning of their names to distinguish them from the similarly named macros vlambda, mlambda, flambda, and dlambda. The purpose of those macros is to facilitate the creation of closures accepting a variable number of arguments. The special operator _handler-bind has an underscore at the beginning of its name to distinguish it from the similarly named macro handler-bind. The special operator _for-each has an underscore at the beginning of its name because it is a hack only needed and implemented by some of the interpreters.

The evaluator uses a data structure called the control stack to coordinate its activities. Each time a top-level form is submitted to the evaluator, a new control stack is created that will be used throughout the evaluation of the form. The same control stack is used to evaluate the top-level form and all non-top-level forms whose evaluations are entailed by the evaluation of the top-level form.

An evaluation/invocation that completes normally produces a result/output consisting of zero or more objects. The production of that result/output, which only occurs if the evaluation/invocation completes normally, is the primary effect of the evaluation/invocation. In addition to or in place of its primary effect, an evaluation/invocation can also have secondary effects called side effects. Examples of side effects are:

The prompt is the greater-than sign printed at the beginning of a line to inform you that the listener buffer is waiting for a form to be typed in.
If you press the Return or Enter key when (1) the cursor is not at the very end of the buffer or (2) the form is missing or incomplete, then a newline is simply inserted into the buffer and no evaluation takes place.
If the evaluation completes abruptly, then the reason is necessarily of type error and its payload (an object of type string describing the error) is printed in place of the printable representations of the (nonexisting) resulting values.
If the evaluation completes abruptly, then the reason of the abrupt completion is necessarily of type error and the payload of the reason (a string describing the error) is printed in place of the printable representations of the (nonexisting) resulting values.
If the evaluation does not complete, then you must abort the evaluation or restart the evaluator in order to get a new prompt.

We will now illustrate some of the concepts introduced in the section Programming Language by providing a commented transcript of a sequence of evaluations conducted in a listener buffer. If you want to reproduce the evaluations, be sure to start with a fresh Trampoline++ evaluator. To get a fresh Trampoline++ evaluator, restart the evaluator (using the Restart Evaluator… command from the Eval menu) with Trampoline++ selected as the evaluator name.

> (car '(1 2 3))⏎
1

The evaluation produces a result consisting of the first element of the list (1 2 3). Because lists are not self-evaluating, quoting the list is necessary.

> (car (1 2 3))⏎
ERROR: The operator-form does not evaluate to a function.

The evaluation completes abruptly with a reason of type error if the list is not quoted. The explanation for this behavior is as follows: The evaluator treats the list (1 2 3) as a plain function call and the operator-form, the number 1, does not evaluate to a function.

The evaluation completes abruptly for a reason of type error if the list is not quoted. The explanation for this behavior is as follows: The evaluator treats the list (1 2 3) as a plain function call and the operator-form, the number 1, does not evaluate to a function.

> (cdr '(1 2 3))⏎
(2 3)

The evaluation produces a result consisting of the sublist of the list (1 2 3) obtained by omitting its first element.

> (car (cdr '(1 2 3)))⏎
2

> (cdr (cdr (cdr '(1 2 3))))⏎
()

The evaluation produces a result consisting of the sublist of the list (1 2 3) obtained by omitting its first three elements.

> (car (cdr (cdr (cdr '(1 2 3)))))⏎
ERROR: The 1st argument is not of type EVLCons.

The evaluation completes abruptly with a reason of type error because the empty list is not a cons.

The evaluation completes abruptly for a reason of type error because the empty list is not a cons.

> (disk-area 2)⏎
ERROR: The variable 'disk-area' is unbound in the FUNCTION namespace.

The evaluation completes abruptly with a reason of type error because the global function disk-area is undefined.

The evaluation completes abruptly for a reason of type error because the global function disk-area is undefined.

> (fdef disk-area (r) (* 3.14 r r))⏎
disk-area

The evaluation produces a result consisting of the variable disk-area. More importantly, the evaluation has the side effect of defining the global function disk-area. In its intended usage, the function accepts the radius of a disk and returns the area of the disk computed using 3.14 as the value of pi. When the function is invoked, its body is evaluated with respect to a lexical environment binding, in the value namespace, the variable r to the argument of the invocation (that is, the radius of the disk).

> (disk-area 2)⏎
12.56

> (fdef disk-area (r) (* *pi* r r))⏎
disk-area

The evaluation has the side effect of redefining the global function disk-area to compute the area of the disk using the value of the global variable *pi* as the value of pi. It is customary for a global or dynamic variable to have a name starting and ending with an asterisk.

> (disk-area 2)⏎
ERROR: The variable '*pi*' is unbound in the VALUE namespace.

The evaluation completes abruptly with a reason of type error because the global variable *pi* is undefined.

The evaluation completes abruptly for a reason of type error because the global variable *pi* is undefined.

> (vdef *pi* 3.141593)⏎
*pi*

The evaluation produces a result consisting of the variable *pi*. More importantly, the evaluation has the side effect of defining the global variable *pi*.

> *pi*⏎
3.141593

Otherwise, if the first nonblank character before the cursor position is the last character of a top-level form, then that form is selected for evaluation.
Otherwise, no form is selected for evaluation and no evaluation takes place.

If the evaluation of the top-level form completes normally, then the printable representations of the resulting values are printed in the minibuffer, separated by a comma. If the evaluation of the top-level form completes abruptly, then the reason is necessarily of type error and its payload is printed in the minibuffer. If the evaluation of the top-level form does not complete, then no new evaluation is possible until the evaluation is aborted or the evaluator is restarted.

If the evaluation of the top-level form completes normally, then the printable representations of the resulting values are printed in the minibuffer, separated by a comma. If the evaluation of the top-level form completes abruptly, then the reason of the abrupt completion is necessarily of type error and the payload of the reason is printed in the minibuffer. If the evaluation of the top-level form does not complete, then no new evaluation is possible until the evaluation is aborted or the evaluator is restarted.

Load Buffer

Evaluates the top-level forms contained inside the selected file buffer.

This command is only available when the selected window displays the contents of an EVLambda source file.

The top-level forms contained inside the selected file buffer are evaluated as if they were part of a progn-form.

If the evaluation of the progn-form completes normally, then the printable representations of the resulting values are printed in the minibuffer, separated by a comma. If the evaluation of the progn-form completes abruptly, then the reason is necessarily of type error and its payload is printed in the minibuffer. If the evaluation of the progn-form does not complete, then no new evaluation is possible until the evaluation is aborted or the evaluator is restarted.

If the evaluation of the progn-form completes normally, then the printable representations of the resulting values are printed in the minibuffer, separated by a comma. If the evaluation of the progn-form completes abruptly, then the reason of the abrupt completion is necessarily of type error and the payload of the reason is printed in the minibuffer. If the evaluation of the progn-form does not complete, then no new evaluation is possible until the evaluation is aborted or the evaluator is restarted.

Abort Evaluation

Aborts the current evaluation.

Restart Evaluator…

Signaling and Handling Conditions

(error <string>)

(_catch-errors <form>)

(_catch-errors <form>*)

Implementation Notes

Reference Manual

Documentation Generator

Semantics

Primitive Data Types and Primitive Functions

Primitive Data Types

Primitive Data Type `object` and Related Primitive Functions

Primitive Data Type `void` and Related Primitive Functions

Primitive Data Type `boolean` and Related Primitive Functions

Primitive Data Type `number` and Related Primitive Functions

Primitive Data Type `character` and Related Primitive Functions

Primitive Data Type `string` and Related Primitive Functions

Primitive Data Type `symbol` and Related Primitive Functions

Primitive Data Type `keyword` and Related Primitive Functions

Primitive Data Type `variable` and Related Primitive Functions

Primitive Data Type `list` and Related Primitive Functions

Primitive Data Type `empty-list` and Related Primitive Functions

Primitive Data Type `cons` and Related Primitive Functions

Primitive Data Type `vector` and Related Primitive Functions

Primitive Data Type `function` and Related Primitive Functions

Primitive Data Type `primitive-function` and Related Primitive Functions

Primitive Data Type `closure` and Related Primitive Functions

Miscellaneous Primitive Functions

Forms

Advanced Control Structures

Special Forms `block`/`return-from`

Special Forms `catch`/`throw`

Special Form `_handler-bind`

Special Form `unwind-protect`

Special Form `_for-each`

Special Form `_catch-errors`

Function Calls

Evaluation Rules in Continuation-Passing Style

Comparison Operators

Load Buffer

Abort Evaluation

Restart Evaluator…

Implementation Notes

Reference Manual

Documentation Generator

Semantics

Primitive Data Types and Primitive Functions

Primitive Data Types

Primitive Data Type object and Related Primitive Functions

Primitive Data Type void and Related Primitive Functions

Primitive Data Type boolean and Related Primitive Functions

Primitive Data Type number and Related Primitive Functions

Primitive Data Type character and Related Primitive Functions

Primitive Data Type string and Related Primitive Functions

Primitive Data Type symbol and Related Primitive Functions

Primitive Data Type keyword and Related Primitive Functions

Primitive Data Type variable and Related Primitive Functions

Primitive Data Type list and Related Primitive Functions

Primitive Data Type empty-list and Related Primitive Functions

Primitive Data Type cons and Related Primitive Functions

Primitive Data Type vector and Related Primitive Functions

Primitive Data Type function and Related Primitive Functions

Primitive Data Type primitive-function and Related Primitive Functions

Primitive Data Type closure and Related Primitive Functions

Miscellaneous Primitive Functions

Forms

Advanced Control Structures

Special Forms block/return-from

Special Forms catch/throw

Special Form _handler-bind

Special Form unwind-protect

Special Form _for-each

Special Form _catch-errors

Function Calls

Evaluation Rules in Continuation-Passing Style

Comparison Operators

Load Buffer

Abort Evaluation

Restart Evaluator…

Primitive Data Type `object` and Related Primitive Functions

Primitive Data Type `void` and Related Primitive Functions

Primitive Data Type `boolean` and Related Primitive Functions

Primitive Data Type `number` and Related Primitive Functions

Primitive Data Type `character` and Related Primitive Functions

Primitive Data Type `string` and Related Primitive Functions

Primitive Data Type `symbol` and Related Primitive Functions

Primitive Data Type `keyword` and Related Primitive Functions

Primitive Data Type `variable` and Related Primitive Functions

Primitive Data Type `list` and Related Primitive Functions

Primitive Data Type `empty-list` and Related Primitive Functions

Primitive Data Type `cons` and Related Primitive Functions

Primitive Data Type `vector` and Related Primitive Functions

Primitive Data Type `function` and Related Primitive Functions

Primitive Data Type `primitive-function` and Related Primitive Functions

Primitive Data Type `closure` and Related Primitive Functions

Special Forms `block`/`return-from`

Special Forms `catch`/`throw`

Special Form `_handler-bind`

Special Form `unwind-protect`

Special Form `_for-each`

Special Form `_catch-errors`