From: Raphaël Van Dyck Date: Wed, 21 Jan 2026 19:33:01 +0000 (+0100) Subject: revise user manual, tutorial, and reference manual X-Git-Url: http://evlambda.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=a2767030d1c506f4331b2d0a2ad18a171ae63f81;p=evlambda.git revise user manual, tutorial, and reference manual --- diff --git a/system-files/REFERENCE-MANUAL b/system-files/REFERENCE-MANUAL index 20694ee..77f389a 100644 --- a/system-files/REFERENCE-MANUAL +++ b/system-files/REFERENCE-MANUAL @@ -15,7 +15,7 @@ $\DeclareMathOperator{\pat}{pat}$

Reference Manual

-

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

+

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.

Syntax

Introduction

Listener Buffers

@@ -170,10 +170,10 @@

The following table summarizes the syntax of the regular expressions used in this document:

- - - - + + + + @@ -213,7 +213,7 @@ - + @@ -229,12 +229,12 @@ - + - + @@ -555,7 +555,7 @@
$\metavar{input}\Coloneq$ $\metavar{object}$
$\mathcal{M}(\metavar{input})=\langle\mathcal{M}(\metavar{object})\rangle$
-
$\metavar{input}\Coloneq$ $\metavarn{object}{1}$ $\ldots$ $\metavarn{object}{n\geq0}$
+
$\metavar{input}\Coloneq$ $\metavarn{object}{1}\ldots\metavarn{object}{n\geq0}$
$\mathcal{M}(\metavar{input})=\langle\mathcal{M}(\metavarn{object}{1}),\ldots,\mathcal{M}(\metavarn{object}{n})\rangle$
$\metavar{input}\Coloneq$ $\metavar{xml-comment}$* $\metavar{xml-element}$ $\metavar{xml-comment}$*
$\mathcal{M}(\metavar{input})=\mathcal{M}(\metavar{xml-element})$
@@ -565,7 +565,7 @@
$\metavar{xml-markup}\Coloneq$ $\metavar{xml-comment}$
$\mathcal{M}(\metavar{xml-markup})=\mathcal{M}(\metavar{xml-comment})$
-
$\metavar{xml-element}\Coloneq$ xml-start-tag $\metavarn{xml-element-content}{1}$ $\ldots$ $\metavarn{xml-element-content}{n\geq0}$ xml-end-tag
+
$\metavar{xml-element}\Coloneq$ xml-start-tag $\metavarn{xml-element-content}{1}\ldots\metavarn{xml-element-content}{n\geq0}$ xml-end-tag
$\mathcal{M}(\metavar{xml-element})=\mathcal{M}(\metavarn{xml-element-content}{1})\|\cdots\|\mathcal{M}(\metavarn{xml-element-content}{n})$
$\metavar{xml-element}\Coloneq$ xml-empty-element-tag
$\mathcal{M}(\metavar{xml-element})=\langle\rangle$
@@ -627,13 +627,13 @@
$\metavar{proper-list}\Coloneq$ left-parenthesis right-parenthesis
$\mathcal{M}(\metavar{proper-list})=$ the empty list
-
$\metavar{proper-list}\Coloneq$ left-parenthesis $\metavarn{object}{1}$ $\ldots$ $\metavarn{object}{n\geq1}$ right-parenthesis
+
$\metavar{proper-list}\Coloneq$ left-parenthesis $\metavarn{object}{1}\ldots\metavarn{object}{n\geq1}$ right-parenthesis
$\mathcal{M}(\metavar{proper-list})=$ the first cons of a chain of $n$ conses $\cons_1,\ldots,\cons_n$ such that the car of $\cons_i$ is $\mathcal{M}(\metavarn{object}{i})$, the cdr of $\cons_{i\lt n}$ is $\cons_{i+1}$, and the cdr of $\cons_n$ is the empty list
-
$\metavar{dotted-list}\Coloneq$ left-parenthesis $\metavarn{object}{1}$ $\ldots$ $\metavarn{object}{n\geq1}$ dot $\metavarn{object}{n+1}$ right-parenthesis
+
$\metavar{dotted-list}\Coloneq$ left-parenthesis $\metavarn{object}{1}\ldots\metavarn{object}{n\geq1}$ dot $\metavarn{object}{n+1}$ right-parenthesis
$\mathcal{M}(\metavar{dotted-list})=$ the first cons of a chain of $n$ conses $\cons_1,\ldots,\cons_n$ such that the car of $\cons_i$ is $\mathcal{M}(\metavarn{object}{i})$, the cdr of $\cons_{i\lt n}$ is $\cons_{i+1}$, and the cdr of $\cons_n$ is $\mathcal{M}(\metavarn{object}{n+1})$
-
$\metavar{vector}\Coloneq$ hash-left-parenthesis $\metavarn{object}{1}$ $\ldots$ $\metavarn{object}{n\geq0}$ right-parenthesis
+
$\metavar{vector}\Coloneq$ hash-left-parenthesis $\metavarn{object}{1}\ldots\metavarn{object}{n\geq0}$ right-parenthesis
$\mathcal{M}(\metavar{vector})=$ a vector of $n$ elements $\mlvar{elem}_1,\ldots,\mlvar{elem}_n$ such that $\mlvar{elem}_i$ is $\mathcal{M}(\metavarn{object}{i})$

