klisp

klisp.info (198574B)

---

 This is ../klisp.info, produced by makeinfo version 4.13 from
 klisp.texi.
 
 This file documents klisp.
 
    This is edition 0.3 of the klisp Reference Manual, for klisp version
 0.3.
 
    Copyright (C) 2011-2012 Andres Navarro
 
    Permission is granted to copy and distribute this manual, in whole or
 in part, without fee.  Please note that most text of this manual is
 derived from `The Revised(-1) Report on the Kernel Programming
 Language' by John N. Shutt.  There's a clause in that reports, under
 the header "Permission to copy this report", that reads:
 
      This report is intended to belong to the programming community,
      and so permission is granted to copy it in whole or in part
      without fee.
 
 
 File: klisp.info,  Node: Top,  Next: License,  Prev: (dir),  Up: (dir)
 
    This Info file contains edition 0.3 of the klisp Reference Manual,
 corresponding to klisp version 0.3.
 
    Copyright (C) 2011-2012 Andres Navarro
 
    Permission is granted to copy and distribute this manual, in whole or
 in part, without fee.  Please note that most text of this manual is
 derived from `The Revised(-1) Report on the Kernel Programming
 Language' by John N. Shutt.  There's a clause in that reports, under
 the header "Permission to copy this report", that reads:
 
      This report is intended to belong to the programming community,
      and so permission is granted to copy it in whole or in part
      without fee.
 
 * Menu:
 
 * License::                 Conditions for copying and changing klisp.
 * Introduction::            Introduction and conventions used.
 * Interpreter::             The klisp stand-alone interpreter
 * Booleans::                Booleans module features.
 * Equivalence::             Equivalence (under & up to) mutation modules features.
 * Symbols::                 Symbols module features.
 * Control::                 Control module features.
 * Pairs and lists::         Pairs and lists and Pair mutation modules features.
 * Environments::            Environments and Environment mutation modules features.
 * Combiners::               Combiners module features.
 * Continuations::           Continuations module features.
 * Encapsulations::          Encapsulations module features.
 * Promises::                Promises module features.
 * Keyed Variables::         Keyed (dynamic & static) variables module features.
 * Numbers::                 Numbers module features.
 * Strings::                 Strings module features.
 * Characters::              Characters module features.
 * Ports::                   Ports module features.
 * Vectors::                 Vectors module features.
 * Bytevectors::             Bytevectors module features.
 * Errors::                  Errors module features.
 * Libraries::               Libraries module features.
 * System::                  System module features.
 * Alphabetical Index::      Index including concepts, functions, variables,
                               and other terms.
 
 
 File: klisp.info,  Node: License,  Next: Introduction,  Prev: Top,  Up: Top
 
    klisp is licensed under the terms of the MIT license reproduced
 below.  This means that klisp is free software and can be used for both
 academic and commercial purposes at absolutely no cost.  The two
 projects whose code klisp uses, Lua & IMath, are also distributed under
 the MIT license.
 
    * klisp Parts: Copyright (C) 2011-2012 Andres Navarro, Oto Havle.
 
    * Lua Parts: Copyright (C) 1994-2010 Lua.org, PUC-Rio.
 
    * IMath Parts: Copyright (C) 2002-2007 Michael J. Fromberger.
 
    * srfi-78: Copyright (C) 2005-2006 Sebastian Egner.
 
 MIT/X11 License
 ***************
 
 Permission is hereby granted, free of charge, to any person obtaining a
 copy of this software and associated documentation files (the
 "Software"), to deal in the Software without restriction, including
 without limitation the rights to use, copy, modify, merge, publish,
 distribute, sublicense, and/or sell copies of the Software, and to
 permit persons to whom the Software is furnished to do so, subject to
 the following conditions:
 
    The above copyright notice and this permission notice shall be
 included in all copies or substantial portions of the Software.
 
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 
 File: klisp.info,  Node: Introduction,  Next: Interpreter,  Prev: License,  Up: Top
 
 1 Introduction
 **************
 
 klisp is an open source interpreter for the Kernel Programming
 Language.  It aims at being comprehensive and robust as specified in
 the `Revised(-1) Report on the Kernel Programming Language', but that
 probably won't happen for some time.  It is written in C99 under the
 MIT license.  It draws heavily from the Lua interpreter source code &
 file structure.  It uses the IMath library for arbitrary sized integers
 and rationals.
 
    The Kernel programming language is a statically scoped and properly
 tail-recursive dialect of Lisp, descended from Scheme.  It is designed
 to be simpler and more general than Scheme, with an exceptionally
 clear, simple, and versatile semantics, only one way to form compound
 expressions, and no inessential restrictions on the power of that one
 compound form.  Imperative, functional, and message-passing programming
 styles (to name a few) may be conveniently expressed in Kernel.
 
    An important property of Kernel is that all manipulable entities in
 Kernel are first-class objects.  In particular, Kernel has no
 second-class combiners; instead, the roles of special forms and macros
 are subsumed by operatives, which are first-class, statically scoped
 combiners that act directly on their unevaluated operands.  Kernel also
 has a second type of combiners, applicatives, which act on their evalu-
 ated arguments.  Applicatives are roughly equivalent to Scheme
 procedures.  However, an applicative is nothing more than a wrapper to
 induce operand evaluation, around an underlying operative (or, in
 principle, around another applicative, though that isn’t usually done);
 applicatives themselves are mere facilitators to computation.
 
    You can read more about Kernel at
 `http://web.cs.wpi.edu/~jshutt/kernel.html'.
 
    klisp is freely available for both academic and commercial purposes.
 See LICENSE for details.  it can be downloaded at
 `https://bitbucket.org/AndresNavarro/klisp'
 
    klisp is developed by Andres Navarro, a Computer Science
 undergraduate at Buenos Aires University (UBA).  You can reach him at
 <canavarro82@gmail.com>. Significant contributions are being done by
 Oto Havle, his fork is at `https://bitbucket.org/havleoto/klisp'.
 
    This manual describes klisp version 0.3, presuming some familiarity
 with the Lisp family of languages in general, and with the Kernel
 Programming Language in particular.  There are frequent references to
 the Kernel Programming Language Report.  Unlike in the report, no
 rationale is provided for any feature, only a description of the
 implemented functionality.
 
    This is edition 0.3.
 
 * Menu:
 
 * Caveats::                Flaws and a request for help.
 * Kernel History::         Kernel is descended from Scheme.
 * Conventions::            How the manual is formatted.
 * Acknowledgements::       Contributions to this manual.
 
 
 File: klisp.info,  Node: Caveats,  Next: Kernel History,  Prev: Introduction,  Up: Introduction
 
 1.1 Caveats
 ===========
 
 This is the first draft of this manual.  It will be incomplete for some
 time.  It will also evolve, together with klisp and the Kernel
 Programming Language, both of which, right now, are in a quite fluid
 state.
 
    The main reference on Kernel is the preliminary report: `Revised(-1)
 Report on the Kernel Programming Language'.  Some sections of the
 report are still incomplete, so both klisp and this manual will use
 specifications from other languages in these sections, trying to follow
 the Kernel spirit.  These instances will be documented throughout the
 manual.
 
    Please mail comments and corrections to <canavarro82@gmail.com>.
 
 
       -Andres Navarro
 
 
 File: klisp.info,  Node: Kernel History,  Next: Conventions,  Prev: Caveats,  Up: Introduction
 
 1.2 Kernel History
 ==================
 
 The Kernel Programming Language is a work in progress.  It is being
 developed by John N. Shutt, Ph.D, who created it while studying at the
 Worcester Polytechnic Institute (I think about 2002, or so... ASK).  It
 is descended from scheme, with the idea that all objects should be
 first class values.  In particular, Kernel replaces macros with
 operatives (kinda like statically scoped fexprs and fsubrs) and has
 first class environments.  Kernel also has the notion of encapsulated
 objects which limits the ammount of information an implementation can
 share with a Kernel program (e.g. There is no way in Kernel to get the
 parents or a complete list of bindings of an environment object).
 
    The main reference on Kernel is the preliminary report: `Revised(-1)
 Report on the Kernel Programming Language'.  Some sections of the
 report are still incomplete, so both klisp and this manual will use
 specifications from other languages in these sections, trying to follow
 the Kernel spirit.  These instances will be documented throughout the
 manual.
 
    You can read all about Kernel at John's homepage at WPI
 `http://www.cs.wpi.edu/~jshutt/', including the preliminary report on
 the language and his doctoral dissertation which gives a theorethical
 frame for fexprs.  You can contact him at <jshutt@cs.wpi.edu>.
 
 
 File: klisp.info,  Node: Conventions,  Next: Acknowledgements,  Prev: Kernel History,  Up: Introduction
 
 1.3 Conventions
 ===============
 
 This section explains the notational conventions that are used in this
 manual.  You may want to skip this section and refer back to it later.
 
 * Menu:
 
 * Some Terms::               Explanation of terms we use in this manual.
 * Evaluation Notation::      The format we use for examples of evaluation.
 * Printing Notation::        The format we use for examples that print output.
 * Error Messages::           The format we use for examples of errors.
 * Format of Descriptions::   Notation for describing functions, variables, etc.
 
 
 File: klisp.info,  Node: Some Terms,  Next: Evaluation Notation,  Prev: Conventions,  Up: Conventions
 
 1.3.1 Some Terms
 ----------------
 
 Throughout this manual, the phrases "the Kernel reader" and "the Kernel
 printer" are used to refer to those routines in Lisp that convert
 textual representations of Kernel objects into actual objects, and vice
 versa.  XXX Printed Representation XXX, for more details.  You, the
 person reading this manual, are assumed to be "the programmer" or "the
 user".
 
    Examples of Kernel code appear in this font or form: `(list 1 2 3)'.
 Names that represent arguments or metasyntactic variables appear in
 this font or form: FIRST-NUMBER.
 
 
 File: klisp.info,  Node: Evaluation Notation,  Next: Printing Notation,  Prev: Some Terms,  Up: Conventions
 
 1.3.2 Evaluation Notation
 -------------------------
 
 When you evaluate a piece of Kernel code, it produces a result.  In the
 examples in this manual, this is indicated with `=>':
 
      (car (cons 1 2))
           => 1
 
 You can read this as "`(car (cons 1 2))' evaluates to 1".
 
    The semantics of a language feature are sometimes clarified, or even
 defined, in its entry by specifying that two expressions are
 equivalent.  This is notated with `=='.  For example, the semantics of
 applicative list* can be defined by following equivalences:
      (list* arg1) == arg1
      (list* arg1 . more-args) == (cons arg1 (list* . more-args))
    Notice that in these kind of examples the applicatives or operatives
 referred to are the first class values and not the symbols bound to
 them in the ground environment.  This definition would hold even if
 `cons' or `list*' were redefined in the current dynamic environment.
 
 
 File: klisp.info,  Node: Printing Notation,  Next: Error Messages,  Prev: Evaluation Notation,  Up: Conventions
 
 1.3.3 Printing Notation
 -----------------------
 
 Many of the examples in this manual print text when they are evaluated.
 In examples that print text, the printed text is indicated with `-|'.
 The value returned by evaluating the form (here `#t') follows on a
 separate line.
 
      ($sequence (write 1) (write 2) #t)
           -| 1
           -| 2
           => #t
 
 
 File: klisp.info,  Node: Error Messages,  Next: Format of Descriptions,  Prev: Printing Notation,  Up: Conventions
 
 1.3.4 Error Messages
 --------------------
 
 Some examples cause errors to be signaled.  The report doesn't specify
 what objects are passed to the error continuation, but in klisp,
 objects passed to the error continuation are encapsulated error objects
 that have at least a message and possibly some additional objects and
 context informations (such as source code location).  In the examples,
 the error message is shown on a line starting with `error-->'.
 
      (+ 23 #t)
      error--> Wrong type argument: (expected number) (#t)
 
 
 File: klisp.info,  Node: Format of Descriptions,  Prev: Error Messages,  Up: Conventions
 
 1.3.5 Format of Descriptions
 ----------------------------
 
 Applicatives, operatives, and other objects are described in this manual
 in a uniform format.  The first line of a description contains the name
 of the item followed by its operands or arguments, if any.  The
 category--operative, applicative, or whatever--appears at the beginning
 of the line.  The description follows on succeeding lines, sometimes
 with examples.
 
 * Menu:
 
 * A Sample Applicative Description::
 
 
 File: klisp.info,  Node: A Sample Applicative Description,  Prev: Format of Descriptions,  Up: Format of Descriptions
 
 1.3.5.1 A Sample Applicative Description
 ........................................
 
 In an applicative description, the name of the applicative being
 described appears first.  It is followed on the same line by an
 applicative combination that includes the name of the applicative and
 the arguments, as would appear in a program.  The names used for the
 arguments are also used in the body of the description.
 
    Here is a description of an imaginary applicative `foo':
 
  -- Applicative: foo (foo integer1 integer2 . rest)
      The applicative `foo' subtracts INTEGER1 from INTEGER2, then adds
      all the rest of the arguments to the result.
 
           (foo 1 5 3 9)
                => 16
 
      More generally,
 
           (foo W X Y...)
           ==
           (+ (- X W) Y...)
 
    Any parameter whose name contains the name of a type (e.g., INTEGER,
 INTEGER1 or CONTINUATION) is expected to be of that type.  A plural of
 a type (such as NUMBERS) often means a list of objects of that type.
 Parameters named OBJECT may be of any type.  Additionally parameters
 named K, or KN (for any value of N), should be exact, non-negative
 integers.  (XXX Types of Lisp Object XXX, for a list of Kernel object
 types.)  Parameters with other sorts of names are discussed
 specifically in the description of the combiner.  In some sections,
 features common to parameters of several combiners are described at the
 beginning.
 
    Operative descriptions have the same format, but the word
 `Applicative' is  replaced by `Operative', and `Argument' is replaced
 by `Operand'.  Also Operatives always have an environment parameter
 (that can be #ignore or a symbol).
 
 
 File: klisp.info,  Node: Acknowledgements,  Prev: Conventions,  Up: Introduction
 
 1.4 Acknowledgements
 ====================
 
 This manual was written by Andres Navarro.
 
    The structure and some text for this introductory section were
 borrowed from the Elisp Manual by the Free Sofware Foundation.  This
 manual also borrows freely from both the Kernel Report and the Scheme
 Reports.
 
 
 File: klisp.info,  Node: Interpreter,  Next: Booleans,  Prev: Introduction,  Up: Top
 
 2 Interpreter
 *************
 
 This section describes the `klisp', a Kernel Programming Language
 stand-alone interpreter.
 
 2.1 Invocation
 ==============
 
 `klisp' is invoked like this:
      klisp [options] [script]
 
 2.2 Description
 ===============
 
 `klisp' is a stand-alone klisp interpreter for the Kernel Programming
 Language.  It loads and evaluates Kernel programs in textual source
 form.  `klisp' can be used as a batch interpreter and also
 interactively.  The given `options' (*note Command Line Options::) are
 evaluated and then the klisp program in file `script' is loaded and
 evaluated.  All evaluations mentioned, including the initialization
 that is described below, take place in the same (initially) standard
 environment. All values that result from these evaluation are
 discarded, but if the `root-continuation' or `error-continuation' are
 passed a value, the evaluation of `options' is interrupted and `klisp'
 terminates.  *Note Exit Status: Interpreter Exit Status, for a
 description of the exit status in each case.
 
    The string `script' together with all arguments are available as a
 list of strings via the applicative `get-script-arguments'.  If these
 arguments contain spaces or other characters special to the shell, then
 they should be quoted (but note that the quotes will be removed by the
 shell).  The complete command line, including the name of the
 interpreter, options, the script, and its arguments are available as a
 list of strings via the applicative `get-interpreter-arguments'.
 
    At the very beginning, before even handling the command line,
 `klisp' reads and evaluates the contents of the environment variable
 `KLISP_INIT', if it is defined.  To use an init file, just define
 `KLISP_INIT' to the following form: `(load "/path/to/init-file")'.
 Notice that `klisp' expects exactly one expression in `KLISP_INIT', if
 it is defined.  So it is an error to have no expressions or more than
 one in `KLISP_INIT'.  The same is true of the argument to the `-e'
 option, as both are implemented in terms of `string-eval'.
 
    In interactive mode, `klisp' prompts the user, reads expressions
 from the standard input, and evaluates them as they are read. The
 default prompt is "klisp> ".
 
 2.3 Options
 ===========
 
 Options start with `-' and are described below. You can use `--' to
 signal the end of options. If no arguments are given, then `-v'  `-i'
 is assumed when the standard input is a terminal; otherwise, `-' is
 assumed.  If no SCRIPT, or option `-e' or `-l' is given, `-i' is
 assumed.
 
 `-'
      load and execute the standard input as a file, that is, not
      interactively, even when the standard input is a terminal.  .TP
 
 `-e EXPR'
      evaluate expression EXPR.  You need to quote EXPR if it contains
      spaces, quotes, or other characters special to the shell.
 
 `-i'
      enter interactive mode after SCRIPT is executed.
 
 `-l NAME'
      evaluate `(load "name")' before SCRIPT is executed.  Typically
      used to do environment initialization.
 
 `-r NAME'
      evaluate `(require "name")' before SCRIPT is executed. Typically
      used to load libraries.
 
 `-v'
      show version and copyright information.
 
 
 2.4 Exit Status
 ===============
 
 If the SCRIPT or `stdin' reach EOF or if there is no SCRIPT,
 `EXIT_SUCCESS' is returned.  If the ERROR-CONTINUATION is passed an
 object during init, arguments or script evaluation `EXIT_FAILURE' is
 returned.  If the ROOT-CONTINUATION is passed an object, `klisp' tries
 to convert the value passed to the ROOT-CONTINUATION to an exit status
 as follows:
 
 `integer'
      If the value is an integer it is used as exit status.
 
 `boolean'
      If the value is a boolean then `EXIT_SUCCESS' is returned for `#t'
      and `EXIT_FAILURE' for `#f'.
 
 `inert'
      If the value is inert, then `EXIT_SUCCESS' is returned.
 
 `else'
      In any other case `EXIT_FAILURE' is returned.
 
 2.5 Environment Variables
 =========================
 
 The following environment variables affect the behaviour of `klisp'
 
 `KLISP_INIT'
      A Kernel expression to be evaluated before any arguments to the
      interpreter.  To use an init file, just define KLISP_INIT to the
      following form `(load "/path/to/init-file")'
 
 `KLISP_PATH'
      A semicolon separated list of templates for controlling the search
      of required files.  Each template can use the char `?' to be
      replaced by the required name at run-time.
 
 
 
 File: klisp.info,  Node: Booleans,  Next: Equivalence,  Prev: Interpreter,  Up: Top
 
 3 Booleans
 **********
 
 The boolean data type consists of two values, which are called true and
 false, and have respectively external representations `#t' and `#f'.
 There are no possible mutations of either of these two values, and the
 boolean type is encapsulated.
 
  -- Applicative: boolean? (boolean? . objects)
      The primitive type predicate for type boolean.  `boolean?' returns
      true iff all the objects in `objects' are of type boolean.
 
  -- Applicative: not? (not? boolean)
      Applicative `not?' is a predicate that returns the logical
      negation of its argument.
 
  -- Applicative: and? (and? . booleans)
      Applicative `and?' is a predicate that returns true unless one or
      more of its arguments are false.
 
  -- Applicative: or? (or? . booleans)
      Applicative `or?' is a predicate that returns false unless one or
      more of its arguments are true.
 
  -- Operative: $and? ($and? . <list>)
      The `$and?' operative performs a "short-circuit and" of its
      operands.  It evaluates them from left to right, until either an
      operand evaluates to false, or the end of the list is reached.  If
      the end of the list is reached (which is immediate if `<list>' is
      `nil'), the operative returns true.  If an operand evaluates to
      false, no further operand evaluations are performed, and the
      operative returns false.  If `<list>' is acyclic, and the last
      operand is evaluated, it is evaluated in a special type of tail
      context that checks that the passed value is a boolean.  If
      `<list>' is cyclic, an unbounded number of operand evaluations may
      be performed.  If any of the operands evaluates to a non-boolean
      value, an error is signaled (even if it's the last one).
 
  -- Operative: $or? ($or? . <list>)
      The `$or?' operative performs a "short-circuit or" of its
      operands.  It evaluates them from left to right, until either an
      operand evaluates to true, or the end of the list is reached.  If
      the end of the list is reached (which is immediate if `<list>' is
      `nil'), the operative returns false.  If an operand evaluates to
      true, no further operand evaluations are performed, and the
      operative returns true.  If `<list>' is acyclic, and the last
      operand is evaluated, it is evaluated in a special type of tail
      context that checks that the passed value is a boolean.  If
      `<list>' is cyclic, an unbounded number of operand evaluations may
      be performed.  If any of the operands evaluates to a non-boolean
      value, an error is signaled (even if it's the last one).
 
 
 File: klisp.info,  Node: Equivalence,  Next: Symbols,  Prev: Booleans,  Up: Top
 
 4 Equivalence
 *************
 
 Kernel has two general-purpose equivalence predicates (whereas R5RS
 Scheme has three).  The two Kernel predicates correspond to the
 abstract notions of equivalence up to mutation (`equal') and
 equivalence in the presence of mutation (`eq?').
 
  -- Applicative: eq? (eq? . objects)
      Predicate `eq?' returns true iff all of `objects' are effectively
      the same object, even in the presence of mutation.
 
  -- Applicative: equal? (equal? . objects)
      Predicate `equal?' returns true iff all of `objects' "look" the
      same as long as nothing is mutated.  This is a weaker predicate
      than `eq?'; that is, `equal?' must return true whenever `eq?'
      would return true.
 
 
 File: klisp.info,  Node: Symbols,  Next: Control,  Prev: Equivalence,  Up: Top
 
 5 Symbols
 *********
 
 Two symbols are eq? iff they have the same external representation.
 Symbols are immutable, and the symbol type is encapsulated.  The
 external representations of symbols are usually identifiers.  However,
 symbols with other external representations may be created.  Symbols
 whose external representation is enclosed within "|" (that is "| ...
 |") can contain any character supported by klisp, "|" and "\" can be
 included by escaping them with a leading "\" (that is "\|" and "\\").
 Characters in symbols can also be specified with a unicode hex escape
 by using the syntax "\x<hex codepoint>;".  This works whether using the
 "| ... |" syntax or not.
 
  -- Applicative: symbol? (symbol? . objects)
      The primitive type predicate for type symbol.  `symbol?' returns
      true iff all the objects in `objects' are of type symbol.
 
  -- Applicative: symbol->string (symbol->string symbol)
      Applicative `symbol->string' returns the name of `symbol' as a
      string.  The string returned is immutable.
 
  -- Applicative: string->symbol (string->symbol string)
      Applicative `string->symbol' returns the symbol with name
      `string'.  The symbol is always interned, which means, that it is
      always the case that:
           (eq? <symbol> (string->symbol (symbol->string <symbol>)))
                => #t
        `string->symbol' can create symbols whose external
      representation aren't identifiers.  klisp uses the r7rs external
      representation for such symbols and so all symbols can be written
      and read back.
 
 
 File: klisp.info,  Node: Control,  Next: Pairs and lists,  Prev: Symbols,  Up: Top
 
 6 Control
 *********
 
 The inert data type is provided for use with control combiners.  It
 consists of a single immutable value, having external representation
 `#inert'.  The inert type is encapsulated.
 
  -- Applicative: inert? (inert? . objects)
      The primitive type predicate for type inert. `inert?' returns true
      iff all the objects in `objects' are of type inert.
 
  -- Operative: $if ($if <test> <consequent> <alternative>)
      The `$if' operative first evaluates `<test>' in the dynamic
      environment.  If the result is not of type boolean, an error is
      signaled.  If the result is true, `<consequent>' is then evaluated
      in the dynamic environment as a tail context.  Otherwise,
      `<alternative>' is evaluated in the dynamic environment as a tail
      context.
 
  -- Operative: $sequence ($sequence . <objects>)
      The `$sequence' operative evaluates the elements of the list
      `<objects>' in the dynamic environment, one at a time from left to
      right.  If `<objects>' is a cyclic list, element evaluation
      continues indefinitely, with elements in the cycle being evaluated
      repeatedly.  If `<objects>' is a nonempty finite list, its last
      element is evaluated as a tail context.  If `<objects>' is the
      empty list, the result is inert.
 
  -- Operative: $cond ($cond . <clauses>)
      `<clauses>' should be a list of clause expressions, each of the
      form `(<test> . <body>)', where body is a list of expressions.
 
      The following equivalences define the behaviour of the `$cond'
      operative:
           ($cond) == #inert
           ($cond (<test> . <body>) . <clauses>) ==
             ($if <test> ($sequence . <body>) ($cond . <clauses>))
 
  -- Applicative: for-each (for-each applicative . lists)
      `lists' must be a nonempty list of lists; if there are two or
      more, they should all be the same length. If lists is empty, or if
      all of its elements are not lists of the same length, an error is
      signaled.
 
      `for-each' behaves identically to `map', except that instead of
      accumulating and returning a list of the results of the
      element-wise applications, the results of the applications are
      discarded and the result returned by `for-each' is inert.
 
  -- Applicative: string-for-each (string-for-each applicative . strings)
  -- Applicative: vector-for-each (vector-for-each applicative. vectors)
  -- Applicative: bytevector-for-each (bytevector-for-each applicative .
           bytevectors)
      `strings', `vectors', or `bytevectors' should be non-empty lists
      of the corresponding type and all elements should be of the same
      length.
 
      These applicatives behave as `for-each' except that the list of
      elements passed to `applicative' are the n-th chars, objects, or
      uint8s of the strings, vectors or bytevectors passed as arguments.
 
      SOURCE NOTE: These are taken from r7rs.
 
  -- Operative: $when ($when <test> . <body>)
  -- Operative: $unless ($unless <test> . <body>)
      `body' should be a list of expressions.
 
      These operatives behave as one-armed `$if's with an implicit
      `$sequence', except that they always discard the last value and
      the result returned is inert.
 
      So both `$when', and `$unless' evaluate `<test>' in the dynamic
      environment.  If the result is non boolean an error is signaled.
      In `$when' if the result is false and in `$unless' if the result
      is true, the expressions in `<body>' are not evaluated and an
      inert value is returned.  Otherwise, the expressions in `<body>'
      are evaluated sequentially in the dynamic environment.  If
      `<body>' is a non cyclic list, the last expression in `<body>' is
      evaluated in a special type of tail context, that, upon receiving
      a value discards it and returns an inert value instead.  If
      `<body>' is a cyclic list, element evaluation continues
      indefinitely, with elements in the cycle being evaluated
      repeatedly.  SOURCE NOTE: These are taken from r7rs.
 
 
 File: klisp.info,  Node: Pairs and lists,  Next: Environments,  Prev: Control,  Up: Top
 
 7 Pairs and lists
 *****************
 
 A pair is an object that refers to two other objects, called its car
 and cdr.  The Kernel data type pair is encapsulated.
 
    The null data type consists of a single immutable value, called nil
 or the empty list and having external representation `()', with or
 without whitespace between the parentheses. It is immutable, and the
 null type is encapsulated.
 
    If `a' and `d' are external representations of respectively the car
 and cdr of a pair `p', then `(a . d)' is an external representation of
 `p'. If the cdr of `p' is nil, then `(a)' is also an external
 representation of `p'. If the cdr of `p' is a pair `p2', and `(r)' is
 an external representation of `p2', then `(a r)' is an external
 representation of `p'.    When a pair is output (as by write), an
 external representation with the fewest parentheses is used; in the
 case of a finite list, only one set of parentheses is required beyond
 those used in representing the elements of the list. For example, an
 object with external representation `(1 . (2 . (3 . ())))' would be
 output using, modulo whitespace, external representation `(1 2 3)'.
 
  -- Applicative: pair? (pair? . objects)
      The primitive type predicate for type pair.  `pair?' returns true
      iff all the objects in `objects' are of type pair.
 
  -- Applicative: null? (null? . objects)
      The primitive type predicate for type null.  `null?' returns true
      iff all the objects in `objects' are of type null.
 
  -- Applicative: immutable-pair? (immutable-pair? objects)
  -- Applicative: mutable-pair? (mutable-pair? objects)
      The primitive type predicates for types immutable pair and mutable
      pair.  These return true iff all the objects in `objects' are of
      type immutable pair or mutable pair respectively.
 
      SOURCE NOTE: these aren't provided in the Kernel report, but added
      for convenience.  These can be implemented in standard kernel by
      using guards.
 
  -- Applicative: cons (cons object1 object2)
      A new mutable pair object is constructed and returned, whose car
      and cdr referents are respectively `object1' and `object2'.  No
      two objects returned by different calls to cons are `eq?' to each
      other.
 
  -- Applicative: set-car! (set-car! pair object)
  -- Applicative: set-cdr! (set-cdr! pair object)
      `pair' should be a mutable pair.
 
      These applicatives set the referent of, respectively, the car
      reference or the cdr reference of `pair' to `object'.  The result
      of the expression is inert.
 
  -- Applicative: copy-es-immutable! (copy-es-immutable object)
      The short description of this applicative is that it returns an
      object `equal?' to `object' with an immutable evaluation
      structure. The "-es-" in the name is short for "evaluation
      structure".
 
      The evaluation structure of an object `o' is defined to be the set
      of all pairs that can be reached by following chains of references
      from `o' without ever passing through a non-pair object. The
      evaluation structure of a non-pair object is empty.
 
      If `object' is not a pair, the applicative returns `object'.
      Otherwise (if `object' is a pair), the applicative returns an
      immutable pair whose car and cdr would be suitable results for
      `(copy-es-immutable (car object))' and `(copy-es-immutable (cdr
      object))', respectively.  Further, the evaluation structure of the
      returned value is isomorphic to that of `object' at the time of
      copying, with corresponding non-pair referents being `eq?'.
 
      NOTE: In Kernel it's undefined whether immutable pairs are copied
      or left "as is" in the result.  klisp doesn't copy immutable
      pairs, but that behaviour should not be depended upon.
 
  -- Applicative: list (list . objects)
      The `list' applicative returns `objects'.
 
      The underlying operative of `list' returns its undifferentiated
      operand tree, regardless of whether that tree is or is not a list.
 
  -- Applicative: list* (list* . objects)
      `objects' should be a finite nonempty list of arguments.
 
      The following equivalences hold:
           (list* arg1) == arg1
           (list* arg1 arg2 . args) == (cons arg1 (list* arg2 . args))
 
  -- Applicative: car (car pair)
  -- Applicative: cdr (cdr pair)
      These applicatives return, respectively, the car and cdr of `pair'.
 
  -- Applicative: caar (caar pair)
  -- Applicative: cadr (cadr pair)
  -- Applicative: cdar (cdar pair)
  -- Applicative: cddr (cddr pair)
  -- Applicative: caaar (caaar pair)
  -- Applicative: caadr (caadr pair)
  -- Applicative: cadar (cadar pair)
  -- Applicative: caddr (caddr pair)
  -- Applicative: cdaar (cdaar pair)
  -- Applicative: cdadr (cdadr pair)
  -- Applicative: cddar (cddar pair)
  -- Applicative: cdddr (cdddr pair)
  -- Applicative: caaaar (caaaar pair)
  -- Applicative: caaadr (caaadr pair)
  -- Applicative: caadar (caadar pair)
  -- Applicative: caaddr (caaddr pair)
  -- Applicative: cadaar (cadaar pair)
  -- Applicative: cadadr (cadadr pair)
  -- Applicative: caddar (caddar pair)
  -- Applicative: cadddr (cadddr pair)
  -- Applicative: cdaaar (cdaaar pair)
  -- Applicative: cdaadr (cdaadr pair)
  -- Applicative: cdadar (cdadar pair)
  -- Applicative: cdaddr (cdaddr pair)
  -- Applicative: cddaar (cddaar pair)
  -- Applicative: cddadr (cddadr pair)
  -- Applicative: cdddar (cdddar pair)
  -- Applicative: cddddr (cddddr pair)
      These applicatives are compositions of `car' and `cdr', with the
      "a’s" and "d’s" in the same order as they would appear if all the
      individual "car’s" and "cdr’s" were written out in prefix order.
      Arbitrary compositions up to four deep are provided. There are
      twenty-eight of these applicatives in all.
 
  -- Applicative: make-list (make-list length [fill])
      `length' shoulde be an exact non-negative integer.
 
      Applicative `make-list' creates a new mutable acyclic list of
      length `length', with all pairs having `fill' in their cars.  If
      no value is provided for `fill', `#inert' is used.
 
      SOURCE NOTE: this is taken from r7rs.
 
  -- Applicative: list-copy (list-copy list)
      Applicative `list-copy' creates a new mutable copy of `list'.
      That is, the returned list has the same list metrics as `list' and
      the cars in the returned list are initially `eq?' to the
      corresponding cars in `list'.
 
      SOURCE NOTE: this is taken from r7rs.
 
  -- Applicative: reverse (reverse list)
      `list' should be an acyclic list.
 
      Applicative `reverse' makes a mutable copy of list but with the
      reverse order.  That is, the returned list has the same number of
      pairs as `list' and the cars in the returned list are initially
      `eq?' to the corresponding cars in `list' but starting from the
      end and going backwards.
 
      SOURCE NOTE: this is taken from r7rs.
 
  -- Applicative: get-list-metrics (get-list-metrics object)
      By definition, an improper list is a data structure whose objects
      are its start together with all objects reachable from the start by
      following the cdr references of pairs, and whose internal
      references are just the cdr references of its pairs.  Every
      object, of whatever type, is the start of an improper list.  If
      the start is not a pair, the improper list consists of just that
      object.  The acyclic prefix length of an improper list `L' is the
      number of pairs of `L' that a naive traversal of `L' would visit
      only once. The cycle length of `L' is the number of pairs of `L'
      that a naive traversal would visit repeatedly. Two improper lists
      are structurally isomorphic iff they have the same acyclic prefix
      length and cycle length and, if they are terminated by non-pair
      objects rather than by cycles, the non-pair objects have the same
      type.  Applicative `get-list-metrics' constructs and returns a
      list of exact integers of the form `(p n a c)', where `p', `n',
      `a', and `c' are, respectively, the number of pairs in, the number
      of nil objects in, the acyclic prefix length of, and the cycle
      length of, the improper list starting with `object'. `n' is either
      `0' or `1', `a + c = p', and `n' and `c' cannot both be non-zero.
      If `c = 0', the improper list is acyclic; if `n = 1', the improper
      list is a finite list; if `n = c = 0', the improper list is not a
      list; if `a = c = 0', `object' is not a pair.
 
  -- Applicative: list-tail (list-tail object k)
      `object' must be the start of an improper list containing at least
      `k' pairs.
 
      The `list-tail' applicative follows `k' cdr references starting
      from `object'.
 
      The following equivalences hold:
           (list-tail object 0) == object
           (list-tail object (+ k 1)) == (list-tail (cdr object) k)
 
  -- Applicative: encycle! (encycle! object k1 k2)
      The improper list starting at `object' must contain at least `k1 +
      k2' pairs.
 
      If `k2 = 0', the applicative does nothing. If `k2 > 0', the
      applicative mutates the improper list starting at `object' to have
      acyclic prefix length `k1' and cycle length `k2', by setting the
      cdr of the `(k1+k2)'th pair in the list to refer to the `(k1 +
      1)'th pair in the list.  The result returned by `encycle!' is
      inert.
 
  -- Applicative: map (map applicative . lists)
      `lists' must be a nonempty list of lists; if there are two or
      more, they must all have the same length.
 
      The map applicative applies `applicative' element-wise to the
      elements of the lists in lists (i.e., applies it to a list of the
      first elements of the lists, to a list of the second elements of
      the lists, etc.), using the dynamic environment from which map was
      called, and returns a list of the results, in order. The
      applications may be performed in any order, as long as their
      results occur in the resultant list in the order of their
      arguments in the original lists.  If `lists' is a cyclic list,
      each argument list to which `applicative' is applied is
      structurally isomorphic to `lists'.  If any of the elements of
      `lists' is a cyclic list, they all must be, or they wouldn’t all
      have the same length.  Let `a1...an' be their acyclic prefix
      lengths, and `c1...cn' be their cycle lengths.  The acyclic prefix
      length `a' of the resultant list will be the maximum of the `ak',
      while the cycle length `c' of the resultant list will be the least
      common multiple of the `ck'.  In the construction of the result,
      `applicative' is called exactly `a + c' times.
 
  -- Applicative: length (length object)
      Applicative `length' returns the (exact) improper-list length of
      `object'.  That is, it returns the number of consecutive cdr
      references that can be followed starting from `object'.  If
      `object' is not a pair, it returns zero; if `object' is a cyclic
      list, it returns positive infinity.
 
  -- Applicative: list-ref (list-ref object k)
      The `list-ref' applicative returns the `car' of the object
      obtained by following `k' cdr references starting from `object'.
 
      NOTE: In the current report, object is required to be a list. In
      klisp, for now, we prefer the behaviour presented here, as it is
      more in line with the applicative `list-tail'.  That is, we define
      `list-ref' by the following equivalence:
           (list-ref object k) == (car (list-tail object k))
 
  -- Applicative: append (append . lists)
      Here, all the elements of `lists' except the last element (if any)
      must be acyclic lists.  The `append' applicative returns a freshly
      allocated list of the elements of all the specified `lists', in
      order, except that if there is a last specified element of
      `lists', it is not copied, but is simply referenced by the cdr of
      the preceding pair (if any) in the resultant list.  If `lists' is
      cyclic, the cycle of the result list consists of just the elements
      of the lists specified in the cycle in `lists'. In this case, the
      acyclic prefix length of the result is the sum of the lengths of
      the lists specified in the acyclic prefix of `lists', and the
      cycle length of the result is the sum of the lengths of the lists
      specified in the cycle of `lists'.
 
      The following equivalences hold:
           (append) == ()
           (append h) == h
           (append () h . t) == (append h . t)
           (append (cons a b) h . t) == (cons a (append b h . t))
 
  -- Applicative: list-neighbors (list-neighbors list)
      The `list-neighbors' applicative constructs and returns a list of
      all the consecutive sublists of `list' of length 2, in order.  If
      `list' is nil, the result is nil.  If `list' is non-nil, the
      length of the result is one less than the length of `list'. If
      `list' is cyclic, the result is structurally isomorphic to it
      (i.e., has the same acyclic prefix length and cycle length).
 
      For example:
           (list-neighbors (list 1 2 3 4)) => ((1 2) (2 3) (3 4))
 
  -- Applicative: filter (filter applicative list)
      Applicative `filter' passes each of the elements of `list' as an
      argument to `applicative', one at a time in no particular order,
      using a fresh empty environment for each call.  The result of each
      call to `applicative' must be boolean, otherwise an error is
      signaled.  `filter' constructs and returns a list of all elements
      of `list' on which `applicative' returned true, in the same order
      as in `list'.  `applicative' is called exactly as many times as
      there are pairs in `list'.  The resultant list has a cycle
      containing exactly those elements accepted by `applicative' that
      were in the cycle of `list'; if there were no such elements, the
      result is acyclic.
 
  -- Applicative: assoc (assoc object pairs [eq-pred?])
      Applicative `assoc' returns the first element of `pairs' whose car
      is `eq-pred?' to `object'.  If there is no such element in
      `pairs', nil is returned.  If `eq-pred?' is not supplied it
      defaults to `equal?'.  SOURCE NOTE: the optional eq-pred? argument
      is from r7rs.
 
  -- Applicative: member? (member? object list [eq-pred?])
      Applicative `member?' is a predicate that returns true iff some
      element of `list' is `eq-pred?' to `object'.  If `eq-pred?' is not
      supplied, it defaults to `equal?'.  SOURCE NOTE: the optional
      eq-pred? argument is from r7rs.
 
  -- Applicative: finite-list? (finite-list? . objects)
      This is the type predicate for type finite-list.  `finite-list?'
      returns true iff all the objects in `objects' are acyclic lists.
 
  -- Applicative: countable-list? (countable-list? . objects)
      This is the type predicate for type list.  `countable-list?'
      returns true iff all the objects in `objects' are lists.
 
  -- Applicative: reduce (reduce list binary identity [precycle incycle
           postcycle])
      `binary' should be an applicative. If the short form is used,
      `list' should be an acyclic. If the long form is used, `precycle',
      `incycle', and `postcycle' should be applicatives.
 
      If `list' is empty, applicative `reduce' returns `identity'.  If
      `list' is nonempty but acyclic, applicative `reduce' uses binary
      operation `binary' to merge all the elements of `list' into a
      single object, using any associative grouping of the elements.
      That is, the sequence of objects initially found in `list' is
      repeatedly decremented in length by applying `binary' to a list of
      any two consecutive objects, replacing those two objects with the
      result at the point in the sequence where they occurred; and when
      the sequence contains only one object, that object is returned.
      If `list' is cyclic, the long form must be used.  The elements of
      the cycle are passed, one at a time (but just once for each
      position in the cycle), as arguments to unary applicative
      `precycle'; the finite, cyclic sequence of results from `precycle'
      is reduced using binary applicative `incycle'; and the result from
      reducing the cycle is passed as an argument to unary applicative
      `postcycle'. Binary operation `binary' is used to reduce the
      sequence consisting of the elements of the acyclic prefix of
      `list' followed by the result returned by `postcycle'. The only
      constraint on the order of calls to the applicatives is that each
      call must be made before its result is needed (thus, parts of the
      reduction of the acyclic prefix may occur before the contribution
      from the cycle has been completed).
 
      Each call to `binary', `precycle', `incycle', or `postcycle' uses
      the dynamic environment of the call to `reduce'.
 
      If `list' is acyclic with length `n >= 1', `binary' is called `n -
      1' times.  If `list' is cyclic with acyclic prefix length `a' and
      cycle length `c', `binary' is called `a' times; `precycle', `c'
      times; `incycle', `c - 1' times; and `postcycle', once.
 
  -- Applicative: append! (append! . lists)
      `lists' must be a nonempty list; its first element must be an
      acyclic nonempty list, and all of its elements except the last
      element (if any) must be acyclic lists.
 
      The `append!' applicative sets the cdr of the last pair in each
      nonempty list argument to refer to the next non-nil argument,
      except that if there is a last non-nil argument, it isn’t mutated.
      It is an error for any two of the list arguments to have the same
      last pair.  The result returned by this applicative is inert.
 
      The following equivalences hold:
           (append! v) == #inert
           (append! u v . w) == ($sequence (append! u v) (append! u . w))
 
  -- Applicative: copy-es (copy-es object)
      Briefly, applicative `copy-es' returns an object initially
      `equal?' to `object' with a freshly constructed evaluation
      structure made up of mutable pairs.  If `object' is not a pair,
      the applicative returns `object'.  If `object' is a pair, the
      applicative returns a freshly constructed pair whose car and cdr
      would be suitable results for `(copy-es (car object))' and
      `(copy-es (cdr object))', respectively.  Further, the evaluation
      structure of the returned value is structurally isomorphic to that
      of `object' at the time of copying, with corresponding non-pair
      referents being `eq?'.
 
  -- Applicative: assq (assq object pairs)
      Applicative `assq' returns the first element of `pairs' whose car
      is `eq?' to `object'.  If there is no such element in `pairs', nil
      is returned.
 
  -- Applicative: memq? (memq? object list)
      Applicative `memq?' is a predicate that returns true iff some
      element of `list' is `eq?' to `object'.
 
 
 File: klisp.info,  Node: Environments,  Next: Combiners,  Prev: Pairs and lists,  Up: Top
 
 8 Environments
 **************
 
 An environment consists of a set of bindings, and a list of zero or
 more references to other environments called its parents.  Changing the
 set of bindings of an environment, or setting the referent of the
 reference in a binding, is a mutation of the environment. (Changing the
 parent list, or a referent in the list, would be a mutation of the
 environment too, but there is no facility provided to do it.) The
 Kernel data type environment is encapsulated.  Among other things,
 there is no facility provided for enumerating all the variables
 exhibited by an environment (which is not required, after all, to be a
 finite set), and no facility for identifying the parents of an
 environment.  Two environments are `equal?' iff they are `eq?'.
 
    An auxiliary data type used by combiners that perform binding is
 ignore. The ignore type consists of a single immutable value, having
 external representation `#ignore'.  The ignore type is encapsulated.
 
  -- Applicative: environment? (environment? . objects)
      The primitive type predicate for type environment.  `environment?'
      returns true iff all the objects in `objects' are of type
      environment.
 
  -- Applicative: ignore? (ignore? . objects)
      The primitive type predicate for type ignore.  `ignore?' returns
      true iff all the objects in `objects' are of type ignore.
 
  -- Applicative: eval (eval expression environment)
      The `eval' applicative evaluates `expression' in `environment', as
      a tail context, returning the resulting value.
 
  -- Applicative: make-environment (make-environment . environments)
      The applicative constructs and returns a new environment, with
      initially no local bindings, and parent environments the
      environments listed in `environments'. The constructed environment
      internally stores its list of parents independent of the
      first-class list `environments', so that subsequent mutation of
      `environments' will not change the parentage of the constructed
      environment. If the provided list `environments' is cyclic, the
      constructed environment will still check each of its parents at
      most once, and signal an error if no binding is found locally or
      in any of the parents.  No two objects returned by different calls
      to `make-environment' are `eq?' to each other.
 
  -- Operative: $define! ($define! <definiend> <expression>)
      `<definiend>' should be a formal parameter tree, as described
      below; otherwise, an error is signaled.
 
      The `$define!' operative evaluates `<expression>' in the dynamic
      environment and matches `<definiend>' to the result in the dynamic
      environment, binding each symbol in definiend in the dynamic
      environment to the corresponding part of the result; the matching
      process will be further described below. The ancestors of the
      dynamic environment, if any, are unaffected by the matching
      process, as are all bindings, local to the dynamic environment, of
      symbols not in `<definiend>'.  The result returned by `$define!' is
      inert.
 
      A formal parameter tree has the following context-free structure:
           ptree:: symbol | #ignore | () | (ptree . ptree)
 
      That is, a formal parameter tree is either a symbol, or ignore, or
      nil, or a pair whose car and cdr referents are formal parameter
      trees.  A formal parameter tree must also be acyclic, and no one
      symbol can occur more than once in it.  It is not an error for a
      pair in the tree to be reachable from the root by more than one
      path, as long as there is no cycle; but if any particular symbol
      were reachable from the root by more than one path, that would
      count as occurring more than once.  Thus, if a pair is reachable
      by more than one path, there must be no symbols reachable from it.
 
      Matching of a formal parameter tree `t' to an object `o' in an
      environment `e' proceeds recursively as follows.  If the matching
      process fails, an error is signaled.
         * If `t' is a symbol, then `t' is bound to `o' in `e'.
 
         * If `t' is `#ignore', no action is taken.
 
         * If `t' is nil, then `o' must be nil (else matching fails).
 
         * If `t' is a pair, then `o' must be a pair (else matching
           fails). The car of `t' is matched to the car of `o' in `e',
           and the cdr of `t' is matched to the cdr of `o' in `e'.
 
  -- Operative: $let ($let <bindings> . <objects>)
      `<bindings>' should be a finite list of
      formal-parameter-tree/expression pairings, each of the form
      `(formals expression)', where each `formals' is a formal
      parameter, and no symbol occurs in more than one of the `formals'.
 
      The following equivalence holds:
 
           ($let ((form1 exp1) ... (formn expn)) . objects) ==
             (($lambda (form1 ... formn) . objects) exp1 ... expn)
 
      Thus, the `expk' are first evaluated in the dynamic environment,
      in any order; then a child environment `e' of the dynamic
      environment is created, with the `formk' matched in `e' to the
      results of the evaluations of the `expk'; and finally the
      subexpressions of `objects' are evaluated in `e' from left to
      right, with the last (if any) evaluated as a tail context, or if
      `objects' is empty the result is inert.
 
  -- Operative: $binds? ($binds? <exp> . <symbols>)
      Operative `$binds' evaluates `<exp>' in the dynamic environment;
      call the result `env'.  `env' must be an environment.  The
      operative is a predicate that returns true iff all its later
      operands, `<symbols>', are visibly bound in `env'.
 
  -- Applicative: get-current-environment (get-current-environment)
      The `get-current-environment' applicative returns the dynamic
      environment in which it is called.
 
  -- Applicative: make-kernel-standard-environment
           (make-kernel-standard-environment)
      The `make-kernel-standard-environment' applicative returns a
      standard environment; that is, a child of the ground environment
      with no local bindings.
 
  -- Operative: $let* ($let* <bindings> . <body>)
      `<bindings>' should be a finite list of
      formal-parameter-tree/expression pairings, each of the form
      `(formals expression)', where each `formals' is a formal parameter
      tree; `<body>' should be a list of expressions.
 
      The following equivalences hold:
 
           ($let* () . body) == ($let () . body)
 
           ($let* ((form exp) . bindings) . body) ==
             ($let ((form exp)) ($let* bindings . body))
 
  -- Operative: $letrec ($letrec <bindings> . <body>)
      `<bindings>' and `<body>' should be as described for `$let'.
 
      The following equivalence holds:
           ($letrec ((form1 exp1) ... (formn expn)) . body) ==
             ($let () ($define! (form1 ... formn) (list exp1 ... expn)) . body)
 
  -- Operative: $letrec* ($letrec* <bindings> . <body>)
      `<bindings>' and `<body>' should be as described for `$let*'.
 
      The following equivalences hold:
           ($letrec* () . body) == ($letrec () . body)
 
           ($letrec* ((form exp) . bindings) . body) ==
             ($letrec ((form exp)) ($letrec* bindings . body))
 
  -- Operative: $let-redirect ($let-redirect <exp> <bindings> . <body>)
      `<bindings>' and `<body>' should be as described for `$let'.
 
      The following equivalence holds:
 
           ($let-redirect exp ((form1 exp1) ... (formn . body) expn)) ==
             ((eval (list $lambda (form1 ... formn) body) exp) expn ... expn)
 
  -- Operative: $let-safe ($let-safe <bindings> . <body>)
      `<bindings>' and `<body>' should be as described for `$let'.
 
      The following equivalence holds:
 
           ($let-safe bindings . body) ==
             ($let-redirect (make-kernel-standard-environment) bindings . body)
 
  -- Operative: $remote-eval ($remote-eval <exp1> <exp2>)
      Operative `$remote-eval' evaluates `<exp2>' in the dynamic
      environment, then evaluates `<exp1>' as a tail context in the
      environment that must result from the first evaluation.
 
  -- Operative: $bindings->environment ($bindings->environment .
           <bindings>)
      `<bindings>' should be as described for `$let'.
 
      The following equivalence holds:
 
           ($bindings->environment . bindings) ==
             ($let-redirect (make-environment) bindings (get-current-environment))
 
  -- Applicative: eval-string (eval-string string environment)
      `string' should be the external representation of a single object.
      If none or more than one external representation is found in
      `string' then an error is signaled.
 
      Applicative `eval-string' reads an external representation from
      string, and evaluates the resulting object in `environment', as a
      tail context, returning the resulting value.
 
  -- Operative: $set! ($set! <exp1> <formals> <exp2>)
      `<formals>' should be as described for the `$define!' operative.
      The `$set!' operative evaluates `<exp1>' and `<exp2>' in the
      dynamic environment; call the results `env' and `obj'.  If `env'
      is not an environment, an error is signaled.  Then the operative
      matches `<formals>' to `obj' in environment `env'.  Thus, the
      symbols of `<formals>' are bound in `env' to the corresponding
      parts of `obj'.  The result returned by `$set!' is inert.
 
  -- Operative: $provide! ($provide! <symbols> . <body>)
      `<symbols>' must be a finite list of symbols, containing no
      duplicates.  `<body>' must be a finite list.
 
      The `$provide!' operative constructs a child `e' of the dynamic
      environment `d'; evaluates the elements of `<body>' in `e', from
      left to right, discarding all of the results; and exports all of
      the bindings of symbols in `<symbols>' from `e' to `d', i.e.,
      binds each symbol in `d' to the result of looking it up in `e'.
      The result returned by `$provide!'  is inert.
 
      The following equivalence holds:
 
           ($provide!  symbols . body) ==
           ($define!  symbols ($let () ($sequence . body) (list . symbols)))
 
  -- Operative: $import! ($import! <exp> . <symbols>)
      `<symbols>' must be a list of symbols.
 
      The `$import!' operative evaluates `<exp>' in the dynamic
      environment; call the result `env'. `env' must be an environment.
      Each distinct symbol `s' in `<symbols>' is evaluated in `env', and
      `s' is bound in the dynamic environment to the result of this
      evaluation.
 
      The following equivalence holds:
 
           ($import! exp . symbols) ==
           ($define! symbols ($remote-eval (list symbols) exp))
 
 
 File: klisp.info,  Node: Combiners,  Next: Continuations,  Prev: Environments,  Up: Top
 
 9 Combiners
 ***********
 
 There are two types of combiners in Kernel, operative and applicative.
 Both types are encapsulated. All combiners are immutable.  Two
 applicatives are `eq?' iff their underlying combiners are `eq?'.
 However, `eq?'-ness of operatives is only constrained by the general
 rules for `eq?', which leave considerable leeway for variation between
 implementations.  klisp only considers `eq?' those operatives
 constructed by the same call to a constructor (e.g. `$vau').  Two
 combiners are `equal?' iff they are `eq?'.
 
  -- Applicative: operative? (operative? . objects)
      The primitive type predicate for type operative. `operative?'
      returns true iff all the objects in `objects' are of type
      operative.
 
  -- Applicative: applicative? (applicative? . objects)
      The primitive type predicate for type applicative.  `applicative?'
      returns true iff all the objects in `objects' are of type
      applicative.
 
  -- Operative: $vau ($vau <formals> <eformal> . <objects>)
      `<formals>' should be a formal parameter tree; `<eformal>' should
      be either a symbol or `#ignore'.  If `<formals>' does not have the
      correct form for a formal parameter tree, or if `<eformal>' is a
      symbol that also occurs in `<formals>', an error is signaled.
 
      A `vau' expression evaluates to an operative; an operative created
      in this way is said to be compound. The environment in which the
      `vau' expression was evaluated is remembered as part of the
      compound operative, called the compound operative’s static
      environment.  `<formals>' and `<objects>' are copied as by
      `copy-es-immutable' and the copies are stored as part of the
      operative being constructed.  This avoids problem if these
      structures are later mutated.
 
      When the compound operative created by `$vau' is later called with
      an object and an environment, here called respectively the operand
      tree and the dynamic environment, the following happens:
 
        1. A new, initially empty environment is created, with the static
           environment as its parent. This will be called the local
           environment.
 
        2. A stored copy of the formal parameter tree formals is matched
           in the local environment to the operand tree, locally binding
           the symbols of formals to the corresponding parts of the
           operand tree.  eformal is matched to the dynamic environment;
           that is, if eformal is a symbol then that symbol is bound in
           the local environment to the dynamic environment.
 
        3. A stored copy of the expressions is evaluated sequentially
           from left to right, with the last (if any) evaluated as a
           tail context, or if the list of expressions is empty, the
           result is inert.
 
      NOTE: Because compound operatives are not a distinct type in
      Kernel, they are covered by the encapsulation of type operative.
      In particular, an implementation of Kernel cannot provide a
      feature that supports extracting the static environment of any
      given compound operative, nor that supports determining whether or
      not a given operative is compound.
 
  -- Applicative: wrap (wrap combiner)
      The `wrap' applicative returns an applicative whose underlying
      combiner is `combiner'.
 
  -- Applicative: unwrap (unwrap applicative)
      The `unwrap' applicative returns the underlying combiner of
      `applicative'.
 
  -- Operative: $lambda ($lambda <formals> . <objects>)
      `<formals>' should be a formal parameter tree.
 
      The `$lambda' operative is defined by the following equivalence:
           ($lambda formals . objects) ==
             (wrap ($vau formals #ignore . objects))
 
  -- Applicative: apply (apply applicative object [environment])
      Applicative `apply' combines the underlying combiner of
      `applicative' with `object' in a tail context with dynamic
      environment `environment' (if the long form is used) or in an
      empty environment (if the short form is used).
 
      The following equivalences hold:
           (apply applicative object environment) ==
             (eval (cons (unwrap applicative) object) environment)
 
           (apply applicative object) ==
             (apply applicative object (make-environment))
 
  -- Applicative: map (map applicative . lists)
      `lists' must be a nonempty list of lists; if there are two or
      more, they must all have the same length. If `lists' is empty, or
      if all of its elements are not lists of the same length, an error
      is signaled.
 
      The `map' applicative applies `applicative' element-wise to the
      elements of the lists in `lists' (i.e., applies it to a list of
      the first elements of the `lists', to a list of the second
      elements of the `lists', etc.), using the dynamic environment from
      which `map' was called, and returns a list of the results, in
      order. The applications may be performed in any order, as long as
      their results occur in the resultant list in the order of their
      arguments in the original `lists'.  If `lists' is a cyclic list,
      each argument list to which `applicative' is applied is
      structurally isomorphic to `lists'.  If any of the elements of
      `lists' is a cyclic list, they all must be, or they wouldn’t all
      have the same length.  Let `a1...an' be their acyclic prefix
      lengths, and `c1...cn' be their cycle lengths.  The acyclic prefix
      length `a' of the resultant list will be the maximum of the `ak',
      while the cycle length `c' of the resultant list will be the least
      common multiple of the `ck'.  In the construction of the result,
      applicative is called exactly `a + c' times.
 
  -- Applicative: string-map (string-map applicative . strings)
  -- Applicative: vector-map (vector-map applicative . vectors)
  -- Applicative: bytevector-map (bytevector-map applicative .
           bytevectors)
      `strings', `vectors', or `bytevectors' should be non-empty lists
      of the corresponding type and all elements should be of the same
      length.
 
      These applicatives behave as `map' except that the list of
      elements passed to `applicative' are the n-th chars, objects, or
      uint8s of the strings, vectors or bytevectors passed as arguments.
 
      SOURCE NOTE: These are taken from r7rs.
 
  -- Applicative: combiner? (combiner? . objects)
      The primitive type predicate for type combiner. `combiner?'
      returns true iff all the objects in `objects' are of type combiner
      (i.e. applicative or operative).
 
 
 File: klisp.info,  Node: Continuations,  Next: Encapsulations,  Prev: Combiners,  Up: Top
 
 10 Continuations
 ****************
 
 A continuation is a plan for all future computation, parameterized by a
 value to be provided, and contingent on the states of all mutable data
 structures (which notably may include environments). When the Kernel
 evaluator is invoked, the invoker provides a continuation to which the
 result of the evaluation will normally be returned.
 
    For example, when `$if' evaluates its test operand, the continuation
 provided for the result expects to be given a boolean value; and,
 depending on which boolean it gets, it will evaluate either the
 consequent or the alternative operand as a tail context — that is, the
 continuation provided for the result of evaluating the selected operand
 is the same continuation that was provided for the result of the call
 to `$if'.
 
    A Kernel program may sometimes capture a continuation; that is,
 acquire a reference to it as a first-class object. The basic means of
 continuation capture is applicative `call/cc'.  Given a first-class
 continuation `c', a combiner can be constructed that will abnormally
 pass its operand tree to `c' (as opposed to the normal return of values
 to continuations). In the simplest case, the abnormally passed value
 arrives at `c' as if it had been normally returned to `c'. In general,
 continuations bypassed by the abnormal pass may have entry/exit guards
 attached to them, and these guards can intercept the abnormal pass
 before it reaches `c'.  Each entry/exit guard consists of a selector
 continuation, which designates which abnormal passes the guard will
 intercept, and an interceptor applicative that performs the
 interception when selected.
 
    Continuations are immutable, and are `equal?' iff `eq?'.  The
 continuation type is encapsulated.
 
  -- Applicative: continuation? (continuation? . objects)
      The primitive type predicate for type continuation.
      `continuation?' returns true iff all the objects in `objects' are
      of type continuation.
 
  -- Applicative: call/cc (call/cc combiner)
      Calls `combiner' in the dynamic environment as a tail context,
      passing as sole operand to it the continuation to which `call/cc'
      would normally return its result.  (That is, constructs such a
      combination and evaluates it in the dynamic environment.)
 
  -- Applicative: extend-continuation (extend-continuation continuation
           applicative [environment])
      The `extend-continuation' applicative constructs and returns a new
      child of `continuation' that, when it normally receives a value v,
      calls the underlying combiner of `applicative' with dynamic
      environment `environment' (or an empty environment if none was
      specified) and operand tree `v', the result of the call normally
      to be returned to `continuation'.
 
      The following equivalnece defines the short version:
           (extend-continuation c a) ==
             (extend-continuation c a (make-environment))
 
  -- Applicative: guard-continuation (guard-continuation entry-guards
           continuation exit-guards)
      `entry-guards' and `exit-guards' should each be a list of clauses;
      each clause should be a list of length two, whose first element is
      a continuation, and whose second element is an applicative whose
      underlying combiner is operative.
 
      Applicative `guard-continuation' constructs two continuations: a
      child of continuation, called the `outer continuation'; and a
      child of the `outer continuation', called the `inner
      continuation'.  The `inner continuation' is returned as the result
      of the call to `guard-continuation'.
 
      When the `inner continuation' normally receives a value, it passes
      the value normally to the `outer continuation'; and when the
      `outer continuation' normally receives a value, it passes the
      value normally to `continuation'. Thus, in the absence of abnormal
      passing, the inner and outer continuations each have the same
      behavior as `continuation'.
 
      The two elements of each guard clause are called, respectively, the
      `selector' and the `interceptor'.  The `selector' continuation is
      used in deciding whether to intercept a given abnormal pass, and
      the `interceptor' applicative is called to perform customized
      action when interception occurs.
 
      At the beginning of the call to `guard-continuation', internal
      copies are made of the evaluation structures of `entry-guards' and
      `exit-guards', so that the selectors and interceptors contained in
      the arguments at that time remain fixed thereafter, independent of
      any subsequent mutations to the arguments.
 
  -- Applicative: continuation->applicative (continuation->applicative
           continuation)
      Returns an applicative whose underlying operative abnormally passes
      its operand tree to `continuation', thus: A series of interceptors
      are selected to handle the abnormal pass, and a continuation is
      derived that will normally perform all the interceptions in
      sequence and pass some value to the destination of the originally
      abnormal pass.  The operand tree is then normally passed to the
      derived continuation.
 
  -- Variable: root-continuation
      This continuation is the ancestor of all other continuations. When
      it normally receives a value, it terminates the Kernel session.
      (For example, if the system is running a read-eval-print loop, it
      exits the loop.)
 
  -- Variable: error-continuation
      The dynamic extent of this continuation is mutually disjoint from
      the dynamic extent in which Kernel computation usually occurs
      (such as the dynamic extent in which the Kernel system would run a
      read-eval-print loop).
 
      When this continuation normally receives a value, it provides a
      diagnostic message to the user of the Kernel system, on the
      assumption that the received value is an attempt to describe some
      error that aborted a computation; and then resumes operation of
      the Kernel system at some point that is outside of all
      user-defined computation. (For example, if the system is running a
      read-eval-print loop, operation may resume by continuing from the
      top of the loop.)
 
      The diagnostic message is not made available to any Kernel
      computation, and is therefore permitted to contain information that
      violates abstractions within the system.
 
      When an error is signaled during a Kernel computation, the
      signaling action consists of an abnormal pass to some continuation
      in the dynamic extent of `error-continuation'.
 
  -- Applicative: apply-continuation (apply-continuation continuation
           object)
      Applicative `apply-continuation' converts its first argument to an
      applicative as if by `continuation->applicative', and then applies
      it as usual.
 
      That is:
           (apply-continuation continuation object) ==
             (apply (continuation->applicative continuation) object)
 
  -- Operative: $let/cc ($let/cc <symbol> . <objects>)
      A child environment `e' of the dynamic environment is created,
      containing a binding of `<symbol>' to the continuation to which
      the result of the call to `$let/cc' should normally return; then,
      the subexpressions of `<objects>' are evaluated in `e' from left
      to right, with the last (if any) evaluated as a tail context, or
      if `<objects>' is empty the result is inert.
 
      That is:
           ($let/cc symbol . objects) ==
             (call/cc ($lambda (symbol) . objects))
 
  -- Applicative: guard-dynamic-extent (guard-dynamic-extent
           entry-guards combiner exit-guards)
      This applicative extends the current continuation with the
      specified guards, and calls `combiner' in the dynamic extent of
      the new continuation, with no operands and the dynamic environment
      of the call to `guard-dynamic-extent'.
 
  -- Applicative: exit (exit [object])
      Applicative `exit' initiates an abnormal transfer of `object' (or
      `#inert' if `object' was not specified), to `root-continuation'.
      That is:
           (exit) == (apply-continuation root-continuation #inert)
           (exit obj) == (apply-continuation root-continuation obj)
 
      SOURCE NOTE: This applicative doesn't have the optional argument in
      the report.  It was added to klisp to allow a simple way to
      terminate the interpreter passing a value that is then tried to
      convert to an exit status.
 
 
 File: klisp.info,  Node: Encapsulations,  Next: Promises,  Prev: Continuations,  Up: Top
 
 11 Encapsulations
 *****************
 
 An encapsulation is an object that refers to another object, called its
 content.  The Kernel data type encapsulation is encapsulated.  Two
 encapsulations are `equal?' iff they are `eq?'.  Encapsulations are
 immutable.
 
  -- Applicative: make-encapsulation-type (make-encapsulation-type)
      Returns a list of the form `(e p? d)', where `e', `p'?, and `d'
      are applicatives, as follows.  Each call to
      `make-encapsulation-type' returns different applicatives `e',
      `p?', and `d'.
 
         * `e' is an applicative that takes one argument, and returns a
           fresh encapsulation with the argument as content.
           Encapsulations returned on different occasions are not `eq?'.
 
         * `p?' is a primitive type predicate, that takes zero or more
           arguments and returns true iff all of them are encapsulations
           generated by `e'.
 
         * `d' is an applicative that takes one argument; if the
           argument is not an encapsulation generated by `e', an error
           is signaled, otherwise the content of the encapsulation is
           returned.
 
      That is, the predicate `p?' only recognizes, and the decapsulator
      `d' only extracts the content of, encapsulations created by the
      encapsulator `e' that was returned by the same call to
      `make-encapsulation-type'.
 
 
 File: klisp.info,  Node: Promises,  Next: Keyed Variables,  Prev: Encapsulations,  Up: Top
 
 12 Promises
 ***********
 
 A promise is an object that represents the potential to determine a
 value.  The value may be the result of an arbitrary computation that
 will not be performed until the value must be determined (constructor
 `$lazy'); or, in advanced usage, the value may be determined before the
 promise is constructed (constructor `memoize').
 
    The value determined by a promise is obtained by forcing it
 (applicative `force').  A given promise cannot determine different
 values on different occasions that it is forced.  Also, if a promise
 determines its value by computation, and that computation has already
 been completed, forcing the promise again will produce the previously
 determined result without re-initiating the computation to determine it.
 
    The Kernel data type promise is encapsulated.
 
    The general rules for predicate `eq?' only require it to distinguish
 promises if they can exhibit different behavior; the resulting leeway
 for variation between implementations is similar, in both cause and
 effect, to that for `eq?'-ness of operatives.  For example, if two
 promises, constructed on different occasions, would perform the same
 computation to determine their values, and that computation has no
 side-effects and must always return the same value, the promises may or
 may not be `eq?'.  Two promises are `equal?' iff they are `eq?'.
 
  -- Applicative: promise? (promise? . objects)
      The primitive type predicate for type promise.  `promise?' returns
      true iff all the objects in `objects' are of type promise.
 
  -- Applicative: force (force object)
      If `object' is a promise, applicative `force' returns the value
      determined by promise; otherwise, it returns `object'.
 
      The means used to force a promise depend on how the promise was
      constructed.  The description of each promise constructor specifies
      how to force promises constructed by that constructor.
 
  -- Operative: $lazy ($lazy expression)
      Operative `$lazy' constructs and returns a new object of type
      promise, representing potential evaluation of expression in the
      dynamic environment from which `$lazy' was called.
 
      When the promise is forced, if a value has not previously been
      determined for it, `expression' is evaluated in the dynamic
      environment of the constructing call to `$lazy'.  If, when the
      evaluation returns a result, a value is found to have been
      determined for the promise during the evaluation, the result is
      discarded in favor of the previously determined value; otherwise,
      the result is forced, and the value returned by that forcing
      becomes the value determined by the promise.
 
      Forcing an undetermined lazy promise (i.e., a promise constructed
      by $lazy for which no value has yet been determined) may cause a
      sequential series of evaluations, each of which returns a promise
      that is forced and thus initiates the next evaluation in the
      series.  The implementation must support series of this kind with
      unbounded length (i.e., unbounded number of sequential
      evaluations).
 
      Note that forcing concerns the value determined by a given promise,
      not the result of evaluating a given expression in a given
      environment. Distinct promises (judged by `eq?' represent
      different occasions of evaluation; so, even if they do represent
      evaluation of the same expression in the same environment, forcing
      one does not necessarily determine the value for the other, and
      actual evaluation will take place the first time each of them is
      forced.
 
  -- Applicative: memoize (memoize object)
      Applicative `memoize' constructs and returns a new object of type
      promise, representing memoization of `object'.  Whenever the
      promise is forced, it determines `object'.
 
  -- Operative: $delay ($delay <expression>)
      Operative `delay' behaves as the composition of `$lazy' and
      `memoize', that is:
           ($delay <expr>) == ($lazy (memoize <expr>))
      SOURCE NOTE: this is taken from r7rs.
 
 
 File: klisp.info,  Node: Keyed Variables,  Next: Numbers,  Prev: Promises,  Up: Top
 
 13 Keyed Variables
 ******************
 
 A keyed variable is a device that associates a non-symbolic key (in the
 form of an accessor applicative) with a value depending on the context
 in which lookup occurs.  Kernel provides two types of keyed variables:
 dynamic & static.  Keyed Dynamic Variables use the dynamic extent as
 context and Keyed Static Variables use the dynamic environment.
 
 13.1 Keyed Dynamic Variables
 ============================
 
 A keyed dynamic variable is a device that associates a non-symbolic key
 (in the form of an accessor applicative) with a value depending on the
 dynamic extent in which lookup occurs.
 
  -- Applicative: make-keyed-dynamic-variable
           (make-keyed-dynamic-variable)
      Returns a list of the form `(b a)', where `b' and `a' are
      applicatives, as follows.  Each call to
      `make-keyed-dynamic-variable' returns different `b' and `a'.
 
         * `b' is an applicative that takes two arguments, the second of
           which must be a combiner.  It calls its second argument with
           no operands (nil operand tree) in a fresh empty environment,
           and returns the result.
 
         * `a' is an applicative that takes zero arguments. If the call
           to `a' occurs within the dynamic extent of a call to `b', then
           `a' returns the value of the first argument passed to `b' in
           the smallest enclosing dynamic extent of a call to `b'. If the
           call to `a' is not within the dynamic extent of any call to
           `b', an error is signaled.
 
 13.2 Keyed Static Variables
 ===========================
 
 A keyed static variable is a device that binds data in an environment
 by a non-symbolic key, where the key is an accessor applicative.
 
  -- Applicative: make-keyed-static-variable (make-keyed-static-variable)
      Returns a list of the form `(b a)', where `b' and `a' are
      applicatives, as follows.  Each call to
      `make-keyed-static-variable' returns different `b' and `a'.
 
         * `b' is an applicative that takes two arguments, the second of
           which must be an environment.  It constructs and returns a
           child-environment of its second argument, with initially no
           local bindings.
 
         * `a' is an applicative that takes zero arguments. If the
           dynamic environment `e' of the call to a has an improper
           ancestor that was constructed by a call to `b', then a
           returns the value of the first argument passed to `b' in the
           first such environment encountered by a depth-first traversal
           of the improper ancestors of `e'. If `e' has no improper
           ancestors constructed via `b', an error is signaled.
 
 
 File: klisp.info,  Node: Numbers,  Next: Strings,  Prev: Keyed Variables,  Up: Top
 
 14 Numbers
 **********
 
 All numbers are immutable, and `equal?' iff `eq?'.  The number type is
 encapsulated.
 
    The external representation of an undefined number is `#undefined'.
 The external representation of a real with no primary value is `#real'
 (but this may change in the future, the report is missing the output
 representation for reals with no primary values).  All other rules for
 externally representing numbers pertain only to defined numbers with
 primary values.
 
    An external representation of a real number consists of optional
 radix and/or exactness prefixes, optional sign (`+' or `-'), and
 magnitude. The radix prefixes are `#b' (binary), `#o' (octal), `#d'
 (decimal), and `#x' (hexadecimal); the default is decimal.  The
 exactness prefixes are `#e' (exact) and `#i' (inexact); by default, the
 number is inexact iff the magnitude representation uses floating point.
 If both kinds of prefixes are used, they may occur in either order. The
 magnitude is either `infinity'; an unsigned integer (nonempty sequence
 of digits); a ratio of unsigned integers (two unsigned integers with a
 `/' between, of which the second is non-zero); or a floating point
 representation.  If the magnitude is `infinity', there must be an
 exactness prefix and a sign, and no radix prefix.  Floating point
 representation can only be used with decimal radix; it consists of
 nonempty integer part, point (`.'), nonempty fraction part, and
 optional exponent part.  The optional exponent part consists of an
 exponent letter, and an (optionally signed) integer indicating a power
 of ten by which to multiply the magnitude.  The choice of exponent
 letter makes no difference in what mathematical number is indicated by
 the external representation, but does indicate internal representation
 precision. Exponent letters `s', `f', `d', `f' indicate preference for
 successively higher internal precision - short, float, double, long.
 When reading an inexact real number, exponent letter `e' accepts the
 default internal precision, which must be at least double.  When
 writeing an inexact real number, exponent letter `e' may be used for
 the default internal precision, and must be used for any internal
 number format not indicated by any of the other exponent letters.
 Float and double must provide, respectively, at least as much precision
 as IEEE 32-bit and 64-bit floating point standards [IE85].  For
 example, `#i#xa/c' represents an inexact number using hexadecimal
 notation, with signed magnitude positive five sixths (ten over twelve).
 `-3.5l-2' represents an inexact number using decimal notation, with
 signed magnitude negative thirty five thousandths, and requested long
 precision (which must be at least IEEE 64-bit floating point).  When
 reading an external representation of an inexact real, the bounds on
 the resulting inexact number are chosen in accordance with the
 narrow-arithmetic keyed dynamic variable.
 
    NOTE: in klisp, all inexact numbers are stored as IEEE 64-bit
 floating point.  No bounding or robustness info is kept.
 
  -- Applicative: number? (number? . objects)
      The primitive type predicate for type number.  `number?' returns
      true iff all the objects in `objects' are of type number.
 
  -- Applicative: integer? (integer? . objects)
      The primitive type predicate for number subtype integer.
      `integer?'  returns true iff all the objects in `objects' are of
      type integer.
 
  -- Applicative: exact-integer? (exact-integer? . objects)
      The primitive type predicate for number subtype exact integer.
      `exact-integer?'  returns true iff all the objects in `objects'
      are of type integer and exact.
 
      SOURCE NOTE: this is from r7rs.
 
  -- Applicative: u8? (u8? . objects)
      The primitive type predicate for number subtype exact integer
      between 0 and 255.  This is the subtype used in bytevectors.  `u8?'
      returns true iff all the objects in `objects' are of type integer,
      are exact, and lie between 0 and 255 inclusive.
 
      SOURCE NOTE: this is handy for use with bytevectors.
 
  -- Applicative: rational? (rational? . objects)
      The primitive type predicate for number subtype rational.
      `rational?'  returns true iff all the objects in `objects' are of
      type rational.
 
  -- Applicative: real? (real? . objects)
      The primitive type predicate for number subtype real.  `real?'
      returns true iff all the objects in `objects' are of type real.
 
  -- Applicative: finite? (finite? . numbers)
      Predicate `finite?' returns true iff all the numbers in `numbers'
      are finite.
 
  -- Applicative: exact? (exact? . numbers)
      Predicate `exact?' returns true iff all the numbers in `numbers'
      are exact.
 
  -- Applicative: inexact? (inexact? . numbers)
      Predicate `inexact?' returns true iff all the numbers in `numbers'
      are inexact.
 
  -- Applicative: robust? (robust? . numbers)
      Predicate `robust?' returns true iff all the numbers in `numbers'
      are robust.
 
  -- Applicative: undefined? (undefined? . numbers)
      Predicate `undefined?' returns true iff all the numbers in
      `numbers' are undefined.
 
  -- Applicative: =? (=? . numbers)
      Applicative `=?' is a predicate that returns true iff all its
      arguments are numerically equal to each other.  If any of its
      arguments has no primary value, an error is signaled.
 
  -- Applicative: <? (<? . reals)
  -- Applicative: <=? (<=? . reals)
  -- Applicative: >? (>? . reals)
  -- Applicative: >=? (>=? . reals)
      Each of these applicatives is a predicate that returns true iff
      every two consecutive elements of `reals' have primary values in
      the order indicated by the name of the applicative.  If any
      element of `reals' has no primary value, an error is signaled.
 
  -- Applicative: + (+ . numbers)
      Applicative `+' returns the sum of the elements of numbers.  If
      numbers is empty, the sum of its elements is exact zero.  If a
      positive infinity is added to a negative infinity, the result has
      no primary value.  If all the elements of a cycle are zero, the
      sum of the cycle is zero.  If the acyclic sum of the elements of a
      cycle (i.e., the sum of an acyclic list containing just those
      elements) is non-zero, the sum of the cycle is positive infinity
      times the acyclic sum of the elements.  If the acyclic sum of the
      elements of a cycle is zero, but some of the elements of the cycle
      are non-zero, the sum of the cycle has no primary value.
 
  -- Applicative: * (* . numbers)
      Applicative `*' returns the product of the elements of numbers.
      If numbers is empty, the product of its elements is exact one.  If
      an infinity is multiplied by zero, the result has no primary
      value.  If the acyclic product of the elements of a cycle is real
      greater than one, the product of the cycle is positive infinity.
      If all the elements of a cycle are positive one, the product of
      the cycle is positive one.  If the acyclic product of the elements
      of a cycle is positive one, but some of the elements of the cycle
      are not positive one, the product of the cycle has no primary
      value.  If the acyclic product of the elements of a cycle has
      magnitude less than one, the product of the cycle is zero.  If the
      acyclic product of the elements of a cycle has magnitude greater
      than or equal to one, and is not positive real, the product of the
      cycle has no primary value.
 
  -- Applicative: - (- number . numbers)
      `numbers' should be a nonempty list of numbers.
 
      Applicative `-' returns the sum of `number' with the negation of
      the sum of `numbers'.
 
  -- Applicative: zero? (zero? . numbers)
      Applicative `zero?' is a predicate that returns true iff every
      element of `numbers' is zero.  For this purpose, a real number is
      zero if its primary value is zero.  If any element of numbers has
      no primary value an error is signaled.
 
  -- Applicative: div (div real1 real2)
  -- Applicative: mod (mod real1 real2)
  -- Applicative: div-and-mod (div-and-mod real1 real2)
      For all three applicatives, if `real1' is infinite or `real2' is
      zero, an error is signaled.
 
      Let `n' be the greatest integer such that `real2 * n <= real1'.
      Applicative `div' returns `n'.  Applicative `mod' returns `real1 -
      (real2 * n)'.  Applicative `div-and-mod' returns a freshly
      allocated list of length two, whose first element is `n' and whose
      second element is `real1 - (real2 * n)'.
 
      NOTE: I'm not really sure about this description...
 
  -- Applicative: div0 (div0 real1 real2)
  -- Applicative: mod0 (mod0 real1 real2)
  -- Applicative: div0-and-mod0 (div0-and-mod0 real1 real2)
      For all three applicatives, if `real1' is infinite or `real2' is
      zero, an error is signaled.
 
      Let `n' be the greatest integer such that `real2 * n <= real1 +
      |real2/2|'.  Applicative `div0' returns `n'.  Applicative `mod0'
      returns `real1 - (real2 * n)'.  Applicative `div0-and-mod0'
      returns a freshly allocated list of length two, whose first
      element is `n' and whose second element is `real1 - (real2 * n)'.
 
      NOTE: I'm not really sure about this description...
 
  -- Applicative: positive? (positive? . reals)
  -- Applicative: negative? (negative? . reals)
      Applicative `positive?' is a predicate that returns true iff every
      element of `reals' is greater than zero. Applicative `negative?'
      is a predicate that returns true iff every element of `reals' is
      less than zero.  If any argument to either applicative has no
      primary value an error is signaled.
 
  -- Applicative: odd? (odd? . integers)
  -- Applicative: even? (even? . integers)
      Applicative `odd?' is a predicate that returns true iff every
      element of `integers' is odd.  Applicative `even?' is a predicate
      that returns true iff every element of `integers' is even.  If any
      argument to either applicative has no primary value an error is
      signaled.
 
  -- Applicative: abs (abs real)
      Applicative `abs' returns the nonnegative real number with the
      same magnitude as `real'; that is, if `real' is nonnegative it
      returns `real', otherwise it returns the negation of `real'.
 
  -- Applicative: max (max . reals)
  -- Applicative: min (min . reals)
      If `reals' is nil, applicative `max' returns exact negative
      infinity, and applicative `min' returns exact positive infinity.
      If `reals' is non-nil, applicative `max' returns the largest
      number in `reals', and applicative `min' returns the smallest
      number in `reals'.
 
  -- Applicative: lcm (lcm . impints)
  -- Applicative: gcd (gcd . impints)
      `impints' should be a list of improper integers, that is, real
      numbers each of which is either an integer or an infinity.
 
      Applicative `lcm' returns the smallest positive improper integer
      that is an improper0integer multiple of every element of `impints'
      (that is, smallest `n >= 1' such that for every argument `nk'
      there exists `n'k' with `nk * n'k = n').  If any of the arguments
      is zero, the result of `lcm' has no primary value.  According to
      these rules, `lcm' with nil argument list returns `1', and `lcm'
      with any infinite argument returns positive infinity.
 
      Applicative `gcd' returns the largest positive improper integer
      such that every element of `impints' is an improper-integer
      multiple of it (that is, largest `n >= 1' such that for every
      argument `nk' there exists `n'k' with `n * n'k = nk').  `gcd' with
      nil argument list returns exact positive infinity.  If `gcd' is
      called with one or more arguments, and at least one of the
      arguments is zero, but none of the arguments is a non-zero finite
      integer, its result has no primary value.  According to these
      rules, if `gcd' is called with at least one finite non-zero
      argument, its result is the same as if all zero and infinite
      arguments were deleted.
 
  -- Applicative: get-real-internal-bounds (get-real-internal-bounds
           real)
  -- Applicative: get-real-exact-bounds (get-real-exact-bounds real)
      Applicative `get-real-internal-bounds' returns a freshly allocated
      list of reals `(x1 x2)', where the primary value of `x1' is the
      lower bound of `real', using the same internal representation as
      the primary value of `real', and the primary value of `x2' is the
      upper bound of `real', using the same internal representation as
      the primary value of `real'.  The `xk' are inexact iff real is
      inexact.  The `xk' are robust (i.e., tagged if the implementation
      supports such), and the bounds of each `xk' are only required to
      contain its primary value (i.e., the implementation is allowed to
      make the bounds equal to the primary value).
 
      Applicative `get-real-exact-bounds' returns a freshly allocated
      list of exact reals `(x1 x2)', where `x1' is not greater than the
      lower bound of `real', and `x2' is not less than the upper bound
      of `real'.
 
  -- Applicative: get-real-internal-primary (get-real-internal-primary
           real)
  -- Applicative: get-real-exact-primary (get-real-exact-primary real)
      If `real' is exact, both applicatives return `real'.  If `real'
      has no primary value, both applicatives signal an error.
 
      If `real' is inexact with a primary value, applicative
      `get-real-internal-primary' returns a real number `x0' whose
      primary value is the same as, and has the same internal format as,
      the primary value of `real'.  `x0' is robust, and its bounds are
      only required to contain its primary value.
 
      If `real' is inexact with a primary value, applicative
      `get-real-exact-primary' returns an exact real number `x0' within
      the exact bounds that would be returned for `real' by applicative
      `get-real-exact-bounds'.  Preferably, `x0' should be as close to
      the primary value of `real' as the implementation can reasonably
      arrange. If the implementation does not support any exact `real'
      that reasonably approximates `real', an error may be signaled.
 
  -- Applicative: make-inexact (make-inexact real1 real2 real3)
      Applicative `make-inexact' returns an inexact real number, as
      follows.  If `real2' is inexact, the result has the same primary
      value as `real2'; and if `real2' has no primary value, the result
      has no primary value.  The result has the same robustness as
      `real2'.  If possible, the result uses the same internal
      representation as `real2'.  If `real2' is exact, the primary value
      of the result is as close to `real2' as the implementation can
      reasonably arrange; overflow and underflow are handled as
      described in ....  The lower bound of the result is no greater than
      the lower bound of `real1', the primary value of `real2', and the
      primary value of the result.  The upper bound of the result is no
      less than the upper bound of `real3', the primary value of
      `real2', and the primary value of the result.
 
  -- Applicative: real->inexact (real->inexact real)
  -- Applicative: real->exact (real->exact real)
      Applicative `real->exact' behaves just as `get-real-exact-primary'.
 
      If `real' is inexact, applicative `real->inexact' returns `real'.
      If `real' is exact, applicative `real->inexact' returns an inexact
      real `x0' such that `real' would be a permissible result of
      passing `x0' to `real->exact'.  If the implementation does not
      support any such `x0', an error may be signaled.  Otherwise, `x0'
      is robust, and its bounds are only required to contain its primary
      value and `real'.
 
  -- Applicative: with-strict-arithmetic (with-strict-arithmetic boolean
           combiner)
  -- Applicative: get-string-arithmetic (get-strict-arithmetic?)
      These applicatives are the binder and accessor of the
      `strict-arithmetic' keyed dynamic variable.  When this keyed
      variable is true, various survivable but dubious arithmetic events
      signal an error - notably, operation results with no primary value,
      and over- and underflows.
 
  -- Applicative: / (/ number . numbers)
      `numbers' should be a nonempty list of numbers.
 
      Applicative `/' returns `number' divided by the product of
      `numbers'.  If the product of `numbers' is zero, an error is
      signaled.  If `number' is infinite and the product of `numbers' is
      infinite, an error is signaled.
 
  -- Applicative: numerator (numerator rational)
  -- Applicative: denominator (denominator rational)
      These applicatives return the numerator and denominator of
      `rational', in least terms (i.e., chosen for the least positive
      denominator).  Note that if `rational' is inexact, and either of
      its bounds is not its primary value, the denominator has upper
      bound positive infinity, and the numerator must have at least one
      infinite bound (two infinite bounds if the bounds of rational
      allow values of both signs).
 
  -- Applicative: floor (floor real)
  -- Applicative: ceiling (ceiling real)
  -- Applicative: truncate (truncate real)
  -- Applicative: round (round real)
      Applicative `floor' returns the largest integer not greater than
      `real'.
 
      Applicative `ceiling' returns the smallest integer not less than
      `real'.
 
      Applicative `truncate' returns the integer closest to `real' whose
      absolute value is not greater than that of `real'.
 
      Applicative `round' returns the closest integer to `real',
      rounding to even when `real' is halfway between two integers.
 
  -- Applicative: rationalize (rationalize real1 real2)
  -- Applicative: simplest-rational (simplest-rational real1 real2)
      A rational number `r1' is simpler than another rational `r2' if
      `r1 = p1 / q1' and `r2 = p2 / q2', both in lowest terms, and `|p1|
      <= |p2|' and `|q1| <= |q2|'. Thus `3/5' is simpler than `4/7'. Not
      all rationals are comparable in this ordering, as for example
      `2/7' and `3/5'.  However, any interval (that contains rational
      numbers) contains a rational number that is simpler than every
      other rational number in that interval.  Note that `0 = 0/1' is
      simpler than any other rational (so that one never has to choose
      between `p/q' and `−p/q').
 
      For applicative `simplest-rational', let `x0' be the simplest
      rational mathematically not less than the primary value of `real1'
      and not greater than the primary value of `real2'.  If no such
      `x0' exists (because the primary value of `real1' is greater, or
      because the primary values of the arguments are equal and
      irrational), or if either argument does not have a primary value,
      an error is signaled.
 
      For applicative `rationalize', let `x0' be the simplest rational
      mathematical number within the interval bounded by the primary
      value of `real1' plus and minus the primary value of `real2'.  If
      no such `x0' exists (because the primary value of `real1' is
      irrational and the primary value `real2' is zero), or if either
      argument does not have a primary value, an error is signaled.
 
      If `real1' and `real2' are exact, the applicative (whichever it
      is) returns exact `x0'.  If one or both of `real1' and `real2' are
      inexact, the applicative returns an inexact rational approximating
      `x0' (as by `real->inexact'.  Note that an inexact result returned
      is not necessarily bounded by the primary values of the arguments;
      but the result is an approximation of `x0', which is so bounded,
      and the bounds of the result include `x0'.
 
  -- Applicative: sqrt (sqrt number)
      If `number' is negative, the result is undefined.
 
      Applicative `sqrt' returns the positive square root of number.
      The result may be inexact even if `number' is exact and the square
      root is rational.
 
  -- Applicative: expt (expt number1 number2)
      Applicative `expt' returns `number1' to the power of `number2'.
      If `number1' is zero, then the result is 1 if `number2' is zero
      and 0 otherwise.
 
  -- Applicative: exp (exp number)
  -- Applicative: log (log number)
  -- Applicative: sin (sin number)
  -- Applicative: cos (cos number)
  -- Applicative: tan (tan number)
  -- Applicative: asin (asin number)
  -- Applicative: acos (acos number)
  -- Applicative: atan (atan number1 [number2])
      These applicatives compute the usual transcendental functions.
      `log' computes the natural logarithm (not the base-10 logarithm).
      The two argument version of `atan' computes `(angle
      (make-recutangular number1 number2))' even thou klisp doesn't
      support complex numbers.
 
      All results may be inexact even if `number' is exact and the
      result of the transcendental function is rational.  TODO add
      intervals returned for multidefined functions (inverses and log)
 
  -- Applicative: string->number (string->number string [radix])
      `radix' should be an exact integer, either 2, 8, 10, or 16.
      `string' should be a string describing a number in the specified
      radix, but may contain a radix prefix to override it.  The default
      `radix', if not supplied, is 10.
 
      Applicative `string->number' returns the best approximation of the
      number represented by `string'.  If `string' is not a valid
      representation of a number in the given `radix' an error is
      signaled.
 
      Examples:
           (string->number "100") => 100
           (string->number "100" 16) => 256
           (string->number "#o100" 2) => 64
           (string->number "1.0") => 1.0
 
      SOURCE NOTE: this is taken from r7rs.
 
  -- Applicative: number->string (number->string number [radix])
      `radix' should be an exact integer, either 2, 8, 10, or 16.  The
      default `radix', if not supplied, is 10.
 
      Applicative `number->string' returns a string representing
      `number' in the given `radix'.  No radix prefix is present in the
      returned string.  If an inexact number is passed together with a
      radix other from 10, an error is signaled.
 
      The returned string is such that
           (string->number (number->string number radix) radix) == number
 
      Examples:
           (number->string 100) => "100"
           (number->string 256 16) => "100"
           (number->string 1.0) => "1.0"
 
      SOURCE NOTE: this is taken from r7rs.
 
 
 File: klisp.info,  Node: Strings,  Next: Characters,  Prev: Numbers,  Up: Top
 
 15 Strings
 **********
 
 A string is an object that represent a sequence of characters (for now,
 only ASCII is supported in klisp, in the future, full UNICODE will be
 supported).  The external representation of strings consists of a
 leading """, the characters of the string and a closing """.  Both
 double quote and backslash should be escaped to appear withing strings.
 Some other characters also have an escaped form for convenience.  All
 of these are written with a leading slash ("\").  In klisp these are:
 double quote ("\""), backslash ("\\"), null ("\0"), alarm ("\a"),
 backspace ("\b"), tab ("\t"), newline ("\n"), return ("\r"), vertical
 tab ("\v"), and formfeed ("\f").  You can also use inline hex escapes
 to include arbitary unicode codepoints (only ASCII range supported for
 now).  The syntax is "\x<hex codepoint>;".  New lines can be escaped to
 simplify the accomodation of literal strings in source code, to do
 this: use "\" followed by any ammount of intraline whitespace, a new
 line and another ammount of intraline whitespace.  All of that intraline
 whitespace and the newline, together with the leading slash is
 discarded by the reader and doesn't end up in the string being read.
 
    A string has a length that is fixed at creation time, and as many
 characters, indexed from `0' to `length-1'.
 
    Strings may be mutable or immutable.  If an attempt is made to
 mutate an immutable string, an error is signaled.  Two immutable
 strings are "eq?" iff they are "equal?".  Two mutable strings are "eq?"
 if they were created by the same constructor call.  Two mutable strings
 are "equal?" iff they are "string=?".  For now it is undefined if a
 mutable and an immutable strings that are "string=?" are "equal?" or
 not.  The only exception is the empty string.  There is only one empty
 string (all empty strings are "eq?"  to each other) and it should be
 considered immutable.  Even if an attempt is made to return a new empty
 string (like calling `(string)', the canonical immutable empty string
 is returned.  The string type is encapsulated.
 
    SOURCE NOTE: This section is still missing from the report.  The
 features defined here were taken mostly from r7rs scheme.  It is
 possible that in the future, klisp only admits immutable strings (like
 lua and java), and that operations for contructing strings are moved to
 a new type (like Java's StringBuilder/StringBuffer).  But for now,
 compatibility with r7rs was preferred/simpler.
 
  -- Applicative: string? (string? . objects)
      The primitive type predicate for type string.  `string?' returns
      true iff all the objects in `objects' are of type string.
 
  -- Applicative: immutable-string? (immutable-string? objects)
  -- Applicative: mutable-string? (mutable-string? objects)
      The primitive type predicates for types immutable string and
      mutable string.  These return true iff all the objects in
      `objects' are of type immutable string or mutable string
      respectively.
 
      SOURCE NOTE: these aren't provided in the Kernel report, but added
      for convenience.  These can be implemented in standard kernel by
      using guards.
 
  -- Applicative: string=? (string=? . strings)
  -- Applicative: string<? (string<? . strings)
  -- Applicative: string<=? (string<=? . strings)
  -- Applicative: string>? (string>? . strings)
  -- Applicative: string>=? (string>=? . strings)
      These predicates compare any number of strings by their
      lexicographic order.
 
  -- Applicative: string-ci=? (string-ci=? . strings)
  -- Applicative: string-ci<? (string-ci<? . strings)
  -- Applicative: string-ci<=? (string-ci<=? . strings)
  -- Applicative: string-ci>? (string-ci>? . strings)
  -- Applicative: string-ci>=? (string-ci>=? . strings)
      These predicates convert the strings to lowercase and then compare
      them using their lexicographic order.
 
  -- Applicative: make-string (make-string k [char])
      Applicative `make-string' constructs and returns a new mutable
      string of length `k'.  If `char' is specified, then all characters
      in the returned string are `char', otherwise the content of the
      string is unspecified.
 
  -- Applicative: string (string . chars)
      Applicative `string' contructs and return a new mutable string
      composed of the character arguments.
 
  -- Applicative: string-length (string-length string)
      Applicative `string-length' returns the length of `string'.
 
  -- Applicative: string-ref (string-ref string k)
      Applicative `string-ref' returns the character of `string' at
      position `k'.  If `k' is out of bounds (i.e. less than `0' or
      greater or equal than `(string-length string)') an error is
      signaled.
 
  -- Applicative: string-set! (string-set! string k char)
      Applicative `string-set!' replaces the character with index `k' in
      `string' with character `char'.  If `k' is out of bounds, or
      `string' is immutable, an error is signaled.
 
  -- Applicative: string-fill! (string-fill! string char)
      Applicative `string-fill!' replaces all the characters in `string'
      with character `char'.  If `string' is an immutable string, an
      error is signaled.
 
  -- Applicative: substring (substring string k1 k2)
      Both `k1' & `k2-1' should be valid indexes in `string'.  Also it
      should be the case that `k1 <= k2'.
 
      Applicative `substring' constructs and returns a new mutable
      string with length `k2 - k1', with the characters from `string',
      starting at index `k1' (inclusive) and ending at index `k2'
      (exclusive).
 
  -- Applicative: string-append (string-append . strings)
      Applicative `string-append' constructs and returns a new mutable
      string consisting of the concatenation of all its arguments.
 
  -- Applicative: string-copy (string-copy string)
      Applicative `string-copy' constructs and returns a new mutable
      string with the same length and characters as `string'.
 
  -- Applicative: string->immutable-string (string->immutable-string
           string)
      Applicative `string->immutable-string' constructs and returns a
      new immutable string with the same length and characters as
      `string'.
 
  -- Applicative: string->list (string->list string)
  -- Applicative: list->string (list->string chars)
  -- Applicative: string->vector (string->vector string)
  -- Applicative: vector->string (vector->string vchars)
  -- Applicative: string->bytevector (string->bytevector string)
  -- Applicative: bytevector->string (bytevector->string bvchars)
      These applicatives convert between strings and list of characters,
      vectors of characters, and bytevectors of characters.  The objects
      returned by these applicatives are always mutable.
 
  -- Applicative: string-upcase (string-upcase string)
  -- Applicative: string-downcase (string-downcase string)
  -- Applicative: string-titlecase (string-titlecase string)
  -- Applicative: string-foldcase (string-foldcase string)
      These applicatives perform the respective case folding on the
      passed `string' and return a new mutable strings as a result.  The
      original `string' is not modified.  For now in klisp only ASCII is
      implemented, and so `string-foldcase' is the same as
      `string-downcase'.
 
 
 File: klisp.info,  Node: Characters,  Next: Ports,  Prev: Strings,  Up: Top
 
 16 Characters
 *************
 
 A character is an object that represents an ASCII character (for now,
 only ASCII is supported in klisp, in the future, full UNICODE will be
 supported).
 
    The external representation of characters consists of a leading "#\"
 and the character or character name or "#\x" followed by the hex
 unicode code point (only ASCII supported for now).  The supported names
 for now are "null", "alarm", "backspace", "tab", "newline", "return",
 "escape", "space", "delete", "vtab", and "formfeed" (this is a
 combination of the ones accepted in r6rs and r7rs).
 
    Characters are immutable.  The character type is encapsulated.
 
    SOURCE NOTE: This section is still missing from the report.  The
 features defined here were taken mostly from r7rs.
 
  -- Applicative: char? (char? . objects)
      The primitive type predicate for type character.  `char?' returns
      true iff all the objects in `objects' are of type character.
 
  -- Applicative: char=? (char=? . chars)
  -- Applicative: char<? (char<? . chars)
  -- Applicative: char<=? (char<=? . chars)
  -- Applicative: char>? (char>? . chars)
  -- Applicative: char>=? (char>=? . chars)
      These predicates compare any number of characters using their
      ASCII value for the comparison.
 
  -- Applicative: char-ci=? (char-ci=? . chars)
  -- Applicative: char-ci<? (char-ci<? . chars)
  -- Applicative: char-ci<=? (char-ci<=? . chars)
  -- Applicative: char-ci>? (char-ci>? . chars)
  -- Applicative: char-ci>=? (char-ci>=? . chars)
      These predicates convert the chars to lowercase and then compare
      their ASCII values.
 
  -- Applicative: char-alphabetic? (char-alphabetic? . chars)
  -- Applicative: char-numeric? (char-numeric? . chars)
  -- Applicative: char-whitespace? (char-whitespace? . chars)
      These predicates return true iff all of their arguments are
      respectively "alphabetic", "numeric", or "whitespace".
 
  -- Applicative: char-upper-case? (char-upper-case? . chars)
  -- Applicative: char-lower-case? (char-lower-case? . chars)
  -- Applicative: char-title-case? (char-title-case? . chars)
      These predicates return true iff all of their arguments are
      respectively "upper case, "lower case", or "title case".
 
      Currently klisp only supports ASCII, so there are no title-cased
      characters (i.e. `char-title-case?' always returns false).
 
  -- Applicative: char-upcase (char-upcase char)
  -- Applicative: char-downcase (char-downcase char)
  -- Applicative: char-titlecase (char-downcase char)
  -- Applicative: char-foldcase (char-downcase char)
      These applicatives return a character `char2' so that:
           (char-ci=? char char2) => #t
 
      If `char' is alphabetic then the following holds:
 
           (char-upper-case? (char-upcase char)) => #t
           (char-lower-case? (char-downcase char)) => #t
 
      Currently klisp only supports ASCII, so `char-foldcase' behaves as
      `char-downcase' and `char-titlecase' behaves as `char-upcase'.
 
  -- Applicative: char->integer (char->integer char)
  -- Applicative: integer->char (integer->char k)
      These applicatives convert between ASCII values (as exact integers
      between 0 and 127) and characters.  If an integer that is out of
      range for ASCII characters is passed to `integer->char', an error
      is signaled.
 
  -- Applicative: char-digit? (char-digit? char [base])
      `base' must be an exact integer, between 2 and 36, it omitted it
      defaults to `10'.
 
      Applicative `char-digit?' is a predicate that returns true iff
      `char' is a digit in base `base'.  If `base' is greater than 10,
      then either upper case or lower case letters can be used.
 
      SOURCE NOTE:  This is like char-numeric? but with bases other than
      10.
 
  -- Applicative: char->digit (char->digit char [base])
  -- Applicative: digit->char (digit->char digit [base])
      `base' must be an exact integer, between 2 and 36, it omitted it
      defaults to `10'.  In `char->digit', `char' should be a character
      such that
           (char-digit? char base) => #t
      In `digit->char', `digit' should be an exact integer such that
           (>=? (- base 1) digit 0) => #t
 
      These two applicatives convert between chars representing digits
      and the corresponding integer values, in arbitrary bases (between
      2 and 36).
 
      `char->digit' accepts either lower or upper case characters (if
      the base is greater than 10), `digit->char' always returns lower
      characters (or numbers of course).
 
      SOURCE NOTE: These are like r7rs digit-value but augmented with a
      base argument.
 
 
 File: klisp.info,  Node: Ports,  Next: Vectors,  Prev: Characters,  Up: Top
 
 17 Ports
 ********
 
 A port is an object that mediates data from an input or to a
 destination.  In the former case, the port is an input port, in the
 latter case, an output port.  The data itself can consist of either
 characters or bytes.  In the former case the port is a textual port and
 in the latter case, a binary port.
 
    There are three textual ports open, binded by dynamic variables, one
 for standard input, output, and error.
 
    Although ports are not considered immutable, none of the operations
 on ports described in this section constitute mutation.  Ports are
 `equal?' iff `eq?'.  The port type is encapsulated.
 
    An auxiliary data type used to signal the end of file was reached is
 `eof'. The eof type consists of a single immutable value, having an
 output only external representation (so that it can never be the normal
 result of a call to read).  The eof type is encapsulated.
 
    SOURCE NOTE:  the eof type is not in the Kernel report, it is used in
 klisp and was taken from r7rs.
 
  -- Applicative: port? (port? . objects)
      The primitive type predicate for type port.  `port?'  returns true
      iff all the objects in `objects' are of type port.
 
  -- Applicative: input-port? (input-port? . objects)
  -- Applicative: output-port? (output-port? . objects)
      Applicative `input-port?' is a predicate that returns true unless
      one or more of its arguments is not an input port.  Applicative
      `output-port?' is a predicate that returns true unless one or more
      of its arguments is not an output port.
 
      Every port must be admitted by at least one of these two
      predicates.
 
  -- Applicative: textual-port? (textual-port? . objects)
  -- Applicative: binary-port? (binary-port? . objects)
      Applicative `textual-port?' is a predicate that returns true
      unless one or more of its arguments is not a textual port.
      Applicative `binary-port?' is a predicate that returns true unless
      one or more of its arguments is not a binary port.
 
      Every port must be admitted by at least one of these two
      predicates.
 
      SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
 
  -- Applicative: file-port? (file-port? . objects)
  -- Applicative: string-port? (string-port? . objects)
  -- Applicative: bytevector-port? (bytevector-port? . objects)
      These applictives are predicates that returns true unless one or
      more of its arguments is not a file, string or bytevector port,
      repectively.
 
      Every port in klisp is be admitted by exactly one of these
      predicates.
 
      SOURCE NOTE: this is missing from Kernel, but convenient in the
      face of the different port types admited by klisp.
 
  -- Applicative: port-open? (port-open? port)
      Applicative `port-open?' returns true iff `port' is still open.
 
      SOURCE NOTE: this is taken from r7rs.
 
  -- Applicative: with-input-from-file (with-input-from-file string
           combiner)
  -- Applicative: with-output-to-file (with-output-to-file string
           combiner)
  -- Applicative: with-error-to-file (with-error-to-file string combiner)
      These three applicatives open the file named in `string' for
      textual input or output, an invoke the binder of either the
      input-port, the output-port or the error-port keyed dynamic
      variables respectively with the opened port & the passed
      `combiner' (this means that the combiner is called in a fresh,
      empty dynamic environment).  When/if the binder normally returns,
      the port is closed.  The result of the applicatives
      `with-input-from-file' and `with-output-from-file' is inert.
 
      SOURCE NOTE: The first two are enumerated in the Kernel report but
      the text is still missing.  The third applicative is from r7rs.
 
  -- Applicative: get-current-input-port (get-current-input-port)
  -- Applicative: get-current-output-port (get-current-output-port)
  -- Applicative: get-current-error-port (get-current-error-port)
      These are the accessors for the input-port, output-port, and
      error-port keyed dynamic variables repectively.
 
      SOURCE NOTE: The first two are enumerated in the Kernel report but
      the text is still missing.  The third applicative is from r7rs.
 
  -- Applicative: open-input-file (open-input-file string)
  -- Applicative: open-binary-input-file (open-binary-input-file string)
      `string' should be the name/path for an existing file.
 
      Applicative `open-input-file' creates and returns a textual input
      port associated with the file represented with `string'.
      Applicative `open-binary-input-file' creates and returns a binary
      input port associated with the file represented with `string'.  In
      either case, if the file can't be opened (e.g. because it doesn't
      exists, or there's a permissions problem), an error is signaled.
 
      SOURCE NOTE: `open-input-file' is enumerated in the Kernel report
      but the text is still missing. `open-binary-input-file' is from
      r7rs.
 
  -- Applicative: open-output-file (open-output-file string)
  -- Applicative: open-binary-output-file (open-binary-output-file
           string)
      `string' should be the name/path for an existing file.
 
      Applicative `open-output-file' creates and returns a textual
      output port associated with the file represented with `string'.
      Applicative `open-binary-output-file' creates and returns a binary
      output port associated with the file represented with `string'.
      In either case, if the file can't be opened (e.g. if there's a
      permissions problem), an error is signaled.
 
      In klisp, for now, applicative `open-output-file' and
      `open-binary-output-file' truncate the file if it already exists,
      but that could change later (i.e. like in Scheme the behaviour
      should be considered unspecified).
 
      SOURCE NOTE: `open-output-file' is enumerated in the Kernel report
      but the text is still missing. `open-binary-output-file' is from
      r7rs.
 
  -- Applicative: open-input-string (open-output-string string)
  -- Applicative: open-input-bytevector (open-output-bytevector
           bytevector)
      These applicative return a fresh input port that reads characters
      or unsigned bytes from the passed sequence.
 
      SOURCE NOTE: These are taken from r7rs.
 
  -- Applicative: open-output-string (open-output-string)
      Applicative `open-output-string' returns a fresh textual output
      port that accumulates characters.  The accumulated data can be
      obtained via applicative `get-output-string'.
 
      SOURCE NOTE: This is taken from r7rs.
 
  -- Applicative: open-output-bytevector (open-output-bytevector)
      Applicative `open-output-bytevector' returns a fresh binary output
      port that accumulates unsigned bytes.  The accumulated data can be
      obtained via applicative `get-output-bytevector'.
 
      SOURCE NOTE: This is taken from r7rs.
 
  -- Applicative: close-input-file (close-input-file input-port)
  -- Applicative: close-output-file (close-output-file output-port)
      These applicatives close the port argument, so that no more
      input/output may be performed on them, and the resources can be
      freed.  If the port was already closed these applicatives have no
      effect.
 
      The result returned by applicatives `close-input-file' and
      `close-output-file' is inert.
 
      SOURCE NOTE: this is enumerated in the Kernel report but the text
      is still missing.  There's probably a name error here.  These
      should probably be called close-input-port & close-output-port.
 
  -- Applicative: close-input-port (close-input-port input-port)
  -- Applicative: close-output-port (close-output-port output-port)
  -- Applicative: close-port (close-port port)
      These applicatives close the port argument, so that no more
      input/output may be performed on them, and the resources can be
      freed.  If the port was already closed these applicatives have no
      effect.  If at some time klisp provided input/output ports these
      could be used to selectively close only one direction of the port.
 
      The result returned by applicatives `close-input-port',
      `close-output-port', and `close-port' is inert.
 
      SOURCE NOTE: this is from r7rs. The equivalent `close-input-file'
      and `close-output-file' are probably name errors and only retained
      here till the draft standard rectifies them.
 
  -- Applicative: get-output-string (get-output-string port)
      `port' should be a string output port.
 
      Applicative `get-output-string' returns a freshly created mutable
      string representing the characters accumulated in `port' so far.
      `port' can be either open or closed.
 
      SOURCE NOTE: This is taken from r7rs.
 
  -- Applicative: get-output-bytevector (get-output-bytevector port)
      `port' should be a bytevector output port.
 
      Applicative `get-output-bytevector' returns a freshly created
      mutable bytevector representing the unsigned bytes accumulated in
      `port' so far.  `port' can be either open or closed.
 
      SOURCE NOTE: This is taken from r7rs.
 
  -- Applicative: read (read [port])
      If the `port' optional argument is not specified, then the value
      of the `input-port' keyed dynamic variable is used.  If the port
      is closed, an error is signaled.  The port should be a textual
      input port.
 
      Applicative `read' reads & returns the next parseable object from
      the given port, or the `eof' if no objects remain.  If `read'
      finds and unparseable object in the port, an error is signaled.
      In that case, the remaining position in the port is unspecified.
 
      SOURCE NOTE: this is enumerated in the Kernel report but the text
      is still missing.
 
  -- Applicative: write (write object [port])
      If the `port' optional argument is not specified, then the value
      of the `output-port' keyed dynamic variable is used.  If the port
      is closed, an error is signaled.  The port should be a textual
      output port.
 
      Applicative `write' writes an external representation of `object'
      to the specified port.  This may be an output-only representation
      that can't be read by applicative `read' in cases where the type
      of `object' doen't have a parseable external representation (e.g.
      combiners and environments).  The result returned by `write' is
      inert.  `write' is guaranteed to terminate even in the case of
      objects with shared or cyclic structure.  In those cases `write'
      will use special syntax to preserve sharing info.
 
      SOURCE NOTE: this is enumerated in the Kernel report but the text
      is still missing.
 
  -- Applicative: write-simple (write-simple object [port])
      Applicative `write-simple' is like `write' except that it doesn't
      write sharing info. It will hang if handed a cyclic structure.
 
      SOURCE NOTE: this is taken from r7rs.
 
  -- Applicative: eof-object? (eof-object? . objects)
      The primitive type predicate for type eof.  `eof-object?' returns
      true iff all the objects in `objects' are of type eof.
 
      SOURCE NOTE: This is not in the report, the idea is from Scheme.
      The `eof-object?' name is also from Scheme, but this will probably
      be changed to just `eof?', for consistency with the other primitive
      type predicates.
 
  -- Applicative: newline (newline [port])
      If the `port' optional argument is not specified, then the value
      of the `output-port' keyed dynamic variable is used.  If the port
      is closed, an error is signaled.  The port should be a textual
      output port.
 
      Applicative `newline' writes a newline to the specified port.  The
      result returned by `newline' is inert.
 
      SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
 
  -- Applicative: display (display object [port])
      If the `port' optional argument is not specified, then the value
      of the `output-port' keyed dynamic variable is used.  If the port
      is not a textual output port, or is closed, an error is signaled.
 
      Applicative `display' behaves like `write' except that strings are
      not enclosed in double quotes and no character is escaped within
      those strings and character objects are output as if by
      `write-char' instead of `write'. The result returned by `display'
      is inert.
 
      SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
 
  -- Applicative: read-line (read-line [port])
      If the `port' optional argument is not specified, then the value
      of the `input-port' keyed dynamic variable is used.  If the port
      is closed or if it is not a textual input port, an error is
      signaled.
 
      Applicative `read-line'
 
      SOURCE NOTE: this is taken from r7rs.
 
  -- Applicative: flush-output-port (flush-output-port [port])
      If the `port' optional argument is not specified, then the value
      of the `output-port' keyed dynamic variable is used.  If the port
      is closed or if it is not an output port, an error is signaled.
 
      Applicative `flush-output-port' flushes any buffered data in the
      output port to the underlying object (file, socket, pipe, memory
      sector, device, etc).  The result returned by `flush-output-port'
      is inert.
 
      SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
 
  -- Applicative: write-char (write-char char [port])
      If the `port' optional argument is not specified, then the value
      of the `output-port' keyed dynamic variable is used.  If the port
      is closed, an error is signaled.  The port should be a textual
      output port.
 
      Applicative `write-char' writes the `char' character (not an
      external representation of the character) to the specified port.
      The result returned by `write-char' is inert.
 
      SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
 
  -- Applicative: read-char (read-char [port])
      If the `port' optional argument is not specified, then the value
      of the `input-port' keyed dynamic variable is used.  If the port
      is closed, an error is signaled.  The port should be a textual
      input port.
 
      Applicative `read-char' reads and returns a character (not an
      external representation of a character) from the specified port,
      or an `eof' if the end of file was reached.
 
      SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
 
  -- Applicative: peek-char (peek-char [port])
      If the `port' optional argument is not specified, then the value
      of the `input-port' keyed dynamic variable is used.  If the port
      is closed, an error is signaled.  The port should be a textual
      input port.
 
      Applicative `peek-char' reads and returns a character (not an
      external representation of a character) from the specified port,
      or an `eof' if the end of file was reached.  The position of the
      port remains unchanged so that new call to `peek-char' or
      `read-char' on the same port return the same character.
 
      SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
 
  -- Applicative: char-ready? (char-ready? [port])
      If the `port' optional argument is not specified, then the value
      of the `input-port' keyed dynamic variable is used.  If the port
      is closed, an error is signaled.  The port should be a textual
      input port.
 
      Predicate `char-ready?' checks to see if a character is available
      in the specified port.  If it returns true, then a `read-char' or
      `peek-char' on that port is guaranteed not to block/hang.  For now
      in klisp this is hardcoded to `#t' because the code to do this is
      non-portable.
 
      SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
 
  -- Applicative: write-u8 (write-u8 u8 [port])
      If the `port' optional argument is not specified, then the value
      of the `output-port' keyed dynamic variable is used.  If the port
      is closed, an error is signaled.  The port should be a binary
      output port.
 
      Applicative `write-u8' writes the byte represented by the unsigned
      integer `u8', that should be between 0 and 255 inclusive, (not an
      external representation of byte) to the specified port.  The
      result returned by `write-u8' is inert.
 
      SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
 
  -- Applicative: read-u8 (read-u8 [port])
      If the `port' optional argument is not specified, then the value
      of the `input-port' keyed dynamic variable is used.  If the port
      is closed, an error is signaled.  The port should be a binary input
      port.
 
      Applicative `read-u8' reads and returns a byte as an exact
      unsigned integer between 0 and 255 inclusive (not an external
      representation of a byte) from the specified port, or an `eof' if
      the end of file was reached.
 
      SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
 
  -- Applicative: peek-u8 (peek-u8 [port])
      If the `port' optional argument is not specified, then the value
      of the `input-port' keyed dynamic variable is used.  If the port
      is closed, an error is signaled.  The port should be a binary
      input port.
 
      Applicative `peek-u8' reads and returns a byte as an exact
      unsigned integer between 0 and 255 inclusive (not an external
      representation of a byte) from the specified port, or an `eof' if
      the end of file was reached.  The position of the port remains
      unchanged so that new call to `peek-u8' or `read-u8' on the same
      port return the same byte.
 
      SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
 
  -- Applicative: u8-ready? (u8-ready? [port])
      If the `port' optional argument is not specified, then the value
      of the `input-port' keyed dynamic variable is used.  If the port
      is closed, an error is signaled.  The port should be a binary
      input port.
 
      Predicate `u8-ready?' checks to see if a byte is available in the
      specified port.  If it returns true, then a `read-u8' or `peek-u8'
      on that port is guaranteed not to block/hang.  For now in klisp
      this is hardcoded to `#t' because the code to do this is
      non-portable.
 
      SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
 
  -- Applicative: call-with-input-file (call-with-input-file string
           combiner)
  -- Applicative: call-with-output-file (call-with-output-file string
           combiner)
      These applicatives open file named in `string' for textual
      input/output respectively and call their `combiner' argument in a
      fresh empty environment passing it as a sole operand the opened
      port.  When/if the combiner normally returns a value the port is
      closed and that value is returned as the result of the applicative.
 
      SOURCE NOTE: this is enumerated in the Kernel report but the text
      is still missing.
 
  -- Applicative: load (load string)
      Applicative `load' opens the file named `string' for textual
      input; reads immutable objects from the file until the end of the
      file is reached; evaluates those objects consecutively in the
      created environment.  The result from applicative `load' is inert.
 
      Notice that if `string' is a relative path it is looked in the
      current directory (whatever that means in your OS, normally the
      directory from which the interpreted was run or the directory where
      the interpreter executable lives).  klisp doesn't track the
      directory from which the current code was read, so there's in
      principle no way to load a file in the same directory as the
      currently executing code with a relative path.  See
      `find-required-filename' for a way to look for a file in a number
      of directories.
 
      SOURCE NOTE: load is enumerated in the Kernel report, but the
      description is not there yet.  This seems like a sane way to define
      it, taking the description of `get-module' that there is in the
      report.  The one detail that I think is still open, is whether to
      return `#inert' (as is the case with klisp currently) or rather
      return the value of the last evaluation.
 
  -- Applicative: require (require string)
      Applicative `require' looks for `string' following the algorithm
      described in applicative `find-required-filename'.  If an
      appropriate file can't be found, and error is signaled.  Otherwise,
      the file is opened for textual input; immutable objects are read
      and acumulated until the end of file is found; those objects are
      evaluated in a fresh standard environment; the results of
      evaluation are discarded and the result from applicative `require'
      is inert.
 
      Applicative `require' also register `string' (as via applicative
      `register-requirement!') so that subsequent calls to `require'
      with exactly the same `string' will not cause any search or
      evaluation.  The mechanism used for this can also be manipulated
      directly by the programmer via applicatives
      `registered-requirement?', `register-requirement!',
      `unregister-requirement!', and `find-required-filename'.
 
      Applicative `require' is useful to load klisp libraries.
 
      SOURCE NOTE: require is taken from lua and r7rs.
 
  -- Applicative: registered-requirement? (registered-requirement?
           string)
  -- Applicative: register-requirement! (register-requirement! string)
  -- Applicative: unregister-requirement! (unregister-requirement!
           string)
  -- Applicative: find-required-filename (find-required-filename string)
      `string' should be non-empty.
 
      These applicatives control the underlying facilities used by
      `require' to register already required files.  Predicate
      `registered-requirement?' returns true iff `string' is already
      registered.  `register-requirement!' marks `string' as registered
      (throws an error if it was already registered).
      `unregister-requirement!' marks `string' as not being registered
      (throws an error if it wasn't registered).
      `find-required-filename' looks for an appropriate file for
      `string' using the algorithm described below.
 
      filename search in controlled by environment variable
      `KLISP_PATH'.  This environment variable should be a list of
      templates separated with semicolons (";").  Each template is a
      string that may contain embedded question mark characters ("?") to
      be replaced with `string'.  After replacements, each template
      represents the path to a file.  All templates are probed in order,
      and the first to name an existing readable file is returned.  If no
      template corresponds to an existing readable file, an error is
      signaled.
 
      NOTE: in the future there will be some mechanism to alter the
      search algorithm dinamically, in the meantime this environment
      variable is the only way to customize it.
 
      SOURCE NOTE: this is not in Kernel, they are supplied per guideline
      G1b of the report (extensibility), so that klisp programs can
      easily duplicate the behaviour of `require'
 
  -- Applicative: get-module (get-module string [environment])
      Applicative `get-module' creates a fresh standard environment;
      opens the file named `string' for textual input; reads objects
      from the file until the end of the file is reached; evaluates those
      objects consecutively in the created environment; and, lastly,
      returns the created environment.  If the optional argument
      `environment' is specified, the freshly created standard
      environment is augmented, prior to evaluating read expressions, by
      binding symbol `module-parameters' to the `environment' argument.
 
 
 File: klisp.info,  Node: Vectors,  Next: Bytevectors,  Prev: Ports,  Up: Top
 
 18 Vectors
 **********
 
 A vector is an object that contains a sequence of arbitrary klisp
 objects.  A vector has a length that is fixed at creation time, and as
 many objects, indexed from `0' to `length-1'.  Compared to lists, klisp
 vectors use less size and have constant access time for any element.
 
    Vectors may be mutable or immutable.  If an attempt is made to mutate
 an immutable vector, an error is signaled.  Two immutable vectors are
 "eq?" iff they are "equal?".  Two mutable vectors are "eq?" if they
 were created by the same constructor call.  Two mutable vectors are
 "equal?" iff they have the same length and have "equal?"  objects in
 each position.  As is the case for lists, in order to handle possibly
 cyclic structures, the "equal?" algorithm considers vectors as FSMs
 where it position is a state change.  There is only one empty vector
 (that is, a vector of length 0) and that vector is immutable.  The
 vector type is encapsulated.
 
    SOURCE NOTE: The report doesn't currently include vectors. They are
 taken from r7rs scheme.
 
  -- Applicative: vector? (vector? . objects)
      The primitive type predicate for type vector.  `vector?' returns
      true iff all the objects in `objects' are of type vector.
 
  -- Applicative: immutable-vector? (immutable-vector? objects)
  -- Applicative: mutable-vector? (mutable-vector? objects)
      The primitive type predicates for types immutable vector and
      mutable vector.  These return true iff all the objects in
      `objects' are of type immutable vector or mutable vector
      respectively.
 
  -- Applicative: make-vector (make-vector k [obj])
      Applicative `make-vector' constructs and returns a new mutable
      vector of length `k'.  If `obj' is specified, then all objects in
      the returned vector are `obj', otherwise the content of the vector
      is unspecified.
 
  -- Applicative: vector-length (vector-length vector)
      Applicative `vector-length' returns the length of `vector'.
 
  -- Applicative: vector-ref (vector-ref vector k)
      Applicative `vector-ref' returns the object of `vector' at
      position `k'.  If `k' is out of bounds (i.e. less than `0' or
      greater or equal than `(vector-length vector)') an error is
      signaled.
 
  -- Applicative: vector-set! (vector-set! vector k obj)
      Applicative `vector-set!' replaces the object with index `k' in
      `vector' with object `obj'.  If `k' is out of bounds, or `vector'
      is immutable, an error is signaled. The result returned by
      `vector-set!' is inert.
 
  -- Applicative: vector (vector . objs)
      Applicative `vector' contructs and return a new mutable vector
      composed of the object arguments.
 
  -- Applicative: vector->list (vector->list vector)
  -- Applicative: list->vector (list->vector objs)
      These applicatives convert between vectors and lists.  The objects
      returned by these applicatives are always mutable.
 
  -- Applicative: vector-copy (vector-copy vector)
      Applicative `vector-copy' constructs and returns a new mutable
      vector with the same length and objects as `vector'.
 
  -- Applicative: vector->bytevector (vector->bytevector vector)
  -- Applicative: bytevector->vector (bytevector->vector bytevector)
      These applicatives convert between vectors and bytevectors.  If a
      vector containing objects other than exact integers between 0 and
      255 inclusive are passed to `vector->bytevector', an error is
      signaled.  The objects returned by these applicatives are always
      mutable.
 
  -- Applicative: vector->string (vector->string vector)
  -- Applicative: string->vector (string->vector string)
      These applicatives convert between vectors and strings.  If a
      vector containing objects other than characters is passed to
      `vector->string', an error is signaled.  The objects returned by
      these applicatives are always mutable.
 
  -- Applicative: vector-copy! (vector-copy! vector1 vector2)
      vector2 should have a length greater than or equal to that of
      vector1.
 
      Copies the values in vector1 to the corresponding positions in
      vector2.  If vector2 is immutable, an error is signaled.  The
      result returned by `vector-copy!' is inert.
 
  -- Applicative: vector-copy-partial (vector-copy-partial vector k1 k2)
      Both `k1' & `k2' should be valid indexes in `vector'.  Also it
      should be the case that `k1 <= k2'.
 
      Applicative `vector-copy-partial' constructs and returns a new
      mutable vector with length `k2 - k1', with the objects from
      `vector', starting at index `k1' (inclusive) and ending at index
      `k2' (exclusive).
 
  -- Applicative: vector-copy-partial! (vector-copy-partial! vector1 k1
           k2 vector2 k3)
      Both `k1' & `k2-1' should be valid indexes in `vector1'.  Also it
      should be the case that `k1 <= k2'.  Both `k3' & `k3 + (k2-k1) -
      1' should be valid indexes in `vector2'.
 
      Applicative `vector-copy-partial!' copies objects k1 (inclusive)
      through k2 (exclusive) from `vector1' to the `k2-k1' positions in
      `vector2' starting at `k3'.  If `vector2' is an immutable vector,
      an error is signaled.  The result returned by
      `vector-copy-partial!' is inert.
 
  -- Applicative: vector-fill! (vector-fill! vector obj)
      Applicative `vector-fill!' replaces all the objects in `vector'
      with object `obj'.  If `vector' is an immutable vector, an error
      is signaled.  The result returned by `vector-fill!' is inert.
 
  -- Applicative: vector->immutable-vector (vector->immutable-vector
           vector)
      Applicative `vector->immutable-vector' constructs and returns a
      new immutable vector with the same length and objects as `vector'.
 
 
 File: klisp.info,  Node: Bytevectors,  Next: Errors,  Prev: Vectors,  Up: Top
 
 19 Bytevectors
 **************
 
 A bytevector is an object that contains a sequence of bytes, that is,
 exact integers between 0 and 255 inclusive.  A bytevector has a length
 that is fixed at creation time, and as many bytes, indexed from `0' to
 `length-1'.  Compared to vectors, bytevectors use less size for each
 element.
 
    Bytevectors may be mutable or immutable.  If an attempt is made to
 mutate an immutable bytevector, an error is signaled.  Two immutable
 bytevectors are "eq?" iff they are "equal?".  Two mutable bytevectors
 are "eq?" if they were created by the same constructor call.  Two
 mutable bytevectors are "equal?" iff they have the same length and have
 "equal?"  bytes in each position.  There is only one empty bytevector
 (that is, a bytevector of length 0) and that bytevector is immutable.
 The bytevector type is encapsulated.
 
    SOURCE NOTE: The report doesn't currently include bytevectors. They
 are taken from r7rs scheme.
 
  -- Applicative: bytevector? (bytevector? . obje)
      The primitive type predicate for type bytevector.  `bytevector?'
      returns true iff all the objects in `objects' are of type
      bytevector.
 
  -- Applicative: immutable-bytevector? (immutable-bytevector? objects)
  -- Applicative: mutable-bytevector? (mutable-bytevector? objects)
      The primitive type predicates for types immutable bytevector and
      mutable bytevector.  These return true iff all the objects in
      `objects' are of type immutable bytevector or mutable bytevector
      respectively.
 
  -- Applicative: make-bytevector (make-bytevector k [u8])
      Applicative `make-bytevector' constructs and returns a new mutable
      bytevector of length `k'.  If `u8' is specified, then all bytes in
      the returned bytevector are `obj', otherwise the content of the
      bytevector is unspecified.
 
  -- Applicative: bytevector-length (bytevector-length bytevector)
      Applicative `bytevector-length' returns the length of `bytevector'.
 
  -- Applicative: bytevector-ref (bytevector-ref bytevector k)
      Applicative `bytevector-ref' returns the byte of `bytevector' at
      position `k'.  If `k' is out of bounds (i.e. less than `0' or
      greater or equal than `(bytevector-length bytevector)') an error
      is signaled.
 
  -- Applicative: bytevector-set! (bytevector-set! bytevector k u8)
      Applicative `bytevector-set!' replaces the byte with index `k' in
      `bytevector' with byte `u8'.  If `k' is out of bounds, or
      `bytevector' is immutable, an error is signaled. The result
      returned by `bytevector-set!' is inert.
 
  -- Applicative: bytevector (bytevector . u8s)
      Applicative `bytevector' contructs and return a new mutable
      bytevector composed of the byte arguments.
 
  -- Applicative: bytevector->list (bytevector->list bytevector)
  -- Applicative: list->bytevector (list->bytevector u8s)
      These applicatives convert between bytevectors and lists of bytes.
      If the list passed to `list->bytevector' contains an object that
      isn't a byte, an error is signaled.  The objects returned by these
      applicatives are always mutable.
 
  -- Applicative: bytevector-copy (bytevector-copy bytevector)
      Applicative `bytevector-copy' constructs and returns a new mutable
      bytevector with the same length and bytes as `bytevector'.
 
  -- Applicative: bytevector->vector (bytevector->vector bytevector)
  -- Applicative: vector->bytevector (vector->bytevector vector)
      These applicatives convert between bytevectors and vectors.  If a
      vector containing objects other than bytes (exact integers between
      0 and 255 inclusive) is passed to `vector->bytevector', an error is
      signaled.  The objects returned by these applicatives are always
      mutable.
 
  -- Applicative: bytevector-copy! (bytevector-copy! bytevector1
           bytevector2)
      bytevector2 should have a length greater than or equal to that of
      bytevector1.
 
      Copies the bytes in bytevector1 to the corresponding positions in
      bytevector2.  If bytevector2 is immutable, an error is signaled.
      The result returned by `bytevector-copy!' is inert.
 
  -- Applicative: bytevector-copy-partial (bytevector-copy-partial
           bytevector k1 k2)
      Both `k1' & `k2' should be valid indexes in `bytevector'.  Also it
      should be the case that `k1 <= k2'.
 
      Applicative `bytevector-copy-partial' constructs and returns a new
      mutable bytevector with length `k2 - k1', with the bytes from
      `bytevector', starting at index `k1' (inclusive) and ending at
      index `k2' (exclusive).
 
  -- Applicative: bytevector-copy-partial! (bytevector-copy-partial!
           bytevector1 k1 k2 bytevector2 k3)
      Both `k1' & `k2-1' should be valid indexes in `bytevector1'.  Also
      it should be the case that `k1 <= k2'.  Both `k3' & `k3 + (k2-k1)
      - 1' should be valid indexes in `bytevector2'.
 
      Applicative `bytevector-copy-partial!' copies bytes k1 (inclusive)
      through k2 (exclusive) from `bytevector1' to the `k2-k1' positions
      in `bytevector2' starting at `k3'.  If `bytevector2' is an
      immutable bytevector, an error is signaled.  The result returned
      by `bytevector-copy-partial!' is inert.
 
  -- Applicative: bytevector-fill! (bytevector-fill! bytevector u8)
      Applicative `bytevector-fill!' replaces all the bytes in
      `bytevector' with byte `u8'.  If `bytevector' is an immutable
      bytevector, an error is signaled.  The result returned by
      `bytevector-fill!' is inert.
 
  -- Applicative: bytevector->immutable-bytevector
           (bytevector->immutable-bytevector bytevector)
      Applicative `bytevector->immutable-bytevector' constructs and
      returns a new immutable bytevector with the same length and bytes
      as `bytevector'.
 
 
 File: klisp.info,  Node: Errors,  Next: Libraries,  Prev: Bytevectors,  Up: Top
 
 20 Errors
 *********
 
 An error object contains information that can be used to describe an
 error that occured in the klisp system.  The interpreter will pass an
 error object to an error continuation whenever it needs to signal that
 an error occured while executing a program or evaluating an expression.
 
    An error object contains a message describing the situation and a
 (possibly empty) list of objects, called its irritants, that provide
 some context or additional info depending on the error condition.  The
 error type is encapsulated.
 
    Notice that unlike in most other languages, the error object in klisp
 isn't used to classify the error in error handlers, the error
 continuation being passed the error object is used for that.  The error
 object is used only to convey additional info, not the type of error.
 
    SOURCE NOTE: The type of object passed to the error continuation is
 not specified in the Kernel Report.  This type was inspired by r7rs
 scheme.
 
  -- Applicative: error-object? (error-object? . objs)
      The primitive type predicate for type error.  `error-object?'
      returns true iff all the objects in `objects' are of type error.
 
  -- Applicative: error (error msg . objs)
      Create an error object with message `msg' and irritants the list
      of objects `objs' and then send that error object to the error
      continuation.  This is the recommended way to signal an error in
      klisp.
 
  -- Applicative: raise (raise obj)
      Send `obj' to the error continuation.  `obj' needs not be an error
      object, any kind of object can be sent to the error continuation
      (but that's not recommended!).
 
  -- Applicative: error-object-message (error-object-message error)
      Applicative `error-object-message' extracts the message of `error'.
 
  -- Applicative: error-object-irritants (error-object-irritants error)
      Applicative `error-object-irritants' extracts the irritants of
      `error'.
 
 
 File: klisp.info,  Node: Libraries,  Next: System,  Prev: Errors,  Up: Top
 
 21 Libraries
 ************
 
 Libraries provide a way to organize klisp code with a clean & clear
 interface to the rest of the program.  They are first class objects (as
 all manipulable entities in Kernel, and according to the guidelines in
 the Kernel report). A library has list of exported symbols and values
 for those symbols (generally combiners but may be any object). The
 library type is encapsulated.
 
    In addition there's a mechanism to refer to library objects by name
 (where a name is actually a unique list of symbols and numbers), with
 the ability to register new libraries, get the library object from a
 name, unregister libraries, etc.
 
    These two ways of working with libraries conform the low level API to
 libraries and are orthogonal to each other.  They are provided to allow
 klisp programs to construct their own interface to library definition
 and use, and to respect the guidelines and spirit of the Kernel Report.
 
    There's also a higher level API that is a combination of the lower
 level APIs and behaves more like traditional module systems.  This is
 probably what most klisp programs will use.  This API consist of the
 `$provide-library!' operative to define (and register) new libraries
 and the `$import-library!' operative to extract bindings out of
 existing libraries.  This allows various forms of controlling which
 bindings are extracted from the libraries and allows various forms of
 renaming. It can be used both in the body of libraries or in the top
 level.
 
    No association is made by klisp between source files and libraries.
 For a possible mechanism to handle this see `require' in the ports
 module. Also no special meaning is assigned to the library names.  This
 could be used by an even higher level API, for example to map to
 version numbers and/or to the underlying filesystem.
 
    SOURCE NOTE: This is mostly an adaptation from the r7rs draft of
 scheme.  There's no mention of libraries in the Kernel Report, but they
 were deemed important for klisp in order to share and distribute code
 with a common interface.  A number of adaptations were made to the
 scheme version to sit more comfortably with the Kernel way of doing
 things (first class status, exposing of the library register, etc).
 
  -- Applicative: library? (library? . objects)
      The primitive type predicate for type library.  `library?' returns
      true iff all the objects in `objects' are of type library.
 
      NOTE: This is part of the low level API to libraries. It won't be
      needed to writers or users of libraries that stick to the higher
      level API (i.e. `$provide-library!' & `$import-library!').
 
  -- Applicative: make-library (make-library bindings)
      `bindings' should be an acyclic list of `(symbol . value)' pairs.
      Each symbol may only occur once in the list.
 
      Constructs a new library object with the passed `bindings' as
      exported objects.
 
      NOTE: This is part of the low level API to libraries, writers of
      libraries are encouraged to use `$provide-library!' to define
      their libraries.
 
  -- Applicative: get-library-export-list (get-library-export-list
           library)
  -- Applicative: get-library-environment (get-library-environment
           library)
      `get-library-export-list' returns the list of symbols exported
      from the passed library.  `get-library-environment' returns a
      fresh empty environment whose parent has all exported symbols of
      the library bound to the exported objects.
 
      NOTE: This is part of the low level API to libraries, users of
      libraries are encouraged to use `$import-library!' to get bindings
      out of libraries (and into the current environment).
 
  -- Operative: $registered-library? ($registered-library? name)
  -- Operative: $get-registered-library ($get-registered-library name)
  -- Operative: $register-library! ($register-library! name library)
  -- Operative: $unregister-library! ($unregister-library! name)
      `name' should a an acyclic list of symbols and exact non-negative
      integers.  Two registered libraries can't have the same name (in
      the sense of `equal?').
 
      These operatives control the library registry that maps names to
      libraries.
 
      Predicate `$registered-library?' returns true iff a library named
      `name' is already registered.  `get-registered-library' returns
      the library object associated with `name' (or throws an error if
      no library named `name' is registered).  `$register-library!'
      registers `library' with name `name' (throws an error if `name' is
      already registered.  `$unregister-library!' removes the library
      registered as `name' from the library register (throws an error if
      no such library was registered).
 
      NOTE: This is part of the low level API to libraries, users &
      writers of libraries are encouraged to use `$provide-library!' to
      create & register new libraries.
 
  -- Operative: $provide-library! ($provide-library! name exports . body)
  -- Operative: $import-library! ($import-library! . imports)
      `name' should be as for `register-library!' and not already
      registered.  `exports' should be a list of `(#:export
      <export-spec> ...)'. Where `<export spec>' is either:
         * `symbol'
 
         * `(#:rename internal-symbol external-symbol)'
 
      A lone symbol has the same semantics as the pair with that symbol
      in both internal and external positions.  No symbol can appear
      more than once as external.  `body' should be an acyclic list of
      expressions.  `imports' should be a list like `(<import-spec>
      ...)' where `<import-spec>' is either
         * `<name>'
 
         * `(#:only <import-spec> symbol ...)'
 
         * `(#:except <import-spec> symbol ...)'
 
         * `(#:prefix <import-spec> symbol)'
 
         * `(#:rename <import-spec> (orig-symbol new-symbol) ...)'
 
      These two operatives conform the higher level API for klisp
      libraries.  They are what most users of klisp (both writers and
      users of libraries) will use.
 
      Operative `$provide-library!' creates and register a library with
      name `name' and exported symbols obtained from the `exports' list
      and values prepared by the `body'.  First a child of the dynamic
      environment is created.  Then, `body' is evaluated sequentially as
      if by `$sequence' in that environment.  Next a new library is
      created with a list of exported bindings that use the external
      symbols in `exports' as names and the values bound by the
      corresponding internal symbols in the created environment, as
      values.  If a lone symbol is used in `exports' it is used both as
      internal and external symbol for that binding.  Lastly, the new
      library object is registered as `name'.  This mechanism more or
      less follows the idea of operative `$provide!' from the Kernel
      Report, but it also allows for renaming.
 
      Operative `$import-library!' imports to the current environment
      any combination of bindings from any number of named libraries,
      while allowing renaming of said bindings.  It can be used in any
      context, as any other Kernel expression.  `$import-library!' looks
      for the named libraries and then extracts & renames the specified
      bindings according to each `<import-spec>' and defines them (in
      the sense of `$define!'  and `$set!') in the current dynamic
      environment.  The set of bindings to import are generated in a
      recursive manner.  This allows a great deal of control of the
      imported bindings and their names.  The semantics for the set of
      bindings generated by the various `<import-spec>'s are as follows:
         * `<name>': All bindings from library `name'.
 
         * `(#:only <import-spec> symbol ...)': Only the named bindings
           from the set of bindings in `<import-spec>'.
 
         * `(#:except <import-spec> symbol ...)': All bindings from the
           set in `<import-spec>' except those named in the list.
 
         * `(#:prefix <import-spec> symbol)': All bindings from the set
           in `<import-spec>' but renamed by prefixing each one with the
           specified prefix `symbol'.
 
         * `(#:rename <import-spec> (orig-symbol new-symbol) ...)': All
           bindings from the set in `<import-spec>' but renaming all
           `orig-symbol' to the corresponding `new-symbol'.
 
      If two values are tried to be imported with the same name, they are
      checked for `eq?'-ness, if they are deemed `eq?' to each other
      they are imported, otherwise `$import-library!' throws an error.
      This helps catch name collisions while allowing to reexport
      bindings from used libraries without conflict.
 
 
 File: klisp.info,  Node: System,  Next: Alphabetical Index,  Prev: Libraries,  Up: Top
 
 22 System
 *********
 
 Module System contains some useful features for interacting with the
 host environment.
 
    SOURCE NOTE: most of these come from r7rs.
 
  -- Applicative: get-current-second (get-current-second)
      Applicative `get-current-second' returns the number of seconds
      elapsed since the UNIX/POSIX epoch (that is midnight January 1st,
      1970, UTC).
 
      NOTE: r7rs specifies TAI seconds, but for now we are sticking to
      POSIX here.
 
  -- Applicative: get-current-jiffies (get-current-jiffies)
      Applicative `get-current-jiffies' returns the number of jiffies
      (fractions of a second) elapsed since an arbitrary epoch that may
      change in each run of the klisp interpreter.  Applicative
      `get-jiffies-per-second' can be used to determine which fraction
      of a second a jiffy represents.
 
  -- Applicative: get-jiffies-per-second (get-jiffies-per-second)
      Applicative `get-jiffies-per-second' returns a constant
      representing the number of jiffies that correspond to one second.
 
  -- Applicative: file-exists (file-exists string)
      Predicate `file-exists?' checks to see if a file named `string'
      exists.
 
  -- Applicative: delete-file (delete-file string)
      `string' should be the name/path for an existing file.
 
      Applicative `delete-file' deletes the file named `string'.  If it
      doesn't exists or can't be deleted, an error is signaled. The
      result returned by `delete-file' is inert.
 
  -- Applicative: rename-file (rename-file string1 string2)
      `string1' should be the name/path for an existing file, `string2'
      should be the name/path for a non existing file.
 
      Applicative `rename-file' renames the file named `string1' to
      `string2'. If the file doesn't exists or can't be renamed for any
      reason, an error is signaled. The result returned by `rename-file'
      is inert.
 
      SOURCE NOTE: this is missing from r7rs, it is taken from C, being
      quite similar to `delete-file'.
 
  -- Applicative: get-script-arguments (get-script-arguments)
  -- Applicative: get-interpreter-arguments (get-interpreter-arguments)
      These applicatives return respectively the script and interpreter
      arguments.  The script arguments are a list of the arguments
      passed to the klisp interpreter starting from (and including) the
      script name.  The interpreter arguments are the complete list of
      arguments passed to the klisp interpreter (including the name of
      the interpreter as the first item in the list, the interpreter
      flag arguments and the script name and arguments.
 
  -- Applicative: defined-environment-variable?
           (defined-environment-variable? string)
      Predicate `defined-environment-variable?' returns true iff
      `string' represents a defined envrionment variable.
 
  -- Applicative: get-environment-variable (get-environment-variable
           string)
      Applicative `get-environment-variable' returns the value of the
      environment variable represented by `string'.  If `string' doesn't
      represent a defined environment variable an error is signaled.
 
  -- Applicative: get-environment-variables (get-environment-variables)
      Applicative `get-environment-variable' returns an alist
      representing the defined environment variables and their values.
      The alist is a list of `(variable . value)' entries, where both
      `variable' and `value' are strings.
 
 
 File: klisp.info,  Node: Alphabetical Index,  Next: (dir),  Prev: System,  Up: Top
 
 Index
 *****
 
 
 * Menu:
 
 * $and?:                                 Booleans.            (line  28)
 * $bindings->environment:                Environments.        (line 175)
 * $binds?:                               Environments.        (line 108)
 * $cond:                                 Control.             (line  32)
 * $define!:                              Environments.        (line  49)
 * $delay:                                Promises.            (line  79)
 * $get-registered-library:               Libraries.           (line  80)
 * $if:                                   Control.             (line  15)
 * $import!:                              Environments.        (line 217)
 * $import-library!:                      Libraries.           (line 104)
 * $lambda:                               Combiners.           (line  76)
 * $lazy:                                 Promises.            (line  43)
 * $let:                                  Environments.        (line  89)
 * $let*:                                 Environments.        (line 124)
 * $let-redirect:                         Environments.        (line 153)
 * $let-safe:                             Environments.        (line 161)
 * $let/cc:                               Continuations.       (line 143)
 * $letrec:                               Environments.        (line 137)
 * $letrec*:                              Environments.        (line 144)
 * $or?:                                  Booleans.            (line  42)
 * $provide!:                             Environments.        (line 201)
 * $provide-library!:                     Libraries.           (line 103)
 * $register-library!:                    Libraries.           (line  81)
 * $registered-library?:                  Libraries.           (line  79)
 * $remote-eval:                          Environments.        (line 169)
 * $sequence:                             Control.             (line  23)
 * $set!:                                 Environments.        (line 192)
 * $unless:                               Control.             (line  68)
 * $unregister-library!:                  Libraries.           (line  82)
 * $vau:                                  Combiners.           (line  26)
 * $when:                                 Control.             (line  67)
 * *:                                     Numbers.             (line 136)
 * +:                                     Numbers.             (line 124)
 * -:                                     Numbers.             (line 152)
 * /:                                     Numbers.             (line 321)
 * <=?:                                   Numbers.             (line 116)
 * <?:                                    Numbers.             (line 115)
 * =?:                                    Numbers.             (line 110)
 * >=?:                                   Numbers.             (line 118)
 * >?:                                    Numbers.             (line 117)
 * abs:                                   Numbers.             (line 208)
 * acos:                                  Numbers.             (line 408)
 * and?:                                  Booleans.            (line  20)
 * append:                                Pairs and lists.     (line 246)
 * append!:                               Pairs and lists.     (line 348)
 * applicative descriptions:              A Sample Applicative Description.
                                                               (line   6)
 * applicative?:                          Combiners.           (line  21)
 * applicatives:                          Combiners.           (line   6)
 * apply:                                 Combiners.           (line  83)
 * apply-continuation:                    Continuations.       (line 134)
 * asin:                                  Numbers.             (line 407)
 * assoc:                                 Pairs and lists.     (line 290)
 * assq:                                  Pairs and lists.     (line 375)
 * atan:                                  Numbers.             (line 409)
 * binary-port?:                          Ports.               (line  43)
 * boolean?:                              Booleans.            (line  12)
 * booleans:                              Booleans.            (line   6)
 * bytevector:                            Bytevectors.         (line  58)
 * bytevector->immutable-bytevector:      Bytevectors.         (line 119)
 * bytevector->list:                      Bytevectors.         (line  62)
 * bytevector->string:                    Strings.             (line 135)
 * bytevector->vector <1>:                Bytevectors.         (line  73)
 * bytevector->vector:                    Vectors.             (line  72)
 * bytevector-copy:                       Bytevectors.         (line  69)
 * bytevector-copy!:                      Bytevectors.         (line  82)
 * bytevector-copy-partial:               Bytevectors.         (line  91)
 * bytevector-copy-partial!:              Bytevectors.         (line 101)
 * bytevector-fill!:                      Bytevectors.         (line 112)
 * bytevector-for-each:                   Control.             (line  56)
 * bytevector-length:                     Bytevectors.         (line  43)
 * bytevector-map:                        Combiners.           (line 123)
 * bytevector-port?:                      Ports.               (line  56)
 * bytevector-ref:                        Bytevectors.         (line  46)
 * bytevector-set!:                       Bytevectors.         (line  52)
 * bytevector?:                           Bytevectors.         (line  25)
 * Bytevectors:                           Bytevectors.         (line   6)
 * caaaar:                                Pairs and lists.     (line 111)
 * caaadr:                                Pairs and lists.     (line 112)
 * caaar:                                 Pairs and lists.     (line 103)
 * caadar:                                Pairs and lists.     (line 113)
 * caaddr:                                Pairs and lists.     (line 114)
 * caadr:                                 Pairs and lists.     (line 104)
 * caar:                                  Pairs and lists.     (line  99)
 * cadaar:                                Pairs and lists.     (line 115)
 * cadadr:                                Pairs and lists.     (line 116)
 * cadar:                                 Pairs and lists.     (line 105)
 * caddar:                                Pairs and lists.     (line 117)
 * cadddr:                                Pairs and lists.     (line 118)
 * caddr:                                 Pairs and lists.     (line 106)
 * cadr:                                  Pairs and lists.     (line 100)
 * call-with-input-file:                  Ports.               (line 405)
 * call-with-output-file:                 Ports.               (line 407)
 * call/cc:                               Continuations.       (line  43)
 * car:                                   Pairs and lists.     (line  95)
 * cdaaar:                                Pairs and lists.     (line 119)
 * cdaadr:                                Pairs and lists.     (line 120)
 * cdaar:                                 Pairs and lists.     (line 107)
 * cdadar:                                Pairs and lists.     (line 121)
 * cdaddr:                                Pairs and lists.     (line 122)
 * cdadr:                                 Pairs and lists.     (line 108)
 * cdar:                                  Pairs and lists.     (line 101)
 * cddaar:                                Pairs and lists.     (line 123)
 * cddadr:                                Pairs and lists.     (line 124)
 * cddar:                                 Pairs and lists.     (line 109)
 * cdddar:                                Pairs and lists.     (line 125)
 * cddddr:                                Pairs and lists.     (line 126)
 * cdddr:                                 Pairs and lists.     (line 110)
 * cddr:                                  Pairs and lists.     (line 102)
 * cdr:                                   Pairs and lists.     (line  96)
 * ceiling:                               Numbers.             (line 340)
 * char->digit:                           Characters.          (line  91)
 * char->integer:                         Characters.          (line  73)
 * char-alphabetic?:                      Characters.          (line  43)
 * char-ci<=?:                            Characters.          (line  37)
 * char-ci<?:                             Characters.          (line  36)
 * char-ci=?:                             Characters.          (line  35)
 * char-ci>=?:                            Characters.          (line  39)
 * char-ci>?:                             Characters.          (line  38)
 * char-digit?:                           Characters.          (line  80)
 * char-downcase:                         Characters.          (line  59)
 * char-foldcase:                         Characters.          (line  61)
 * char-lower-case?:                      Characters.          (line  50)
 * char-numeric?:                         Characters.          (line  44)
 * char-ready?:                           Ports.               (line 335)
 * char-title-case?:                      Characters.          (line  51)
 * char-titlecase:                        Characters.          (line  60)
 * char-upcase:                           Characters.          (line  58)
 * char-upper-case?:                      Characters.          (line  49)
 * char-whitespace?:                      Characters.          (line  45)
 * char<=?:                               Characters.          (line  29)
 * char<?:                                Characters.          (line  28)
 * char=?:                                Characters.          (line  27)
 * char>=?:                               Characters.          (line  31)
 * char>?:                                Characters.          (line  30)
 * char?:                                 Characters.          (line  23)
 * characters:                            Characters.          (line   6)
 * close-input-file:                      Ports.               (line 156)
 * close-input-port:                      Ports.               (line 170)
 * close-output-file:                     Ports.               (line 157)
 * close-output-port:                     Ports.               (line 171)
 * close-port:                            Ports.               (line 172)
 * combiner?:                             Combiners.           (line 134)
 * combiners:                             Combiners.           (line   6)
 * cons:                                  Pairs and lists.     (line  45)
 * continuation->applicative:             Continuations.       (line  95)
 * continuation?:                         Continuations.       (line  38)
 * continuations:                         Continuations.       (line   6)
 * control:                               Control.             (line   6)
 * copy-es:                               Pairs and lists.     (line 363)
 * copy-es-immutable!:                    Pairs and lists.     (line  59)
 * cos:                                   Numbers.             (line 405)
 * countable-list?:                       Pairs and lists.     (line 307)
 * defined-environment-variable?:         System.              (line  65)
 * delete-file:                           System.              (line  35)
 * denominator:                           Numbers.             (line 330)
 * description format:                    Format of Descriptions.
                                                               (line   6)
 * digit->char:                           Characters.          (line  92)
 * display:                               Ports.               (line 262)
 * div:                                   Numbers.             (line 164)
 * div-and-mod:                           Numbers.             (line 166)
 * div0:                                  Numbers.             (line 178)
 * div0-and-mod0:                         Numbers.             (line 180)
 * documentation notation:                Evaluation Notation. (line   6)
 * empty list:                            Pairs and lists.     (line   6)
 * encapsulations:                        Encapsulations.      (line   6)
 * encycle!:                              Pairs and lists.     (line 196)
 * environment?:                          Environments.        (line  23)
 * environments:                          Environments.        (line   6)
 * eof-object?:                           Ports.               (line 242)
 * eq?:                                   Equivalence.         (line  12)
 * equal?:                                Equivalence.         (line  16)
 * equivalence:                           Equivalence.         (line   6)
 * error:                                 Errors.              (line  30)
 * error message notation:                Error Messages.      (line   6)
 * error-continuation:                    Continuations.       (line 110)
 * error-object-irritants:                Errors.              (line  44)
 * error-object-message:                  Errors.              (line  41)
 * error-object?:                         Errors.              (line  26)
 * Errors:                                Errors.              (line   6)
 * eval:                                  Environments.        (line  32)
 * eval-string:                           Environments.        (line 183)
 * evaluation notation:                   Evaluation Notation. (line   6)
 * even?:                                 Numbers.             (line 201)
 * exact-integer?:                        Numbers.             (line  66)
 * exact?:                                Numbers.             (line  94)
 * exit:                                  Continuations.       (line 162)
 * exp:                                   Numbers.             (line 402)
 * expt:                                  Numbers.             (line 397)
 * extend-continuation:                   Continuations.       (line  50)
 * file-exists:                           System.              (line  31)
 * file-port?:                            Ports.               (line  54)
 * filter:                                Pairs and lists.     (line 277)
 * find-required-filename:                Ports.               (line 467)
 * finite-list?:                          Pairs and lists.     (line 303)
 * finite?:                               Numbers.             (line  90)
 * floor:                                 Numbers.             (line 339)
 * flush-output-port:                     Ports.               (line 285)
 * fonts:                                 Some Terms.          (line  13)
 * foo:                                   A Sample Applicative Description.
                                                               (line  15)
 * for-each:                              Control.             (line  42)
 * force:                                 Promises.            (line  35)
 * gcd:                                   Numbers.             (line 222)
 * get-current-environment:               Environments.        (line 114)
 * get-current-error-port:                Ports.               (line  91)
 * get-current-input-port:                Ports.               (line  89)
 * get-current-jiffies:                   System.              (line  20)
 * get-current-output-port:               Ports.               (line  90)
 * get-current-second:                    System.              (line  12)
 * get-environment-variable:              System.              (line  70)
 * get-environment-variables:             System.              (line  75)
 * get-interpreter-arguments:             System.              (line  55)
 * get-jiffies-per-second:                System.              (line  27)
 * get-library-environment:               Libraries.           (line  69)
 * get-library-export-list:               Libraries.           (line  67)
 * get-list-metrics:                      Pairs and lists.     (line 161)
 * get-module:                            Ports.               (line 498)
 * get-output-bytevector:                 Ports.               (line 195)
 * get-output-string:                     Ports.               (line 186)
 * get-real-exact-bounds:                 Numbers.             (line 248)
 * get-real-exact-primary:                Numbers.             (line 267)
 * get-real-internal-bounds:              Numbers.             (line 247)
 * get-real-internal-primary:             Numbers.             (line 266)
 * get-script-arguments:                  System.              (line  54)
 * get-string-arithmetic:                 Numbers.             (line 314)
 * guard-continuation:                    Continuations.       (line  63)
 * guard-dynamic-extent:                  Continuations.       (line 156)
 * ignore:                                Environments.        (line   6)
 * ignore?:                               Environments.        (line  28)
 * immutable-bytevector?:                 Bytevectors.         (line  30)
 * immutable-pair?:                       Pairs and lists.     (line  35)
 * immutable-string?:                     Strings.             (line  51)
 * immutable-vector?:                     Vectors.             (line  30)
 * inert:                                 Control.             (line   6)
 * inert?:                                Control.             (line  11)
 * inexact?:                              Numbers.             (line  98)
 * input-port?:                           Ports.               (line  32)
 * integer->char:                         Characters.          (line  74)
 * integer?:                              Numbers.             (line  61)
 * interpreter:                           Interpreter.         (line   6)
 * Kernel history:                        Kernel History.      (line   6)
 * keyed dynamic variables:               Keyed Variables.     (line  15)
 * keyed static variables:                Keyed Variables.     (line  40)
 * keyed variables:                       Keyed Variables.     (line   6)
 * lcm:                                   Numbers.             (line 221)
 * length:                                Pairs and lists.     (line 229)
 * libraries:                             Libraries.           (line   6)
 * library?:                              Libraries.           (line  47)
 * list:                                  Pairs and lists.     (line  82)
 * list*:                                 Pairs and lists.     (line  88)
 * list->bytevector:                      Bytevectors.         (line  63)
 * list->string:                          Strings.             (line 131)
 * list->vector:                          Vectors.             (line  63)
 * list-copy:                             Pairs and lists.     (line 142)
 * list-neighbors:                        Pairs and lists.     (line 266)
 * list-ref:                              Pairs and lists.     (line 236)
 * list-tail:                             Pairs and lists.     (line 185)
 * lists:                                 Pairs and lists.     (line   6)
 * load:                                  Ports.               (line 417)
 * log:                                   Numbers.             (line 403)
 * make-bytevector:                       Bytevectors.         (line  37)
 * make-encapsulation-type:               Encapsulations.      (line  12)
 * make-environment:                      Environments.        (line  36)
 * make-inexact:                          Numbers.             (line 285)
 * make-kernel-standard-environment:      Environments.        (line 119)
 * make-keyed-dynamic-variable:           Keyed Variables.     (line  21)
 * make-keyed-static-variable:            Keyed Variables.     (line  44)
 * make-library:                          Libraries.           (line  55)
 * make-list:                             Pairs and lists.     (line 133)
 * make-string:                           Strings.             (line  78)
 * make-vector:                           Vectors.             (line  37)
 * map <1>:                               Combiners.           (line  96)
 * map:                                   Pairs and lists.     (line 207)
 * max:                                   Numbers.             (line 213)
 * member?:                               Pairs and lists.     (line 297)
 * memoize:                               Promises.            (line  74)
 * memq?:                                 Pairs and lists.     (line 380)
 * min:                                   Numbers.             (line 214)
 * mod:                                   Numbers.             (line 165)
 * mod0:                                  Numbers.             (line 179)
 * mutable-bytevector?:                   Bytevectors.         (line  31)
 * mutable-pair?:                         Pairs and lists.     (line  36)
 * mutable-string?:                       Strings.             (line  52)
 * mutable-vector?:                       Vectors.             (line  31)
 * negative?:                             Numbers.             (line 193)
 * newline:                               Ports.               (line 251)
 * nil:                                   Pairs and lists.     (line   6)
 * not?:                                  Booleans.            (line  16)
 * null?:                                 Pairs and lists.     (line  31)
 * number->string:                        Numbers.             (line 439)
 * number?:                               Numbers.             (line  57)
 * numbers:                               Numbers.             (line   6)
 * numerator:                             Numbers.             (line 329)
 * object descriptions:                   A Sample Applicative Description.
                                                               (line   6)
 * odd?:                                  Numbers.             (line 200)
 * open-binary-input-file:                Ports.               (line  99)
 * open-binary-output-file:               Ports.               (line 115)
 * open-input-bytevector:                 Ports.               (line 136)
 * open-input-file:                       Ports.               (line  98)
 * open-input-string:                     Ports.               (line 134)
 * open-output-bytevector:                Ports.               (line 149)
 * open-output-file:                      Ports.               (line 113)
 * open-output-string:                    Ports.               (line 142)
 * operative descriptions:                A Sample Applicative Description.
                                                               (line   6)
 * operative?:                            Combiners.           (line  16)
 * operatives:                            Combiners.           (line   6)
 * or?:                                   Booleans.            (line  24)
 * output-port?:                          Ports.               (line  33)
 * pair?:                                 Pairs and lists.     (line  27)
 * pairs:                                 Pairs and lists.     (line   6)
 * peek-char:                             Ports.               (line 321)
 * peek-u8:                               Ports.               (line 375)
 * port-open?:                            Ports.               (line  67)
 * port?:                                 Ports.               (line  28)
 * ports:                                 Ports.               (line   6)
 * positive?:                             Numbers.             (line 192)
 * printing notation:                     Printing Notation.   (line   6)
 * promise?:                              Promises.            (line  31)
 * promises:                              Promises.            (line   6)
 * raise:                                 Errors.              (line  36)
 * rational?:                             Numbers.             (line  81)
 * rationalize:                           Numbers.             (line 355)
 * read:                                  Ports.               (line 204)
 * read-char:                             Ports.               (line 309)
 * read-line:                             Ports.               (line 275)
 * read-u8:                               Ports.               (line 362)
 * real->exact:                           Numbers.             (line 301)
 * real->inexact:                         Numbers.             (line 300)
 * real?:                                 Numbers.             (line  86)
 * reduce:                                Pairs and lists.     (line 312)
 * register-requirement!:                 Ports.               (line 464)
 * registered-requirement?:               Ports.               (line 463)
 * rename-file:                           System.              (line  42)
 * require:                               Ports.               (line 440)
 * reverse:                               Pairs and lists.     (line 150)
 * robust?:                               Numbers.             (line 102)
 * root-continuation:                     Continuations.       (line 104)
 * round:                                 Numbers.             (line 342)
 * set-car!:                              Pairs and lists.     (line  51)
 * set-cdr!:                              Pairs and lists.     (line  52)
 * simplest-rational:                     Numbers.             (line 356)
 * sin:                                   Numbers.             (line 404)
 * sqrt:                                  Numbers.             (line 390)
 * string:                                Strings.             (line  84)
 * string->bytevector:                    Strings.             (line 134)
 * string->immutable-string:              Strings.             (line 125)
 * string->list:                          Strings.             (line 130)
 * string->number:                        Numbers.             (line 420)
 * string->symbol:                        Symbols.             (line  26)
 * string->vector <1>:                    Vectors.             (line  80)
 * string->vector:                        Strings.             (line 132)
 * string-append:                         Strings.             (line 116)
 * string-ci<=?:                          Strings.             (line  72)
 * string-ci<?:                           Strings.             (line  71)
 * string-ci=?:                           Strings.             (line  70)
 * string-ci>=?:                          Strings.             (line  74)
 * string-ci>?:                           Strings.             (line  73)
 * string-copy:                           Strings.             (line 120)
 * string-downcase:                       Strings.             (line 141)
 * string-fill!:                          Strings.             (line 102)
 * string-foldcase:                       Strings.             (line 143)
 * string-for-each:                       Control.             (line  53)
 * string-length:                         Strings.             (line  88)
 * string-map:                            Combiners.           (line 120)
 * string-port?:                          Ports.               (line  55)
 * string-ref:                            Strings.             (line  91)
 * string-set!:                           Strings.             (line  97)
 * string-titlecase:                      Strings.             (line 142)
 * string-upcase:                         Strings.             (line 140)
 * string<=?:                             Strings.             (line  64)
 * string<?:                              Strings.             (line  63)
 * string=?:                              Strings.             (line  62)
 * string>=?:                             Strings.             (line  66)
 * string>?:                              Strings.             (line  65)
 * string?:                               Strings.             (line  47)
 * strings:                               Strings.             (line   6)
 * substring:                             Strings.             (line 107)
 * symbol->string:                        Symbols.             (line  22)
 * symbol?:                               Symbols.             (line  18)
 * symbols:                               Symbols.             (line   6)
 * system:                                System.              (line   6)
 * tan:                                   Numbers.             (line 406)
 * textual-port?:                         Ports.               (line  42)
 * truncate:                              Numbers.             (line 341)
 * u8-ready?:                             Ports.               (line 390)
 * u8?:                                   Numbers.             (line  73)
 * undefined?:                            Numbers.             (line 106)
 * unregister-requirement!:               Ports.               (line 466)
 * unwrap:                                Combiners.           (line  72)
 * vector:                                Vectors.             (line  58)
 * vector->bytevector <1>:                Bytevectors.         (line  74)
 * vector->bytevector:                    Vectors.             (line  71)
 * vector->immutable-vector:              Vectors.             (line 121)
 * vector->list:                          Vectors.             (line  62)
 * vector->string <1>:                    Vectors.             (line  79)
 * vector->string:                        Strings.             (line 133)
 * vector-copy:                           Vectors.             (line  67)
 * vector-copy!:                          Vectors.             (line  86)
 * vector-copy-partial:                   Vectors.             (line  94)
 * vector-copy-partial!:                  Vectors.             (line 104)
 * vector-fill!:                          Vectors.             (line 115)
 * vector-for-each:                       Control.             (line  54)
 * vector-length:                         Vectors.             (line  43)
 * vector-map:                            Combiners.           (line 121)
 * vector-ref:                            Vectors.             (line  46)
 * vector-set!:                           Vectors.             (line  52)
 * vector?:                               Vectors.             (line  26)
 * Vectors:                               Vectors.             (line   6)
 * with-error-to-file:                    Ports.               (line  76)
 * with-input-from-file:                  Ports.               (line  73)
 * with-output-to-file:                   Ports.               (line  75)
 * with-strict-arithmetic:                Numbers.             (line 313)
 * wrap:                                  Combiners.           (line  68)
 * write:                                 Ports.               (line 218)
 * write-char:                            Ports.               (line 297)
 * write-simple:                          Ports.               (line 236)
 * write-u8:                              Ports.               (line 349)
 * zero?:                                 Numbers.             (line 158)
 
 
 
 Tag Table:
 Node: Top708
 Node: License2942
 Node: Introduction4629
 Node: Caveats7562
 Node: Kernel History8348
 Node: Conventions9793
 Node: Some Terms10464
 Node: Evaluation Notation11135
 Node: Printing Notation12156
 Node: Error Messages12632
 Node: Format of Descriptions13280
 Node: A Sample Applicative Description13844
 Node: Acknowledgements15607
 Node: Interpreter15993
 Ref: Command Line Options18293
 Ref: Interpreter Exit Status19227
 Node: Booleans20455
 Node: Equivalence23132
 Node: Symbols23925
 Node: Control25555
 Node: Pairs and lists29646
 Node: Environments48526
 Node: Combiners59199
 Node: Continuations65853
 Node: Encapsulations74396
 Node: Promises75849
 Node: Keyed Variables80004
 Node: Numbers82775
 Node: Strings105229
 Node: Characters112502
 Node: Ports117148
 Node: Vectors140847
 Node: Bytevectors146601
 Node: Errors152420
 Node: Libraries154435
 Node: System163195
 Node: Alphabetical Index166693
 
 End Tag Table