Note that the XML markup inside abbreviations, lists, and vectors cannot produce objects and has therefore been omitted from the definition of the function $\mathcal{M}$.

@@ -723,9 +723,9 @@
  • An object matches the name of a type if and only if the object is a member of the type.
  • An object matches a readable representation if and only if the object is (or is eql to) the object denoted by the readable representation.
  • An object matches the pattern () if and only if the object is the empty list.
    • -
  • An object matches the pattern ($\metavarn{pattern}{1}$ $\ldots$ $\metavarn{pattern}{n\geq0}$) if and only if the object is the first cons of a chain of $n$ conses $\cons_1,\ldots,\cons_n$ such that the car of $\cons_i$ matches $\metavarn{pattern}{i}$, the cdr of $\cons_{i\lt n}$ is $\cons_{i+1}$, and the cdr of $\cons_n$ is the empty list.
    • -
  • An object matches the pattern ($\metavarn{pattern}{1}$ $\ldots$ $\metavarn{pattern}{n\geq1}$ . $\metavarn{pattern}{n+1}$) if and only if the object is the first cons of a chain of $n$ conses $\cons_1,\ldots,\cons_n$ such that the car of $\cons_i$ matches $\metavarn{pattern}{i}$, the cdr of $\cons_{i\lt n}$ is $\cons_{i+1}$, and the cdr of $\cons_n$ matches $\metavarn{pattern}{n+1}$.
    • -
  • An object matches the pattern #($\metavarn{pattern}{1}$ $\ldots$ $\metavarn{pattern}{n\geq0}$) if and only if the object is a vector of $n$ elements $\mlvar{elem}_1,\ldots,\mlvar{elem}_n$ such that $\mlvar{elem}_i$ matches $\metavarn{pattern}{i}$.
    • +
  • An object matches the pattern ($\metavarn{pattern}{1}\ldots\metavarn{pattern}{n\geq0}$) if and only if the object is the first cons of a chain of $n$ conses $\cons_1,\ldots,\cons_n$ such that the car of $\cons_i$ matches $\metavarn{pattern}{i}$, the cdr of $\cons_{i\lt n}$ is $\cons_{i+1}$, and the cdr of $\cons_n$ is the empty list.
    • +
  • An object matches the pattern ($\metavarn{pattern}{1}\ldots\metavarn{pattern}{n\geq1}$ . $\metavarn{pattern}{n+1}$) if and only if the object is the first cons of a chain of $n$ conses $\cons_1,\ldots,\cons_n$ such that the car of $\cons_i$ matches $\metavarn{pattern}{i}$, the cdr of $\cons_{i\lt n}$ is $\cons_{i+1}$, and the cdr of $\cons_n$ matches $\metavarn{pattern}{n+1}$.
    • +
  • An object matches the pattern #($\metavarn{pattern}{1}\ldots\metavarn{pattern}{n\geq0}$) if and only if the object is a vector of $n$ elements $\mlvar{elem}_1,\ldots,\mlvar{elem}_n$ such that $\mlvar{elem}_i$ matches $\metavarn{pattern}{i}$.

    • By way of example, let us consider the template language specified by the following context-free grammar:

    SyntaxMeaning
    '$\ldots$'literal string (literal single quotes and backslashes must be escaped)
    "$\ldots$"literal string (literal double quotes and backslashes must be escaped)
    [$\ldots$]positive character class (literal carets, hyphens, closing square brackets, and backslashes must be escaped)
    [^$\ldots$]negative character class (literal carets, hyphens, closing square brackets, and backslashes must be escaped)
    '…'literal string (literal single quotes and backslashes must be escaped)
    "…"literal string (literal double quotes and backslashes must be escaped)
    […]positive character class (literal carets, hyphens, closing square brackets, and backslashes must be escaped)
    [^…]negative character class (literal carets, hyphens, closing square brackets, and backslashes must be escaped)
    $\mlvar{char}_1$-$\mlvar{char}_2$range of characters (inside character classes)
    $\mlvar{re}_1\mlvar{re}_2$concatenation operation
    $\mlvar{re}_1$|$\mlvar{re}_2$union (alternation) operation
    $\metavar{nonterminal}$nonterminal symbol
    terminalterminal symbol
    $\epsilon$empty sequence of symbols
    $\mlvar{rhs}_1$ | $\ldots$ | $\mlvar{rhs}_n$union (alternation) operation
    $\mlvar{rhs}_1$ | … | $\mlvar{rhs}_n$union (alternation) operation
    $\mlvar{symbol}$*zero-or-more-times (Kleene star) operation
    $\mlvar{symbol}$+one-or-more-times (Kleene plus) operation
    $\mlvar{symbol}$?zero-or-one-time (optional) operation
    $\metavar{valid-char}$ $\Coloneq$[\C{L}\C{M}\C{N}\C{P}\C{S}\C{Z}\U{09}-\U{0D}\U{85}\C{Cf}\C{Co}][\C{L}\C{M}\C{N}\C{P}\C{S}\C{Z}\U{0009}-\U{000D}\U{0085}\C{Cf}\C{Co}]
    $\metavar{whitespace-char}$ $\Coloneq$[\U{09}-\U{0D}\U{20}\U{85}\U{200E}\U{200F}\U{2028}\U{2029}][\U{0009}-\U{000D}\U{0020}\U{0085}\U{200E}\U{200F}\U{2028}\U{2029}]
    $\metavar{syntax-char}$
    @@ -803,7 +803,7 @@ - + @@ -951,14 +951,14 @@ - + - + - + - + @@ -1007,7 +1007,7 @@ - + @@ -1017,7 +1017,7 @@ - +
    $\metavar{special-form}$ $\Coloneq$$\metavar{quote-form}$ | $\metavar{progn-form}$ | $\metavar{if-form}$ | $\metavar{lambda-abstraction}$ | $\metavar{variable-reference}$ | $\metavar{variable-assignment}$ | $\metavar{\_for-each-form}$ | $\metavar{\_catch-errors-form}$ | $\metavar{multiple-value-call-form}$ | $\metavar{apply-form}$ | $\metavar{multiple-value-apply-form}$$\metavar{quote-form}$ | $\metavar{progn-form}$ | $\metavar{if-form}$ | $\metavar{lambda-abstraction}$ | $\metavar{variable-reference}$ | $\metavar{variable-assignment}$ | $\metavar{\_for-each-form}$ | $\metavar{\_catch-errors-form}$ | $\metavar{apply-form}$ | $\metavar{multiple-value-call-form}$ | $\metavar{multiple-value-apply-form}$
    $\metavar{quote-form}$$\metavar{form}$
    $\metavar{multiple-value-call-form}$$\metavar{apply-form}$ $\Coloneq$(multiple-value-call $\metavar{operator-form}$ $\metavar{operand-form}$*)(apply $\metavar{operator-form}$ $\metavar{operand-form}$*)
    $\metavar{apply-form}$$\metavar{multiple-value-call-form}$ $\Coloneq$(apply $\metavar{operator-form}$ $\metavar{operand-form}$*)(multiple-value-call $\metavar{operator-form}$ $\metavar{operand-form}$*)
    $\metavar{multiple-value-apply-form}$
    $\metavar{special-operator}$ $\Coloneq$quote | progn | if | _vlambda | _mlambda | _flambda | _dlambda | vref | fref | dref | vset! | fset! | dset! | _for-each | _catch-errors | multiple-value-call | apply | multiple-value-applyquote | progn | if | _vlambda | _mlambda | _flambda | _dlambda | vref | fref | dref | vset! | fset! | dset! | _for-each | _catch-errors | apply | multiple-value-call | multiple-value-apply
    $\metavar{call}$
    $\metavar{function-call}$ $\Coloneq$$\metavar{plain-function-call}$ | $\metavar{multiple-value-call-form}$ | $\metavar{apply-form}$ | $\metavar{multiple-value-apply-form}$$\metavar{plain-function-call}$ | $\metavar{apply-form}$ | $\metavar{multiple-value-call-form}$ | $\metavar{multiple-value-apply-form}$

    The variables quasiquote, unquote, and unquote-splicing are not special operators. The variable quasiquote is the name of a global macro and the variables unquote and unquote-splicing are variables having special meanings in the context of a call to the global macro quasiquote.

    @@ -1047,5 +1047,169 @@

    The second step of the documentation generation process converts the XML document into the following HTML document:

    <html>
      <head>
      </head>
      <body>
        <h1>Recursive Functions</h1>
        <p>...para...</p>
        <p>...para...</p>
        <h2>Factorial Function</h2>
        <p>...para...</p>
        <p>...para...</p>
        <pre class="blockcode">(fdef fact (n)</pre>
        <div class="indentation" style="margin-left: 2ch;">
          <div class="blockcomment">
            <p>...block...</p>
            <p>...block...</p>
          </div>
        </div>
        <pre class="blockcode">
      (if (= n 0)
          1 <span class="eolcomment">...eol...</span>
        (* n (fact (- n 1))))) ⇰
    <span class="eolcomment">...eoll...</span></pre>
        <pre class="blockcode">(test 1 (fact 0))
    (test 120 (fact 5))
    (test 3628800 (fact 10))</pre>
        <h2>Fibonacci Sequence</h2>
        <p>...para...</p>
        <p>...para...</p>
        <pre class="blockcode">(fdef fib (n)</pre>
        <div class="indentation" style="margin-left: 2ch;">
          <div class="blockcomment">
            <p>...block...</p>
            <p>...block...</p>
          </div>
        </div>
        <pre class="blockcode">
      (if (= n 0)
          0 <span class="eolcomment">...eol...</span>
        (if (= n 1)
            1 <span class="eolcomment">...eol...</span>
          (+ (fib (- n 1)) (fib (- n 2)))))) ⇰
    <span class="eolcomment">...eoll...</span></pre>
        <pre class="blockcode">(test 0 (fib 0))
    (test 5 (fib 5))
    (test 55 (fib 10))</pre>
      </body>
    </html>
    +

    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.

    +

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

    +

    Primitive Data Types

    +

    Here is a tree-view representation of the hierarchy of primitive data types:

    + 
    object
      |-void
      |-boolean
      |-number
      |-character
      |-string
      |-symbol
      |   |-keyword
      |   |-variable
      |-list
      |   |-empty-list
      |   |-cons
      |-vector
      |-function
      |   |-primitive-function
      |   |-closure
    +

    Primitive Data Type object and Related Primitive Functions

    +
    +
    (object? $\object$)
    +
    The primitive function returns #t if $\object$ is of type object (which is always the case) and #f otherwise.
    +
    (eq? $\object_1$ $\object_2$)
    +
    The primitive function is an equality predicate. It returns #t if and only if the two objects are one and the same. In other words, it returns #t if and only if the two objects have the same address in the heap.
    +
    (eql? $\object_1$ $\object_2$)
    +
    The primitive function is an equality predicate. If both objects are of type number, then it returns #t if and only if the two objects represent the same mathematical number. Otherwise, if both objects are of type character, then it returns #t if and only if the two objects represent the same UTF-$16$ code unit. Otherwise, if both objects are of type string, then it returns #t if and only if the two objects represent the same indexed sequence of UTF-$16$ code units. Otherwise, it returns #t if and only if the two objects are eq?.
    +
    +

    Primitive Data Type void and Related Primitive Functions

    +
    +
    (void? $\object$)
    +
    The primitive function returns #t if $\object$ is of type void and #f otherwise.
    +
    +

    Primitive Data Type boolean and Related Primitive Functions

    +
    +
    (boolean? $\object$)
    +
    The primitive function returns #t if $\object$ is of type boolean and #f otherwise.
    +
    +

    Primitive Data Type number and Related Primitive Functions

    +

    Objects of type number represent mathematical numbers using the floating-point format IEEE 754 binary 64. +

    +
    (number? $\object$)
    +
    The primitive function returns #t if $\object$ is of type number and #f otherwise.
    +
    (_+ $\number_1$ $\number_2$)
    +
    The primitive function returns the sum $\number_1+\number_2$.
    +
    (_- $\number_1$ $\number_2$)
    +
    The primitive function returns the difference $\number_1-\number_2$.
    +
    (_* $\number_1$ $\number_2$)
    +
    The primitive function returns the product $\number_1\times\number_2$.
    +
    (_/ $\number_1$ $\number_2$)
    +
    The primitive function returns the quotient $\number_1\div\number_2$.
    +
    (% $\number_1$ $\number_2$)
    +
    The primitive function returns the remainder of the division of $\number_1$ by $\number_2$ when the quotient is forced to be an integer.
    +
    (= $\number_1$ $\number_2$)
    +
    The primitive function returns #t if $\number_1$ and $\number_2$ are numerically equal and #f otherwise.
    +
    (/= $\number_1$ $\number_2$)
    +
    The primitive function returns #t if $\number_1$ and $\number_2$ are numerically different and #f otherwise.
    +
    (< $\number_1$ $\number_2$)
    +
    The primitive function returns #t if $\number_1$ is numerically less than $\number_2$ and #f otherwise.
    +
    (<= $\number_1$ $\number_2$)
    +
    The primitive function returns #t if $\number_1$ is numerically less than or equal to $\number_2$ and #f otherwise.
    +
    (> $\number_1$ $\number_2$)
    +
    The primitive function returns #t if $\number_1$ is numerically greater than $\number_2$ and #f otherwise.
    +
    (>= $\number_1$ $\number_2$)
    +
    The primitive function returns #t if $\number_1$ is numerically greater than or equal to $\number_2$ and #f otherwise.
    +
    +

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

    +
    +
    (character? $\object$)
    +
    The primitive function returns #t if $\object$ is of type character and #f otherwise.
    +
    +

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

    +
    +
    (string? $\object$)
    +
    The primitive function returns #t if $\object$ is of type string and #f otherwise.
    +
    +

    Primitive Data Type symbol and Related Primitive Functions

    +
    +
    (symbol? $\object$)
    +
    The primitive function returns #t if $\object$ is of type symbol and #f otherwise.
    +
    +

    Primitive Data Type keyword and Related Primitive Functions

    +
    +
    (keyword? $\object$)
    +
    The primitive function returns #t if $\object$ is of type keyword and #f otherwise.
    +
    (make-keyword? $\string$)
    +
    The primitive function returns a new keyword whose name is $\string$. The keyword is not interned.
    +
    +

    Primitive Data Type variable and Related Primitive Functions

    +
    +
    (variable? $\object$)
    +
    The primitive function returns #t if $\object$ is of type variable and #f otherwise.
    +
    (make-variable $\string$)
    +
    The primitive function returns a new variable whose name is $\string$. The variable is not interned.
    +
    (variable-value $\variable$)
    +
    If there exists a binding for $\variable$ in the value namespace of the global environment, then the primitive function returns the value of that binding. Otherwise, the primitive function returns #v.
    +
    (variable-set-value! $\variable$ $\object$)
    +
    If there exists a binding for $\variable$ in the value namespace of the global environment, then the primitive function replaces the value of that binding by $\object$. Otherwise, the primitive function adds to the value namespace of the global environment a new binding between $\variable$ and $\object$. In both cases, the primitive function returns $\object$.
    +
    (variable-value-bound? $\variable$)
    +
    If there exists a binding for $\variable$ in the value namespace of the global environment, then the primitive function returns #t. Otherwise, the primitive function returns #f.
    +
    (variable-unbind-value! $\variable$)
    +
    If there exists a binding for $\variable$ in the value namespace of the global environment, then that binding is deleted and the primitive function returns #v. Otherwise, the primitive function simply returns #v.
    +
    (variable-function $\variable$)
    +
    If there exists a binding for $\variable$ in the function namespace of the global environment, then the primitive function returns the value of that binding. Otherwise, the primitive function returns #v.
    +
    (variable-set-function! $\variable$ $\object$)
    +
    If there exists a binding for $\variable$ in the function namespace of the global environment, then the primitive function replaces the value of that binding by $\object$. Otherwise, the primitive function adds to the function namespace of the global environment a new binding between $\variable$ and $\object$. In both cases, the primitive function returns $\object$.
    +
    (variable-function-bound? $\variable$)
    +
    If there exists a binding for $\variable$ in the function namespace of the global environment, then the primitive function returns #t. Otherwise, the primitive function returns #f.
    +
    (variable-unbind-function! $\variable$)
    +
    If there exists a binding for $\variable$ in the function namespace of the global environment, then that binding is deleted and the primitive function returns #v. Otherwise, the primitive function simply returns #v.
    +
    +

    Primitive Data Type list and Related Primitive Functions

    +
    +
    (list? $\object$)
    +
    The primitive function returns #t if $\object$ is of type list and #f otherwise.
    +
    +

    Primitive Data Type empty-list and Related Primitive Functions

    +
    +
    (empty-list? $\object$)
    +
    The primitive function returns #t if $\object$ is of type empty-list and #f otherwise.
    +
    +

    Primitive Data Type cons and Related Primitive Functions

    +
    +
    (cons? $\object$)
    +
    The primitive function returns #t if $\object$ is of type cons and #f otherwise.
    +
    (cons $\object_1$ $\object_2$)
    +
    The primitive function returns a new cons whose first element is $\object_1$ and whose second element is $\object_2$.
    +
    (car $\cons$)
    +
    The primitive function returns the first element of $\cons$.
    +
    (set-car! $\cons$ $\object$)
    +
    The primitive function replaces the first element of $\cons$ by $\object$ and returns $\object$.
    +
    (cdr $\cons$)
    +
    The primitive function returns the second element of $\cons$
    +
    (set-cdr! $\cons$ $\object$)
    +
    The primitive function replaces the second element of $\cons$ by $\object$ and returns $\object$.
    +
    +

    Primitive Data Type vector and Related Primitive Functions

    +
    +
    (vector? $\object$)
    +
    The primitive function returns #t if $\object$ is of type vector and #f otherwise.
    +
    +

    Primitive Data Type function and Related Primitive Functions

    +
    +
    (function? $\object$)
    +
    The primitive function returns #t if $\object$ is of type function and #f otherwise.
    +
    +

    Primitive Data Type primitive-function and Related Primitive Functions

    +
    +
    (primitive-function? $\object$)
    +
    The primitive function returns #t if $\object$ is of type primitive-function and #f otherwise.
    +
    +

    Primitive Data Type closure and Related Primitive Functions

    +
    +
    (closure? $\object$)
    +
    The primitive function returns #t if $\object$ is of type closure and #f otherwise.
    +
    +

    Miscellaneous Primitive Functions

    +
    +
    (values $\object_1\ldots\object_n$)
    +
    The primitive function converts its arguments into values: when invoked on the arguments $\object_1,\ldots,\object_n$, the primitive function returns the values $\object_1,\ldots,\object_n$.
    +
    (error $\string$)
    +
    The invocation of the primitive function always completes abnormally.
    +
    (now)
    +
    The primitive function returns the number of milliseconds elapsed since 1970-01-01 00:00:00.000 UTC.
    +
    diff --git a/system-files/TUTORIAL b/system-files/TUTORIAL index a355ee1..eafb2ff 100644 --- a/system-files/TUTORIAL +++ b/system-files/TUTORIAL @@ -32,7 +32,7 @@

    Data Type boolean

    (not $\boolean$)
    -
    The function returns #t if its argument is #f and #f if its argument is #t.
    +
    The function returns #t if $\boolean$ is #f and #f if $\boolean$ is #t.
    > (not #t)
    #f

    > (not #f)
    #t
    @@ -78,41 +78,41 @@

    Comparison Operators

    (= $\number_1$ $\number_2$)
    -
    The function returns #t if its two arguments are equal and #f otherwise.
    +
    The function returns #t if $\number_1$ and $\number_2$ are numerically equal and #f otherwise.
    (/= $\number_1$ $\number_2$)
    -
    The function returns #t if its two arguments are different and #f otherwise.
    +
    The function returns #t if $\number_1$ and $\number_2$ are numerically different and #f otherwise.
    (< $\number_1$ $\number_2$)
    -
    The function returns #t if its first argument is less than its second argument and #f otherwise.
    +
    The function returns #t if $\number_1$ is numerically less than $\number_2$ and #f otherwise.
    (<= $\number_1$ $\number_2$)
    -
    The function returns #t if its first argument is less than or equal to its second argument and #f otherwise.
    +
    The function returns #t if $\number_1$ is numerically less than or equal to $\number_2$ and #f otherwise.
    (> $\number_1$ $\number_2$)
    -
    The function returns #t if its first argument is greater than its second argument and #f otherwise.
    +
    The function returns #t if $\number_1$ is numerically greater than $\number_2$ and #f otherwise.
    (>= $\number_1$ $\number_2$)
    -
    The function returns #t if its first argument is greater than or equal to its second argument and #f otherwise.
    +
    The function returns #t if $\number_1$ is numerically greater than or equal to $\number_2$ and #f otherwise.
    > (list (= -1 0) (= 0 0) (= 1 0))
    (#f #t #f)

    > (list (/= -1 0) (/= 0 0) (/= 1 0))
    (#t #f #t)

    > (list (< -1 0) (< 0 0) (< 1 0))
    (#t #f #f)

    > (list (<= -1 0) (<= 0 0) (<= 1 0))
    (#t #t #f)

    > (list (> -1 0) (> 0 0) (> 1 0))
    (#f #f #t)

    > (list (>= -1 0) (>= 0 0) (>= 1 0))
    (#f #t #t)

    The names of the comparison operators do not end with a question mark because they traditionally do not (in mathematics and other programming languages).

    Data Type list

    (list? $\object$)
    -
    The function returns #t if its argument is of type list and #f otherwise.
    +
    The function returns #t if $\object$ is of type list and #f otherwise.
    > (list? '())
    #t

    > (list? '(1 2 3))
    #t
    (list $\object_1\ldots\object_n$)
    -
    The function collects its arguments into a list: when invoked on the arguments $\object_1$, …, $\object_n$, the function returns a list whose elements are $\object_1$, …, $\object_n$.
    +
    The function collects its arguments into a list: when invoked on the arguments $\object_1,\ldots,\object_n$, the function returns a list whose elements are $\object_1,\ldots,\object_n$.
    > (list)
    ()

    > (list 1 2 3)
    (1 2 3)

    Data Type empty-list

    (empty-list? $\object$)
    -
    The function returns #t if its argument is of type empty-list and #f otherwise.
    +
    The function returns #t if $\object$ is of type empty-list and #f otherwise.
    > (empty-list? '())
    #t

    > (empty-list? '(1 2 3))
    #f

    Data Type cons

    (cons? $\object$)
    -
    The function returns #t if its argument is of type cons and #f otherwise.
    +
    The function returns #t if $\object$ is of type cons and #f otherwise.
    > (cons? '())
    #f

    > (cons? '(1 2 3))
    #t
    @@ -122,9 +122,9 @@ 
    > (cons 3 '())
    (3)

    > (cons 2 (cons 3 '()))
    (2 3)

    > (cons 1 (cons 2 (cons 3 '())))
    (1 2 3)
    (car $\cons$)
    -
    The function returns the first element of its argument.
    +
    The function returns the first element of $\cons$.
    (cdr $\cons$)
    -
    The function returns the second element of its argument.
    +
    The function returns the second element of $\cons$.
    > (car '(1 2 3))
    1

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

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

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

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

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

    Equality Predicates

    @@ -172,8 +172,8 @@
    • An evaluation trace is a sequence of lines.
    • Times flows from top to bottom.
      • -
    • Each recorded evaluation contributes two lines to the trace: an eval-in line of the form “The form $\form$ is evaluated with respect to $\lexenv$ and $\dynenv$.” recording the start of the evaluation and a matching eval-out line of the form “The form $\form$ evaluates to $\obj_1$, …, $\obj_n$.” recording the normal completion of the evaluation.
      • -
    • Each recorded invocation contributes two lines to the trace: an invoke-in line of the form “The function $\fun$ is invoked on $\obj_1$, …, $\obj_n$.” recording the start of the invocation and a matching invoke-out line of the form “The function $\fun$ returns $\obj_1$, …, $\obj_n$.” recording the normal completion of the invocation.
      • +
    • Each recorded evaluation contributes two lines to the trace: an eval-in line of the form “The form $\form$ is evaluated with respect to $\lexenv$ and $\dynenv$.” recording the start of the evaluation and a matching eval-out line of the form “The form $\form$ evaluates to $\obj_1,\ldots,\obj_n$.” recording the normal completion of the evaluation.
      • +
    • Each recorded invocation contributes two lines to the trace: an invoke-in line of the form “The function $\fun$ is invoked on $\obj_1,\ldots,\obj_n$.” recording the start of the invocation and a matching invoke-out line of the form “The function $\fun$ returns $\obj_1,\ldots,\obj_m$.” recording the normal completion of the invocation.
    • A step line is a free-form line recording a step other than an evaluation or invocation.
    • A comment line is a free-form line in italic type containing a comment.
    • Lexical and dynamic environments are represented as $[\binding_1,\ldots,\binding_n]$ where bindings in the value namespace are represented as $\var\vbind\obj$ and bindings in the function namespace are represented as $\var\fbind\obj$.
      • @@ -819,7 +819,7 @@
    • $F_3$ is computed from $F_2$ and $F_1$
    • …
    -

    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$, …, and $b$ is replaced by the next Fibonacci number in the sequence $F_1$, $F_2$, $F_3$, … 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_\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}}$.

    Here is an invocation trace of the evaluation of the form (fib-iter 6):

      diff --git a/system-files/USER-MANUAL b/system-files/USER-MANUAL index 7aff512..505a5f2 100644 --- a/system-files/USER-MANUAL +++ b/system-files/USER-MANUAL @@ -50,7 +50,7 @@
      closure
      Closures are input/output mappings implemented in EVLambda. Some closures are tagged as being a macro. Macros are code to code mappings used to create new language constructs. Closures have no readable representations and their printable representation is #<closure>.
    -

    Each symbol has an associated sequence of characters (called the name of the symbol) that serves as its readable representation. If the name of a symbol starts with a colon, then the symbol is a keyword. Otherwise, the symbol is a variable. The reader always converts the same name into the same symbol. To that end, the reader maintains two mappings from names to symbols called packages: one package mapping the names of the previously encountered variables to the corresponding variables and one package mapping the names of the previously encountered keywords to the corresponding keywords.

    +

    Each symbol has an associated sequence of characters called the name of the symbol. The readable representation of a keyword is its name preceded by a semicolon. The readable representation of a variable is its name. The reader always converts the same readable representation of a symbol into the same symbol. To that end, the reader maintains two mappings from names to symbols called packages: one package mapping the names of the previously encountered variables to the corresponding variables and one package mapping the names of the previously encountered keywords to the corresponding keywords. Adding a symbol to its package is called interning the symbol.

    The printable representation of a list consists of a left parenthesis followed by the printable representations of the elements of the list separated by a single space followed by a right parenthesis. The printable representation of a list is just one of its infinitely many readable representations. In particular, other readable representations can be obtained by using sequences of at least one whitespace character instead of single spaces to separate the elements of the list.

    Although a macro is technically a function (because a macro is an object of type closure and type closure is a subtype of type function), the word “function” is often used to denote specifically a function other than a macro (that is, a primitive function or a closure not tagged as being a macro).

    Variables name objects through the use of namespaces, bindings, environments, and lookup rules:

    @@ -133,7 +133,7 @@

    Evaluations are not all done with respect to the same lexical and dynamic environments. The lexical environment and the dynamic environments with respect to which a form is evaluated are referred to as “the current lexical environment” and “the current dynamic environment”, respectively.

    Top-level forms are evaluated with respect to an initial lexical environment and an initial dynamic environment that are both empty.

    A consequence of the evaluation rules stated later in this section is that non-top-level forms are evaluated with respect to (1) a lexical environment that is either the initial empty lexical environment or the result of extending, once or multiple times in sequence, the initial empty lexical environment and (2) a dynamic environment that is either the initial empty dynamic environment or the result of extending, once or multiple times in sequence, the initial empty dynamic environment.

    -

    Let $\env$ be an environment, $\ns$ be a namespace of the environment, $n$ be a nonnegative integer, $\var_1$, …, $\var_n$ be a sequence of $n$ distinct variables, and $\obj_1$, …, $\obj_n$ be a sequence of $n$ objects. The environment extending the environment $\env$ to bind, in the namespace $\ns$, the variable $\var_i$ to the object $\obj_i$ (for all $i$ from $1$ to $n$) is the environment obtained as follows:

    +

    Let $\env$ be an environment, $\ns$ be a namespace of the environment, $n$ be a nonnegative integer, $\var_1,\ldots,\var_n$ be a sequence of $n$ distinct variables, and $\obj_1,\ldots,\obj_n$ be a sequence of $n$ objects. The environment extending the environment $\env$ to bind, in the namespace $\ns$, the variable $\var_i$ to the object $\obj_i$ (for all $i$ from $1$ to $n$) is the environment obtained as follows:

    1. Copy the environment $\env$ in such a way that (1) the environment $\env$ and its copy are distinct (steps 2 and 3 below must have no effect on the environment $\env$) and (2) the environment $\env$ and its copy contain the exact same bindings (the bindings are not copied but shared between the two environments).
    2. For all $i$ from $1$ to $n$, delete from the copy of the namespace $\ns$ the binding for the variable $\var_i$, if it exists.
      3. @@ -186,6 +186,8 @@
    3. (fset! $\metavar{variable}$ $\metavar{value-form}$)
    4. (dref $\metavar{variable}$)
    5. (dset! $\metavar{variable}$ $\metavar{value-form}$)
      6. +
    6. (_for-each $\metavar{function-form}$ $\metavar{list-form}$)
      7. +
    7. (_catch-errors $\metavar{try-form}$)
    8. (apply $\metavar{operator-form}$ $\metavar{operand-forms}$)
    9. (multiple-value-call $\metavar{operator-form}$ $\metavar{operand-forms}$)
    10. (multiple-value-apply $\metavar{operator-form}$ $\metavar{operand-forms}$)
      11. @@ -203,15 +205,18 @@
    11. $\metavar{body}$ matches any sequence of zero or more objects
    12. $\metavar{variable}$ matches any variable
    13. $\metavar{value-form}$ matches any object
      14. -
    14. $\metavar{operator-form}$ matches any object
      15. -
    15. $\metavar{operand-forms}$ matches any sequence of zero or more objects
      16. +
    16. $\metavar{function-form}$ matches any object
      17. +
    17. $\metavar{list-form}$ matches any object
      18. +
    18. $\metavar{try-form}$ matches any object
    19. $\metavar{macro-operator}$ matches any variable naming a macro according to the lookup rule used by fref
    20. $\metavar{macro-operands}$ matches any sequence of zero or more objects
      21. +
    21. $\metavar{operator-form}$ matches any object
      22. +
    22. $\metavar{operand-forms}$ matches any sequence of zero or more objects

      23. 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 sixteen patterns is called a special form and the variables quote, progn, if, _vlambda, _mlambda, _flambda, _dlambda, vref, vset!, fref, fset!, dref, dset!, 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 17 are called macro calls. Forms matching pattern 18 are called plain function calls.

      +

      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.

      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:

        @@ -244,10 +249,14 @@
        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 abnormally.
        (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$.
        +
        (_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.
        (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}$)
        -
        Variants of the plain function call described below. Those variants are described in the reference manual.
        +
        These special forms are variants of the plain function call described below. They 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 abnormally, then the evaluation of the macro call also completes abnormally. 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 abnormally, then the evaluation of the macro call also completes abnormally. 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}$)
        @@ -265,7 +274,7 @@
        Let's 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 abnormally, then the invocation of the primitive function also completes abnormally. 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 abnormally. (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$, …, $\var_n$ be the variables composing the parameter list of the lambda abstraction recorded by the closure, $\arg_1$, …, $\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 abnormally. (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.
          • @@ -310,22 +319,22 @@
        • 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 type.

        -

        The global functions used in the evaluations are listed below. For each function, a template function call and a description of the function are provided. The variable in operator position is the name of the function (i.e., the variable bound to the function in the function namespace of the global environment).

        +

        The global functions used in the evaluations are listed below. For each function, a template function call and a description of the function's behavior are provided. The variable in operator position is the name of the function (i.e., the variable bound to the function in the function namespace of the global environment).

        (car $\cons$)
        -
        The function car returns the first element of its argument, which must be of type cons.
        +
        The function car returns the first element of $\cons$, which must be of type cons.
        (cdr $\cons$)
        -
        The function cdr returns the second element of its argument, which must be of type cons.
        +
        The function cdr returns the second element of $\cons$, which must be of type cons.
        (list $\object_1\ldots\object_n$)
        -
        The function list collects its arguments, which can be of any types, into a list: when invoked on the arguments $\object_1$, …, $\object_n$, the function returns a list whose elements are $\object_1$, …, $\object_n$.
        +
        The function list collects its arguments, which can be of any types, into a list: when invoked on the arguments $\object_1,\ldots,\object_n$, the function returns a list whose elements are $\object_1,\ldots,\object_n$.
        (+ $\number_1\ldots\number_n$)
        The function + returns the sum of its arguments, which must be of type number.
        (* $\number_1\ldots\number_n$)
        The function * returns the product of its arguments, which must be of type number.
        (values $\object_1\ldots\object_n$)
        -
        The function values converts its arguments, which can be of any types, into values: when invoked on the arguments $\object_1$, …, $\object_n$, the function returns the values $\object_1$, …, $\object_n$.
        +
        The function values converts its arguments, which can be of any types, into values: when invoked on the arguments $\object_1,\ldots,\object_n$, the function returns the values $\object_1,\ldots,\object_n$.
        -

        The global macros used in the evaluations are listed below. For each macro, a template macro call and a description of the macro are provided. The variable in operator position is the name of the macro (i.e., the variable bound to the macro in the function namespace of the global environment).

        +

        The global macros used in the evaluations are listed below. For each macro, a template macro call and a description of the macro's behavior are provided. The variable in operator position is the name of the macro (i.e., the variable bound to the macro in the function namespace of the global environment).

        (vdef $\metavar{variable}$ $\metavar{value-form}$)
        The purpose of the macro vdef is to define a global variable by ensuring that the variable is bound in the value namespace of the global environment to the primary value of the value-form. The macro call evaluates to the variable.