klisp

an open source interpreter for the Kernel Programming Language.
git clone http://git.hanabi.in/repos/klisp.git
Log | Files | Refs | README

klisp.info (198574B)


      1 This is ../klisp.info, produced by makeinfo version 4.13 from
      2 klisp.texi.
      3 
      4 This file documents klisp.
      5 
      6    This is edition 0.3 of the klisp Reference Manual, for klisp version
      7 0.3.
      8 
      9    Copyright (C) 2011-2012 Andres Navarro
     10 
     11    Permission is granted to copy and distribute this manual, in whole or
     12 in part, without fee.  Please note that most text of this manual is
     13 derived from `The Revised(-1) Report on the Kernel Programming
     14 Language' by John N. Shutt.  There's a clause in that reports, under
     15 the header "Permission to copy this report", that reads:
     16 
     17      This report is intended to belong to the programming community,
     18      and so permission is granted to copy it in whole or in part
     19      without fee.
     20 
     21 
     22 File: klisp.info,  Node: Top,  Next: License,  Prev: (dir),  Up: (dir)
     23 
     24    This Info file contains edition 0.3 of the klisp Reference Manual,
     25 corresponding to klisp version 0.3.
     26 
     27    Copyright (C) 2011-2012 Andres Navarro
     28 
     29    Permission is granted to copy and distribute this manual, in whole or
     30 in part, without fee.  Please note that most text of this manual is
     31 derived from `The Revised(-1) Report on the Kernel Programming
     32 Language' by John N. Shutt.  There's a clause in that reports, under
     33 the header "Permission to copy this report", that reads:
     34 
     35      This report is intended to belong to the programming community,
     36      and so permission is granted to copy it in whole or in part
     37      without fee.
     38 
     39 * Menu:
     40 
     41 * License::                 Conditions for copying and changing klisp.
     42 * Introduction::            Introduction and conventions used.
     43 * Interpreter::             The klisp stand-alone interpreter
     44 * Booleans::                Booleans module features.
     45 * Equivalence::             Equivalence (under & up to) mutation modules features.
     46 * Symbols::                 Symbols module features.
     47 * Control::                 Control module features.
     48 * Pairs and lists::         Pairs and lists and Pair mutation modules features.
     49 * Environments::            Environments and Environment mutation modules features.
     50 * Combiners::               Combiners module features.
     51 * Continuations::           Continuations module features.
     52 * Encapsulations::          Encapsulations module features.
     53 * Promises::                Promises module features.
     54 * Keyed Variables::         Keyed (dynamic & static) variables module features.
     55 * Numbers::                 Numbers module features.
     56 * Strings::                 Strings module features.
     57 * Characters::              Characters module features.
     58 * Ports::                   Ports module features.
     59 * Vectors::                 Vectors module features.
     60 * Bytevectors::             Bytevectors module features.
     61 * Errors::                  Errors module features.
     62 * Libraries::               Libraries module features.
     63 * System::                  System module features.
     64 * Alphabetical Index::      Index including concepts, functions, variables,
     65                               and other terms.
     66 
     67 
     68 File: klisp.info,  Node: License,  Next: Introduction,  Prev: Top,  Up: Top
     69 
     70    klisp is licensed under the terms of the MIT license reproduced
     71 below.  This means that klisp is free software and can be used for both
     72 academic and commercial purposes at absolutely no cost.  The two
     73 projects whose code klisp uses, Lua & IMath, are also distributed under
     74 the MIT license.
     75 
     76    * klisp Parts: Copyright (C) 2011-2012 Andres Navarro, Oto Havle.
     77 
     78    * Lua Parts: Copyright (C) 1994-2010 Lua.org, PUC-Rio.
     79 
     80    * IMath Parts: Copyright (C) 2002-2007 Michael J. Fromberger.
     81 
     82    * srfi-78: Copyright (C) 2005-2006 Sebastian Egner.
     83 
     84 MIT/X11 License
     85 ***************
     86 
     87 Permission is hereby granted, free of charge, to any person obtaining a
     88 copy of this software and associated documentation files (the
     89 "Software"), to deal in the Software without restriction, including
     90 without limitation the rights to use, copy, modify, merge, publish,
     91 distribute, sublicense, and/or sell copies of the Software, and to
     92 permit persons to whom the Software is furnished to do so, subject to
     93 the following conditions:
     94 
     95    The above copyright notice and this permission notice shall be
     96 included in all copies or substantial portions of the Software.
     97 
     98    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
     99 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    100 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    101 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    102 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    103 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    104 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    105 
    106 
    107 File: klisp.info,  Node: Introduction,  Next: Interpreter,  Prev: License,  Up: Top
    108 
    109 1 Introduction
    110 **************
    111 
    112 klisp is an open source interpreter for the Kernel Programming
    113 Language.  It aims at being comprehensive and robust as specified in
    114 the `Revised(-1) Report on the Kernel Programming Language', but that
    115 probably won't happen for some time.  It is written in C99 under the
    116 MIT license.  It draws heavily from the Lua interpreter source code &
    117 file structure.  It uses the IMath library for arbitrary sized integers
    118 and rationals.
    119 
    120    The Kernel programming language is a statically scoped and properly
    121 tail-recursive dialect of Lisp, descended from Scheme.  It is designed
    122 to be simpler and more general than Scheme, with an exceptionally
    123 clear, simple, and versatile semantics, only one way to form compound
    124 expressions, and no inessential restrictions on the power of that one
    125 compound form.  Imperative, functional, and message-passing programming
    126 styles (to name a few) may be conveniently expressed in Kernel.
    127 
    128    An important property of Kernel is that all manipulable entities in
    129 Kernel are first-class objects.  In particular, Kernel has no
    130 second-class combiners; instead, the roles of special forms and macros
    131 are subsumed by operatives, which are first-class, statically scoped
    132 combiners that act directly on their unevaluated operands.  Kernel also
    133 has a second type of combiners, applicatives, which act on their evalu-
    134 ated arguments.  Applicatives are roughly equivalent to Scheme
    135 procedures.  However, an applicative is nothing more than a wrapper to
    136 induce operand evaluation, around an underlying operative (or, in
    137 principle, around another applicative, though that isn’t usually done);
    138 applicatives themselves are mere facilitators to computation.
    139 
    140    You can read more about Kernel at
    141 `http://web.cs.wpi.edu/~jshutt/kernel.html'.
    142 
    143    klisp is freely available for both academic and commercial purposes.
    144 See LICENSE for details.  it can be downloaded at
    145 `https://bitbucket.org/AndresNavarro/klisp'
    146 
    147    klisp is developed by Andres Navarro, a Computer Science
    148 undergraduate at Buenos Aires University (UBA).  You can reach him at
    149 <canavarro82@gmail.com>. Significant contributions are being done by
    150 Oto Havle, his fork is at `https://bitbucket.org/havleoto/klisp'.
    151 
    152    This manual describes klisp version 0.3, presuming some familiarity
    153 with the Lisp family of languages in general, and with the Kernel
    154 Programming Language in particular.  There are frequent references to
    155 the Kernel Programming Language Report.  Unlike in the report, no
    156 rationale is provided for any feature, only a description of the
    157 implemented functionality.
    158 
    159    This is edition 0.3.
    160 
    161 * Menu:
    162 
    163 * Caveats::                Flaws and a request for help.
    164 * Kernel History::         Kernel is descended from Scheme.
    165 * Conventions::            How the manual is formatted.
    166 * Acknowledgements::       Contributions to this manual.
    167 
    168 
    169 File: klisp.info,  Node: Caveats,  Next: Kernel History,  Prev: Introduction,  Up: Introduction
    170 
    171 1.1 Caveats
    172 ===========
    173 
    174 This is the first draft of this manual.  It will be incomplete for some
    175 time.  It will also evolve, together with klisp and the Kernel
    176 Programming Language, both of which, right now, are in a quite fluid
    177 state.
    178 
    179    The main reference on Kernel is the preliminary report: `Revised(-1)
    180 Report on the Kernel Programming Language'.  Some sections of the
    181 report are still incomplete, so both klisp and this manual will use
    182 specifications from other languages in these sections, trying to follow
    183 the Kernel spirit.  These instances will be documented throughout the
    184 manual.
    185 
    186    Please mail comments and corrections to <canavarro82@gmail.com>.
    187 
    188 
    189       -Andres Navarro
    190 
    191 
    192 File: klisp.info,  Node: Kernel History,  Next: Conventions,  Prev: Caveats,  Up: Introduction
    193 
    194 1.2 Kernel History
    195 ==================
    196 
    197 The Kernel Programming Language is a work in progress.  It is being
    198 developed by John N. Shutt, Ph.D, who created it while studying at the
    199 Worcester Polytechnic Institute (I think about 2002, or so... ASK).  It
    200 is descended from scheme, with the idea that all objects should be
    201 first class values.  In particular, Kernel replaces macros with
    202 operatives (kinda like statically scoped fexprs and fsubrs) and has
    203 first class environments.  Kernel also has the notion of encapsulated
    204 objects which limits the ammount of information an implementation can
    205 share with a Kernel program (e.g. There is no way in Kernel to get the
    206 parents or a complete list of bindings of an environment object).
    207 
    208    The main reference on Kernel is the preliminary report: `Revised(-1)
    209 Report on the Kernel Programming Language'.  Some sections of the
    210 report are still incomplete, so both klisp and this manual will use
    211 specifications from other languages in these sections, trying to follow
    212 the Kernel spirit.  These instances will be documented throughout the
    213 manual.
    214 
    215    You can read all about Kernel at John's homepage at WPI
    216 `http://www.cs.wpi.edu/~jshutt/', including the preliminary report on
    217 the language and his doctoral dissertation which gives a theorethical
    218 frame for fexprs.  You can contact him at <jshutt@cs.wpi.edu>.
    219 
    220 
    221 File: klisp.info,  Node: Conventions,  Next: Acknowledgements,  Prev: Kernel History,  Up: Introduction
    222 
    223 1.3 Conventions
    224 ===============
    225 
    226 This section explains the notational conventions that are used in this
    227 manual.  You may want to skip this section and refer back to it later.
    228 
    229 * Menu:
    230 
    231 * Some Terms::               Explanation of terms we use in this manual.
    232 * Evaluation Notation::      The format we use for examples of evaluation.
    233 * Printing Notation::        The format we use for examples that print output.
    234 * Error Messages::           The format we use for examples of errors.
    235 * Format of Descriptions::   Notation for describing functions, variables, etc.
    236 
    237 
    238 File: klisp.info,  Node: Some Terms,  Next: Evaluation Notation,  Prev: Conventions,  Up: Conventions
    239 
    240 1.3.1 Some Terms
    241 ----------------
    242 
    243 Throughout this manual, the phrases "the Kernel reader" and "the Kernel
    244 printer" are used to refer to those routines in Lisp that convert
    245 textual representations of Kernel objects into actual objects, and vice
    246 versa.  XXX Printed Representation XXX, for more details.  You, the
    247 person reading this manual, are assumed to be "the programmer" or "the
    248 user".
    249 
    250    Examples of Kernel code appear in this font or form: `(list 1 2 3)'.
    251 Names that represent arguments or metasyntactic variables appear in
    252 this font or form: FIRST-NUMBER.
    253 
    254 
    255 File: klisp.info,  Node: Evaluation Notation,  Next: Printing Notation,  Prev: Some Terms,  Up: Conventions
    256 
    257 1.3.2 Evaluation Notation
    258 -------------------------
    259 
    260 When you evaluate a piece of Kernel code, it produces a result.  In the
    261 examples in this manual, this is indicated with `=>':
    262 
    263      (car (cons 1 2))
    264           => 1
    265 
    266 You can read this as "`(car (cons 1 2))' evaluates to 1".
    267 
    268    The semantics of a language feature are sometimes clarified, or even
    269 defined, in its entry by specifying that two expressions are
    270 equivalent.  This is notated with `=='.  For example, the semantics of
    271 applicative list* can be defined by following equivalences:
    272      (list* arg1) == arg1
    273      (list* arg1 . more-args) == (cons arg1 (list* . more-args))
    274    Notice that in these kind of examples the applicatives or operatives
    275 referred to are the first class values and not the symbols bound to
    276 them in the ground environment.  This definition would hold even if
    277 `cons' or `list*' were redefined in the current dynamic environment.
    278 
    279 
    280 File: klisp.info,  Node: Printing Notation,  Next: Error Messages,  Prev: Evaluation Notation,  Up: Conventions
    281 
    282 1.3.3 Printing Notation
    283 -----------------------
    284 
    285 Many of the examples in this manual print text when they are evaluated.
    286 In examples that print text, the printed text is indicated with `-|'.
    287 The value returned by evaluating the form (here `#t') follows on a
    288 separate line.
    289 
    290      ($sequence (write 1) (write 2) #t)
    291           -| 1
    292           -| 2
    293           => #t
    294 
    295 
    296 File: klisp.info,  Node: Error Messages,  Next: Format of Descriptions,  Prev: Printing Notation,  Up: Conventions
    297 
    298 1.3.4 Error Messages
    299 --------------------
    300 
    301 Some examples cause errors to be signaled.  The report doesn't specify
    302 what objects are passed to the error continuation, but in klisp,
    303 objects passed to the error continuation are encapsulated error objects
    304 that have at least a message and possibly some additional objects and
    305 context informations (such as source code location).  In the examples,
    306 the error message is shown on a line starting with `error-->'.
    307 
    308      (+ 23 #t)
    309      error--> Wrong type argument: (expected number) (#t)
    310 
    311 
    312 File: klisp.info,  Node: Format of Descriptions,  Prev: Error Messages,  Up: Conventions
    313 
    314 1.3.5 Format of Descriptions
    315 ----------------------------
    316 
    317 Applicatives, operatives, and other objects are described in this manual
    318 in a uniform format.  The first line of a description contains the name
    319 of the item followed by its operands or arguments, if any.  The
    320 category--operative, applicative, or whatever--appears at the beginning
    321 of the line.  The description follows on succeeding lines, sometimes
    322 with examples.
    323 
    324 * Menu:
    325 
    326 * A Sample Applicative Description::
    327 
    328 
    329 File: klisp.info,  Node: A Sample Applicative Description,  Prev: Format of Descriptions,  Up: Format of Descriptions
    330 
    331 1.3.5.1 A Sample Applicative Description
    332 ........................................
    333 
    334 In an applicative description, the name of the applicative being
    335 described appears first.  It is followed on the same line by an
    336 applicative combination that includes the name of the applicative and
    337 the arguments, as would appear in a program.  The names used for the
    338 arguments are also used in the body of the description.
    339 
    340    Here is a description of an imaginary applicative `foo':
    341 
    342  -- Applicative: foo (foo integer1 integer2 . rest)
    343      The applicative `foo' subtracts INTEGER1 from INTEGER2, then adds
    344      all the rest of the arguments to the result.
    345 
    346           (foo 1 5 3 9)
    347                => 16
    348 
    349      More generally,
    350 
    351           (foo W X Y...)
    352           ==
    353           (+ (- X W) Y...)
    354 
    355    Any parameter whose name contains the name of a type (e.g., INTEGER,
    356 INTEGER1 or CONTINUATION) is expected to be of that type.  A plural of
    357 a type (such as NUMBERS) often means a list of objects of that type.
    358 Parameters named OBJECT may be of any type.  Additionally parameters
    359 named K, or KN (for any value of N), should be exact, non-negative
    360 integers.  (XXX Types of Lisp Object XXX, for a list of Kernel object
    361 types.)  Parameters with other sorts of names are discussed
    362 specifically in the description of the combiner.  In some sections,
    363 features common to parameters of several combiners are described at the
    364 beginning.
    365 
    366    Operative descriptions have the same format, but the word
    367 `Applicative' is  replaced by `Operative', and `Argument' is replaced
    368 by `Operand'.  Also Operatives always have an environment parameter
    369 (that can be #ignore or a symbol).
    370 
    371 
    372 File: klisp.info,  Node: Acknowledgements,  Prev: Conventions,  Up: Introduction
    373 
    374 1.4 Acknowledgements
    375 ====================
    376 
    377 This manual was written by Andres Navarro.
    378 
    379    The structure and some text for this introductory section were
    380 borrowed from the Elisp Manual by the Free Sofware Foundation.  This
    381 manual also borrows freely from both the Kernel Report and the Scheme
    382 Reports.
    383 
    384 
    385 File: klisp.info,  Node: Interpreter,  Next: Booleans,  Prev: Introduction,  Up: Top
    386 
    387 2 Interpreter
    388 *************
    389 
    390 This section describes the `klisp', a Kernel Programming Language
    391 stand-alone interpreter.
    392 
    393 2.1 Invocation
    394 ==============
    395 
    396 `klisp' is invoked like this:
    397      klisp [options] [script]
    398 
    399 2.2 Description
    400 ===============
    401 
    402 `klisp' is a stand-alone klisp interpreter for the Kernel Programming
    403 Language.  It loads and evaluates Kernel programs in textual source
    404 form.  `klisp' can be used as a batch interpreter and also
    405 interactively.  The given `options' (*note Command Line Options::) are
    406 evaluated and then the klisp program in file `script' is loaded and
    407 evaluated.  All evaluations mentioned, including the initialization
    408 that is described below, take place in the same (initially) standard
    409 environment. All values that result from these evaluation are
    410 discarded, but if the `root-continuation' or `error-continuation' are
    411 passed a value, the evaluation of `options' is interrupted and `klisp'
    412 terminates.  *Note Exit Status: Interpreter Exit Status, for a
    413 description of the exit status in each case.
    414 
    415    The string `script' together with all arguments are available as a
    416 list of strings via the applicative `get-script-arguments'.  If these
    417 arguments contain spaces or other characters special to the shell, then
    418 they should be quoted (but note that the quotes will be removed by the
    419 shell).  The complete command line, including the name of the
    420 interpreter, options, the script, and its arguments are available as a
    421 list of strings via the applicative `get-interpreter-arguments'.
    422 
    423    At the very beginning, before even handling the command line,
    424 `klisp' reads and evaluates the contents of the environment variable
    425 `KLISP_INIT', if it is defined.  To use an init file, just define
    426 `KLISP_INIT' to the following form: `(load "/path/to/init-file")'.
    427 Notice that `klisp' expects exactly one expression in `KLISP_INIT', if
    428 it is defined.  So it is an error to have no expressions or more than
    429 one in `KLISP_INIT'.  The same is true of the argument to the `-e'
    430 option, as both are implemented in terms of `string-eval'.
    431 
    432    In interactive mode, `klisp' prompts the user, reads expressions
    433 from the standard input, and evaluates them as they are read. The
    434 default prompt is "klisp> ".
    435 
    436 2.3 Options
    437 ===========
    438 
    439 Options start with `-' and are described below. You can use `--' to
    440 signal the end of options. If no arguments are given, then `-v'  `-i'
    441 is assumed when the standard input is a terminal; otherwise, `-' is
    442 assumed.  If no SCRIPT, or option `-e' or `-l' is given, `-i' is
    443 assumed.
    444 
    445 `-'
    446      load and execute the standard input as a file, that is, not
    447      interactively, even when the standard input is a terminal.  .TP
    448 
    449 `-e EXPR'
    450      evaluate expression EXPR.  You need to quote EXPR if it contains
    451      spaces, quotes, or other characters special to the shell.
    452 
    453 `-i'
    454      enter interactive mode after SCRIPT is executed.
    455 
    456 `-l NAME'
    457      evaluate `(load "name")' before SCRIPT is executed.  Typically
    458      used to do environment initialization.
    459 
    460 `-r NAME'
    461      evaluate `(require "name")' before SCRIPT is executed. Typically
    462      used to load libraries.
    463 
    464 `-v'
    465      show version and copyright information.
    466 
    467 
    468 2.4 Exit Status
    469 ===============
    470 
    471 If the SCRIPT or `stdin' reach EOF or if there is no SCRIPT,
    472 `EXIT_SUCCESS' is returned.  If the ERROR-CONTINUATION is passed an
    473 object during init, arguments or script evaluation `EXIT_FAILURE' is
    474 returned.  If the ROOT-CONTINUATION is passed an object, `klisp' tries
    475 to convert the value passed to the ROOT-CONTINUATION to an exit status
    476 as follows:
    477 
    478 `integer'
    479      If the value is an integer it is used as exit status.
    480 
    481 `boolean'
    482      If the value is a boolean then `EXIT_SUCCESS' is returned for `#t'
    483      and `EXIT_FAILURE' for `#f'.
    484 
    485 `inert'
    486      If the value is inert, then `EXIT_SUCCESS' is returned.
    487 
    488 `else'
    489      In any other case `EXIT_FAILURE' is returned.
    490 
    491 2.5 Environment Variables
    492 =========================
    493 
    494 The following environment variables affect the behaviour of `klisp'
    495 
    496 `KLISP_INIT'
    497      A Kernel expression to be evaluated before any arguments to the
    498      interpreter.  To use an init file, just define KLISP_INIT to the
    499      following form `(load "/path/to/init-file")'
    500 
    501 `KLISP_PATH'
    502      A semicolon separated list of templates for controlling the search
    503      of required files.  Each template can use the char `?' to be
    504      replaced by the required name at run-time.
    505 
    506 
    507 
    508 File: klisp.info,  Node: Booleans,  Next: Equivalence,  Prev: Interpreter,  Up: Top
    509 
    510 3 Booleans
    511 **********
    512 
    513 The boolean data type consists of two values, which are called true and
    514 false, and have respectively external representations `#t' and `#f'.
    515 There are no possible mutations of either of these two values, and the
    516 boolean type is encapsulated.
    517 
    518  -- Applicative: boolean? (boolean? . objects)
    519      The primitive type predicate for type boolean.  `boolean?' returns
    520      true iff all the objects in `objects' are of type boolean.
    521 
    522  -- Applicative: not? (not? boolean)
    523      Applicative `not?' is a predicate that returns the logical
    524      negation of its argument.
    525 
    526  -- Applicative: and? (and? . booleans)
    527      Applicative `and?' is a predicate that returns true unless one or
    528      more of its arguments are false.
    529 
    530  -- Applicative: or? (or? . booleans)
    531      Applicative `or?' is a predicate that returns false unless one or
    532      more of its arguments are true.
    533 
    534  -- Operative: $and? ($and? . <list>)
    535      The `$and?' operative performs a "short-circuit and" of its
    536      operands.  It evaluates them from left to right, until either an
    537      operand evaluates to false, or the end of the list is reached.  If
    538      the end of the list is reached (which is immediate if `<list>' is
    539      `nil'), the operative returns true.  If an operand evaluates to
    540      false, no further operand evaluations are performed, and the
    541      operative returns false.  If `<list>' is acyclic, and the last
    542      operand is evaluated, it is evaluated in a special type of tail
    543      context that checks that the passed value is a boolean.  If
    544      `<list>' is cyclic, an unbounded number of operand evaluations may
    545      be performed.  If any of the operands evaluates to a non-boolean
    546      value, an error is signaled (even if it's the last one).
    547 
    548  -- Operative: $or? ($or? . <list>)
    549      The `$or?' operative performs a "short-circuit or" of its
    550      operands.  It evaluates them from left to right, until either an
    551      operand evaluates to true, or the end of the list is reached.  If
    552      the end of the list is reached (which is immediate if `<list>' is
    553      `nil'), the operative returns false.  If an operand evaluates to
    554      true, no further operand evaluations are performed, and the
    555      operative returns true.  If `<list>' is acyclic, and the last
    556      operand is evaluated, it is evaluated in a special type of tail
    557      context that checks that the passed value is a boolean.  If
    558      `<list>' is cyclic, an unbounded number of operand evaluations may
    559      be performed.  If any of the operands evaluates to a non-boolean
    560      value, an error is signaled (even if it's the last one).
    561 
    562 
    563 File: klisp.info,  Node: Equivalence,  Next: Symbols,  Prev: Booleans,  Up: Top
    564 
    565 4 Equivalence
    566 *************
    567 
    568 Kernel has two general-purpose equivalence predicates (whereas R5RS
    569 Scheme has three).  The two Kernel predicates correspond to the
    570 abstract notions of equivalence up to mutation (`equal') and
    571 equivalence in the presence of mutation (`eq?').
    572 
    573  -- Applicative: eq? (eq? . objects)
    574      Predicate `eq?' returns true iff all of `objects' are effectively
    575      the same object, even in the presence of mutation.
    576 
    577  -- Applicative: equal? (equal? . objects)
    578      Predicate `equal?' returns true iff all of `objects' "look" the
    579      same as long as nothing is mutated.  This is a weaker predicate
    580      than `eq?'; that is, `equal?' must return true whenever `eq?'
    581      would return true.
    582 
    583 
    584 File: klisp.info,  Node: Symbols,  Next: Control,  Prev: Equivalence,  Up: Top
    585 
    586 5 Symbols
    587 *********
    588 
    589 Two symbols are eq? iff they have the same external representation.
    590 Symbols are immutable, and the symbol type is encapsulated.  The
    591 external representations of symbols are usually identifiers.  However,
    592 symbols with other external representations may be created.  Symbols
    593 whose external representation is enclosed within "|" (that is "| ...
    594 |") can contain any character supported by klisp, "|" and "\" can be
    595 included by escaping them with a leading "\" (that is "\|" and "\\").
    596 Characters in symbols can also be specified with a unicode hex escape
    597 by using the syntax "\x<hex codepoint>;".  This works whether using the
    598 "| ... |" syntax or not.
    599 
    600  -- Applicative: symbol? (symbol? . objects)
    601      The primitive type predicate for type symbol.  `symbol?' returns
    602      true iff all the objects in `objects' are of type symbol.
    603 
    604  -- Applicative: symbol->string (symbol->string symbol)
    605      Applicative `symbol->string' returns the name of `symbol' as a
    606      string.  The string returned is immutable.
    607 
    608  -- Applicative: string->symbol (string->symbol string)
    609      Applicative `string->symbol' returns the symbol with name
    610      `string'.  The symbol is always interned, which means, that it is
    611      always the case that:
    612           (eq? <symbol> (string->symbol (symbol->string <symbol>)))
    613                => #t
    614        `string->symbol' can create symbols whose external
    615      representation aren't identifiers.  klisp uses the r7rs external
    616      representation for such symbols and so all symbols can be written
    617      and read back.
    618 
    619 
    620 File: klisp.info,  Node: Control,  Next: Pairs and lists,  Prev: Symbols,  Up: Top
    621 
    622 6 Control
    623 *********
    624 
    625 The inert data type is provided for use with control combiners.  It
    626 consists of a single immutable value, having external representation
    627 `#inert'.  The inert type is encapsulated.
    628 
    629  -- Applicative: inert? (inert? . objects)
    630      The primitive type predicate for type inert. `inert?' returns true
    631      iff all the objects in `objects' are of type inert.
    632 
    633  -- Operative: $if ($if <test> <consequent> <alternative>)
    634      The `$if' operative first evaluates `<test>' in the dynamic
    635      environment.  If the result is not of type boolean, an error is
    636      signaled.  If the result is true, `<consequent>' is then evaluated
    637      in the dynamic environment as a tail context.  Otherwise,
    638      `<alternative>' is evaluated in the dynamic environment as a tail
    639      context.
    640 
    641  -- Operative: $sequence ($sequence . <objects>)
    642      The `$sequence' operative evaluates the elements of the list
    643      `<objects>' in the dynamic environment, one at a time from left to
    644      right.  If `<objects>' is a cyclic list, element evaluation
    645      continues indefinitely, with elements in the cycle being evaluated
    646      repeatedly.  If `<objects>' is a nonempty finite list, its last
    647      element is evaluated as a tail context.  If `<objects>' is the
    648      empty list, the result is inert.
    649 
    650  -- Operative: $cond ($cond . <clauses>)
    651      `<clauses>' should be a list of clause expressions, each of the
    652      form `(<test> . <body>)', where body is a list of expressions.
    653 
    654      The following equivalences define the behaviour of the `$cond'
    655      operative:
    656           ($cond) == #inert
    657           ($cond (<test> . <body>) . <clauses>) ==
    658             ($if <test> ($sequence . <body>) ($cond . <clauses>))
    659 
    660  -- Applicative: for-each (for-each applicative . lists)
    661      `lists' must be a nonempty list of lists; if there are two or
    662      more, they should all be the same length. If lists is empty, or if
    663      all of its elements are not lists of the same length, an error is
    664      signaled.
    665 
    666      `for-each' behaves identically to `map', except that instead of
    667      accumulating and returning a list of the results of the
    668      element-wise applications, the results of the applications are
    669      discarded and the result returned by `for-each' is inert.
    670 
    671  -- Applicative: string-for-each (string-for-each applicative . strings)
    672  -- Applicative: vector-for-each (vector-for-each applicative. vectors)
    673  -- Applicative: bytevector-for-each (bytevector-for-each applicative .
    674           bytevectors)
    675      `strings', `vectors', or `bytevectors' should be non-empty lists
    676      of the corresponding type and all elements should be of the same
    677      length.
    678 
    679      These applicatives behave as `for-each' except that the list of
    680      elements passed to `applicative' are the n-th chars, objects, or
    681      uint8s of the strings, vectors or bytevectors passed as arguments.
    682 
    683      SOURCE NOTE: These are taken from r7rs.
    684 
    685  -- Operative: $when ($when <test> . <body>)
    686  -- Operative: $unless ($unless <test> . <body>)
    687      `body' should be a list of expressions.
    688 
    689      These operatives behave as one-armed `$if's with an implicit
    690      `$sequence', except that they always discard the last value and
    691      the result returned is inert.
    692 
    693      So both `$when', and `$unless' evaluate `<test>' in the dynamic
    694      environment.  If the result is non boolean an error is signaled.
    695      In `$when' if the result is false and in `$unless' if the result
    696      is true, the expressions in `<body>' are not evaluated and an
    697      inert value is returned.  Otherwise, the expressions in `<body>'
    698      are evaluated sequentially in the dynamic environment.  If
    699      `<body>' is a non cyclic list, the last expression in `<body>' is
    700      evaluated in a special type of tail context, that, upon receiving
    701      a value discards it and returns an inert value instead.  If
    702      `<body>' is a cyclic list, element evaluation continues
    703      indefinitely, with elements in the cycle being evaluated
    704      repeatedly.  SOURCE NOTE: These are taken from r7rs.
    705 
    706 
    707 File: klisp.info,  Node: Pairs and lists,  Next: Environments,  Prev: Control,  Up: Top
    708 
    709 7 Pairs and lists
    710 *****************
    711 
    712 A pair is an object that refers to two other objects, called its car
    713 and cdr.  The Kernel data type pair is encapsulated.
    714 
    715    The null data type consists of a single immutable value, called nil
    716 or the empty list and having external representation `()', with or
    717 without whitespace between the parentheses. It is immutable, and the
    718 null type is encapsulated.
    719 
    720    If `a' and `d' are external representations of respectively the car
    721 and cdr of a pair `p', then `(a . d)' is an external representation of
    722 `p'. If the cdr of `p' is nil, then `(a)' is also an external
    723 representation of `p'. If the cdr of `p' is a pair `p2', and `(r)' is
    724 an external representation of `p2', then `(a r)' is an external
    725 representation of `p'.    When a pair is output (as by write), an
    726 external representation with the fewest parentheses is used; in the
    727 case of a finite list, only one set of parentheses is required beyond
    728 those used in representing the elements of the list. For example, an
    729 object with external representation `(1 . (2 . (3 . ())))' would be
    730 output using, modulo whitespace, external representation `(1 2 3)'.
    731 
    732  -- Applicative: pair? (pair? . objects)
    733      The primitive type predicate for type pair.  `pair?' returns true
    734      iff all the objects in `objects' are of type pair.
    735 
    736  -- Applicative: null? (null? . objects)
    737      The primitive type predicate for type null.  `null?' returns true
    738      iff all the objects in `objects' are of type null.
    739 
    740  -- Applicative: immutable-pair? (immutable-pair? objects)
    741  -- Applicative: mutable-pair? (mutable-pair? objects)
    742      The primitive type predicates for types immutable pair and mutable
    743      pair.  These return true iff all the objects in `objects' are of
    744      type immutable pair or mutable pair respectively.
    745 
    746      SOURCE NOTE: these aren't provided in the Kernel report, but added
    747      for convenience.  These can be implemented in standard kernel by
    748      using guards.
    749 
    750  -- Applicative: cons (cons object1 object2)
    751      A new mutable pair object is constructed and returned, whose car
    752      and cdr referents are respectively `object1' and `object2'.  No
    753      two objects returned by different calls to cons are `eq?' to each
    754      other.
    755 
    756  -- Applicative: set-car! (set-car! pair object)
    757  -- Applicative: set-cdr! (set-cdr! pair object)
    758      `pair' should be a mutable pair.
    759 
    760      These applicatives set the referent of, respectively, the car
    761      reference or the cdr reference of `pair' to `object'.  The result
    762      of the expression is inert.
    763 
    764  -- Applicative: copy-es-immutable! (copy-es-immutable object)
    765      The short description of this applicative is that it returns an
    766      object `equal?' to `object' with an immutable evaluation
    767      structure. The "-es-" in the name is short for "evaluation
    768      structure".
    769 
    770      The evaluation structure of an object `o' is defined to be the set
    771      of all pairs that can be reached by following chains of references
    772      from `o' without ever passing through a non-pair object. The
    773      evaluation structure of a non-pair object is empty.
    774 
    775      If `object' is not a pair, the applicative returns `object'.
    776      Otherwise (if `object' is a pair), the applicative returns an
    777      immutable pair whose car and cdr would be suitable results for
    778      `(copy-es-immutable (car object))' and `(copy-es-immutable (cdr
    779      object))', respectively.  Further, the evaluation structure of the
    780      returned value is isomorphic to that of `object' at the time of
    781      copying, with corresponding non-pair referents being `eq?'.
    782 
    783      NOTE: In Kernel it's undefined whether immutable pairs are copied
    784      or left "as is" in the result.  klisp doesn't copy immutable
    785      pairs, but that behaviour should not be depended upon.
    786 
    787  -- Applicative: list (list . objects)
    788      The `list' applicative returns `objects'.
    789 
    790      The underlying operative of `list' returns its undifferentiated
    791      operand tree, regardless of whether that tree is or is not a list.
    792 
    793  -- Applicative: list* (list* . objects)
    794      `objects' should be a finite nonempty list of arguments.
    795 
    796      The following equivalences hold:
    797           (list* arg1) == arg1
    798           (list* arg1 arg2 . args) == (cons arg1 (list* arg2 . args))
    799 
    800  -- Applicative: car (car pair)
    801  -- Applicative: cdr (cdr pair)
    802      These applicatives return, respectively, the car and cdr of `pair'.
    803 
    804  -- Applicative: caar (caar pair)
    805  -- Applicative: cadr (cadr pair)
    806  -- Applicative: cdar (cdar pair)
    807  -- Applicative: cddr (cddr pair)
    808  -- Applicative: caaar (caaar pair)
    809  -- Applicative: caadr (caadr pair)
    810  -- Applicative: cadar (cadar pair)
    811  -- Applicative: caddr (caddr pair)
    812  -- Applicative: cdaar (cdaar pair)
    813  -- Applicative: cdadr (cdadr pair)
    814  -- Applicative: cddar (cddar pair)
    815  -- Applicative: cdddr (cdddr pair)
    816  -- Applicative: caaaar (caaaar pair)
    817  -- Applicative: caaadr (caaadr pair)
    818  -- Applicative: caadar (caadar pair)
    819  -- Applicative: caaddr (caaddr pair)
    820  -- Applicative: cadaar (cadaar pair)
    821  -- Applicative: cadadr (cadadr pair)
    822  -- Applicative: caddar (caddar pair)
    823  -- Applicative: cadddr (cadddr pair)
    824  -- Applicative: cdaaar (cdaaar pair)
    825  -- Applicative: cdaadr (cdaadr pair)
    826  -- Applicative: cdadar (cdadar pair)
    827  -- Applicative: cdaddr (cdaddr pair)
    828  -- Applicative: cddaar (cddaar pair)
    829  -- Applicative: cddadr (cddadr pair)
    830  -- Applicative: cdddar (cdddar pair)
    831  -- Applicative: cddddr (cddddr pair)
    832      These applicatives are compositions of `car' and `cdr', with the
    833      "a’s" and "d’s" in the same order as they would appear if all the
    834      individual "car’s" and "cdr’s" were written out in prefix order.
    835      Arbitrary compositions up to four deep are provided. There are
    836      twenty-eight of these applicatives in all.
    837 
    838  -- Applicative: make-list (make-list length [fill])
    839      `length' shoulde be an exact non-negative integer.
    840 
    841      Applicative `make-list' creates a new mutable acyclic list of
    842      length `length', with all pairs having `fill' in their cars.  If
    843      no value is provided for `fill', `#inert' is used.
    844 
    845      SOURCE NOTE: this is taken from r7rs.
    846 
    847  -- Applicative: list-copy (list-copy list)
    848      Applicative `list-copy' creates a new mutable copy of `list'.
    849      That is, the returned list has the same list metrics as `list' and
    850      the cars in the returned list are initially `eq?' to the
    851      corresponding cars in `list'.
    852 
    853      SOURCE NOTE: this is taken from r7rs.
    854 
    855  -- Applicative: reverse (reverse list)
    856      `list' should be an acyclic list.
    857 
    858      Applicative `reverse' makes a mutable copy of list but with the
    859      reverse order.  That is, the returned list has the same number of
    860      pairs as `list' and the cars in the returned list are initially
    861      `eq?' to the corresponding cars in `list' but starting from the
    862      end and going backwards.
    863 
    864      SOURCE NOTE: this is taken from r7rs.
    865 
    866  -- Applicative: get-list-metrics (get-list-metrics object)
    867      By definition, an improper list is a data structure whose objects
    868      are its start together with all objects reachable from the start by
    869      following the cdr references of pairs, and whose internal
    870      references are just the cdr references of its pairs.  Every
    871      object, of whatever type, is the start of an improper list.  If
    872      the start is not a pair, the improper list consists of just that
    873      object.  The acyclic prefix length of an improper list `L' is the
    874      number of pairs of `L' that a naive traversal of `L' would visit
    875      only once. The cycle length of `L' is the number of pairs of `L'
    876      that a naive traversal would visit repeatedly. Two improper lists
    877      are structurally isomorphic iff they have the same acyclic prefix
    878      length and cycle length and, if they are terminated by non-pair
    879      objects rather than by cycles, the non-pair objects have the same
    880      type.  Applicative `get-list-metrics' constructs and returns a
    881      list of exact integers of the form `(p n a c)', where `p', `n',
    882      `a', and `c' are, respectively, the number of pairs in, the number
    883      of nil objects in, the acyclic prefix length of, and the cycle
    884      length of, the improper list starting with `object'. `n' is either
    885      `0' or `1', `a + c = p', and `n' and `c' cannot both be non-zero.
    886      If `c = 0', the improper list is acyclic; if `n = 1', the improper
    887      list is a finite list; if `n = c = 0', the improper list is not a
    888      list; if `a = c = 0', `object' is not a pair.
    889 
    890  -- Applicative: list-tail (list-tail object k)
    891      `object' must be the start of an improper list containing at least
    892      `k' pairs.
    893 
    894      The `list-tail' applicative follows `k' cdr references starting
    895      from `object'.
    896 
    897      The following equivalences hold:
    898           (list-tail object 0) == object
    899           (list-tail object (+ k 1)) == (list-tail (cdr object) k)
    900 
    901  -- Applicative: encycle! (encycle! object k1 k2)
    902      The improper list starting at `object' must contain at least `k1 +
    903      k2' pairs.
    904 
    905      If `k2 = 0', the applicative does nothing. If `k2 > 0', the
    906      applicative mutates the improper list starting at `object' to have
    907      acyclic prefix length `k1' and cycle length `k2', by setting the
    908      cdr of the `(k1+k2)'th pair in the list to refer to the `(k1 +
    909      1)'th pair in the list.  The result returned by `encycle!' is
    910      inert.
    911 
    912  -- Applicative: map (map applicative . lists)
    913      `lists' must be a nonempty list of lists; if there are two or
    914      more, they must all have the same length.
    915 
    916      The map applicative applies `applicative' element-wise to the
    917      elements of the lists in lists (i.e., applies it to a list of the
    918      first elements of the lists, to a list of the second elements of
    919      the lists, etc.), using the dynamic environment from which map was
    920      called, and returns a list of the results, in order. The
    921      applications may be performed in any order, as long as their
    922      results occur in the resultant list in the order of their
    923      arguments in the original lists.  If `lists' is a cyclic list,
    924      each argument list to which `applicative' is applied is
    925      structurally isomorphic to `lists'.  If any of the elements of
    926      `lists' is a cyclic list, they all must be, or they wouldn’t all
    927      have the same length.  Let `a1...an' be their acyclic prefix
    928      lengths, and `c1...cn' be their cycle lengths.  The acyclic prefix
    929      length `a' of the resultant list will be the maximum of the `ak',
    930      while the cycle length `c' of the resultant list will be the least
    931      common multiple of the `ck'.  In the construction of the result,
    932      `applicative' is called exactly `a + c' times.
    933 
    934  -- Applicative: length (length object)
    935      Applicative `length' returns the (exact) improper-list length of
    936      `object'.  That is, it returns the number of consecutive cdr
    937      references that can be followed starting from `object'.  If
    938      `object' is not a pair, it returns zero; if `object' is a cyclic
    939      list, it returns positive infinity.
    940 
    941  -- Applicative: list-ref (list-ref object k)
    942      The `list-ref' applicative returns the `car' of the object
    943      obtained by following `k' cdr references starting from `object'.
    944 
    945      NOTE: In the current report, object is required to be a list. In
    946      klisp, for now, we prefer the behaviour presented here, as it is
    947      more in line with the applicative `list-tail'.  That is, we define
    948      `list-ref' by the following equivalence:
    949           (list-ref object k) == (car (list-tail object k))
    950 
    951  -- Applicative: append (append . lists)
    952      Here, all the elements of `lists' except the last element (if any)
    953      must be acyclic lists.  The `append' applicative returns a freshly
    954      allocated list of the elements of all the specified `lists', in
    955      order, except that if there is a last specified element of
    956      `lists', it is not copied, but is simply referenced by the cdr of
    957      the preceding pair (if any) in the resultant list.  If `lists' is
    958      cyclic, the cycle of the result list consists of just the elements
    959      of the lists specified in the cycle in `lists'. In this case, the
    960      acyclic prefix length of the result is the sum of the lengths of
    961      the lists specified in the acyclic prefix of `lists', and the
    962      cycle length of the result is the sum of the lengths of the lists
    963      specified in the cycle of `lists'.
    964 
    965      The following equivalences hold:
    966           (append) == ()
    967           (append h) == h
    968           (append () h . t) == (append h . t)
    969           (append (cons a b) h . t) == (cons a (append b h . t))
    970 
    971  -- Applicative: list-neighbors (list-neighbors list)
    972      The `list-neighbors' applicative constructs and returns a list of
    973      all the consecutive sublists of `list' of length 2, in order.  If
    974      `list' is nil, the result is nil.  If `list' is non-nil, the
    975      length of the result is one less than the length of `list'. If
    976      `list' is cyclic, the result is structurally isomorphic to it
    977      (i.e., has the same acyclic prefix length and cycle length).
    978 
    979      For example:
    980           (list-neighbors (list 1 2 3 4)) => ((1 2) (2 3) (3 4))
    981 
    982  -- Applicative: filter (filter applicative list)
    983      Applicative `filter' passes each of the elements of `list' as an
    984      argument to `applicative', one at a time in no particular order,
    985      using a fresh empty environment for each call.  The result of each
    986      call to `applicative' must be boolean, otherwise an error is
    987      signaled.  `filter' constructs and returns a list of all elements
    988      of `list' on which `applicative' returned true, in the same order
    989      as in `list'.  `applicative' is called exactly as many times as
    990      there are pairs in `list'.  The resultant list has a cycle
    991      containing exactly those elements accepted by `applicative' that
    992      were in the cycle of `list'; if there were no such elements, the
    993      result is acyclic.
    994 
    995  -- Applicative: assoc (assoc object pairs [eq-pred?])
    996      Applicative `assoc' returns the first element of `pairs' whose car
    997      is `eq-pred?' to `object'.  If there is no such element in
    998      `pairs', nil is returned.  If `eq-pred?' is not supplied it
    999      defaults to `equal?'.  SOURCE NOTE: the optional eq-pred? argument
   1000      is from r7rs.
   1001 
   1002  -- Applicative: member? (member? object list [eq-pred?])
   1003      Applicative `member?' is a predicate that returns true iff some
   1004      element of `list' is `eq-pred?' to `object'.  If `eq-pred?' is not
   1005      supplied, it defaults to `equal?'.  SOURCE NOTE: the optional
   1006      eq-pred? argument is from r7rs.
   1007 
   1008  -- Applicative: finite-list? (finite-list? . objects)
   1009      This is the type predicate for type finite-list.  `finite-list?'
   1010      returns true iff all the objects in `objects' are acyclic lists.
   1011 
   1012  -- Applicative: countable-list? (countable-list? . objects)
   1013      This is the type predicate for type list.  `countable-list?'
   1014      returns true iff all the objects in `objects' are lists.
   1015 
   1016  -- Applicative: reduce (reduce list binary identity [precycle incycle
   1017           postcycle])
   1018      `binary' should be an applicative. If the short form is used,
   1019      `list' should be an acyclic. If the long form is used, `precycle',
   1020      `incycle', and `postcycle' should be applicatives.
   1021 
   1022      If `list' is empty, applicative `reduce' returns `identity'.  If
   1023      `list' is nonempty but acyclic, applicative `reduce' uses binary
   1024      operation `binary' to merge all the elements of `list' into a
   1025      single object, using any associative grouping of the elements.
   1026      That is, the sequence of objects initially found in `list' is
   1027      repeatedly decremented in length by applying `binary' to a list of
   1028      any two consecutive objects, replacing those two objects with the
   1029      result at the point in the sequence where they occurred; and when
   1030      the sequence contains only one object, that object is returned.
   1031      If `list' is cyclic, the long form must be used.  The elements of
   1032      the cycle are passed, one at a time (but just once for each
   1033      position in the cycle), as arguments to unary applicative
   1034      `precycle'; the finite, cyclic sequence of results from `precycle'
   1035      is reduced using binary applicative `incycle'; and the result from
   1036      reducing the cycle is passed as an argument to unary applicative
   1037      `postcycle'. Binary operation `binary' is used to reduce the
   1038      sequence consisting of the elements of the acyclic prefix of
   1039      `list' followed by the result returned by `postcycle'. The only
   1040      constraint on the order of calls to the applicatives is that each
   1041      call must be made before its result is needed (thus, parts of the
   1042      reduction of the acyclic prefix may occur before the contribution
   1043      from the cycle has been completed).
   1044 
   1045      Each call to `binary', `precycle', `incycle', or `postcycle' uses
   1046      the dynamic environment of the call to `reduce'.
   1047 
   1048      If `list' is acyclic with length `n >= 1', `binary' is called `n -
   1049      1' times.  If `list' is cyclic with acyclic prefix length `a' and
   1050      cycle length `c', `binary' is called `a' times; `precycle', `c'
   1051      times; `incycle', `c - 1' times; and `postcycle', once.
   1052 
   1053  -- Applicative: append! (append! . lists)
   1054      `lists' must be a nonempty list; its first element must be an
   1055      acyclic nonempty list, and all of its elements except the last
   1056      element (if any) must be acyclic lists.
   1057 
   1058      The `append!' applicative sets the cdr of the last pair in each
   1059      nonempty list argument to refer to the next non-nil argument,
   1060      except that if there is a last non-nil argument, it isn’t mutated.
   1061      It is an error for any two of the list arguments to have the same
   1062      last pair.  The result returned by this applicative is inert.
   1063 
   1064      The following equivalences hold:
   1065           (append! v) == #inert
   1066           (append! u v . w) == ($sequence (append! u v) (append! u . w))
   1067 
   1068  -- Applicative: copy-es (copy-es object)
   1069      Briefly, applicative `copy-es' returns an object initially
   1070      `equal?' to `object' with a freshly constructed evaluation
   1071      structure made up of mutable pairs.  If `object' is not a pair,
   1072      the applicative returns `object'.  If `object' is a pair, the
   1073      applicative returns a freshly constructed pair whose car and cdr
   1074      would be suitable results for `(copy-es (car object))' and
   1075      `(copy-es (cdr object))', respectively.  Further, the evaluation
   1076      structure of the returned value is structurally isomorphic to that
   1077      of `object' at the time of copying, with corresponding non-pair
   1078      referents being `eq?'.
   1079 
   1080  -- Applicative: assq (assq object pairs)
   1081      Applicative `assq' returns the first element of `pairs' whose car
   1082      is `eq?' to `object'.  If there is no such element in `pairs', nil
   1083      is returned.
   1084 
   1085  -- Applicative: memq? (memq? object list)
   1086      Applicative `memq?' is a predicate that returns true iff some
   1087      element of `list' is `eq?' to `object'.
   1088 
   1089 
   1090 File: klisp.info,  Node: Environments,  Next: Combiners,  Prev: Pairs and lists,  Up: Top
   1091 
   1092 8 Environments
   1093 **************
   1094 
   1095 An environment consists of a set of bindings, and a list of zero or
   1096 more references to other environments called its parents.  Changing the
   1097 set of bindings of an environment, or setting the referent of the
   1098 reference in a binding, is a mutation of the environment. (Changing the
   1099 parent list, or a referent in the list, would be a mutation of the
   1100 environment too, but there is no facility provided to do it.) The
   1101 Kernel data type environment is encapsulated.  Among other things,
   1102 there is no facility provided for enumerating all the variables
   1103 exhibited by an environment (which is not required, after all, to be a
   1104 finite set), and no facility for identifying the parents of an
   1105 environment.  Two environments are `equal?' iff they are `eq?'.
   1106 
   1107    An auxiliary data type used by combiners that perform binding is
   1108 ignore. The ignore type consists of a single immutable value, having
   1109 external representation `#ignore'.  The ignore type is encapsulated.
   1110 
   1111  -- Applicative: environment? (environment? . objects)
   1112      The primitive type predicate for type environment.  `environment?'
   1113      returns true iff all the objects in `objects' are of type
   1114      environment.
   1115 
   1116  -- Applicative: ignore? (ignore? . objects)
   1117      The primitive type predicate for type ignore.  `ignore?' returns
   1118      true iff all the objects in `objects' are of type ignore.
   1119 
   1120  -- Applicative: eval (eval expression environment)
   1121      The `eval' applicative evaluates `expression' in `environment', as
   1122      a tail context, returning the resulting value.
   1123 
   1124  -- Applicative: make-environment (make-environment . environments)
   1125      The applicative constructs and returns a new environment, with
   1126      initially no local bindings, and parent environments the
   1127      environments listed in `environments'. The constructed environment
   1128      internally stores its list of parents independent of the
   1129      first-class list `environments', so that subsequent mutation of
   1130      `environments' will not change the parentage of the constructed
   1131      environment. If the provided list `environments' is cyclic, the
   1132      constructed environment will still check each of its parents at
   1133      most once, and signal an error if no binding is found locally or
   1134      in any of the parents.  No two objects returned by different calls
   1135      to `make-environment' are `eq?' to each other.
   1136 
   1137  -- Operative: $define! ($define! <definiend> <expression>)
   1138      `<definiend>' should be a formal parameter tree, as described
   1139      below; otherwise, an error is signaled.
   1140 
   1141      The `$define!' operative evaluates `<expression>' in the dynamic
   1142      environment and matches `<definiend>' to the result in the dynamic
   1143      environment, binding each symbol in definiend in the dynamic
   1144      environment to the corresponding part of the result; the matching
   1145      process will be further described below. The ancestors of the
   1146      dynamic environment, if any, are unaffected by the matching
   1147      process, as are all bindings, local to the dynamic environment, of
   1148      symbols not in `<definiend>'.  The result returned by `$define!' is
   1149      inert.
   1150 
   1151      A formal parameter tree has the following context-free structure:
   1152           ptree:: symbol | #ignore | () | (ptree . ptree)
   1153 
   1154      That is, a formal parameter tree is either a symbol, or ignore, or
   1155      nil, or a pair whose car and cdr referents are formal parameter
   1156      trees.  A formal parameter tree must also be acyclic, and no one
   1157      symbol can occur more than once in it.  It is not an error for a
   1158      pair in the tree to be reachable from the root by more than one
   1159      path, as long as there is no cycle; but if any particular symbol
   1160      were reachable from the root by more than one path, that would
   1161      count as occurring more than once.  Thus, if a pair is reachable
   1162      by more than one path, there must be no symbols reachable from it.
   1163 
   1164      Matching of a formal parameter tree `t' to an object `o' in an
   1165      environment `e' proceeds recursively as follows.  If the matching
   1166      process fails, an error is signaled.
   1167         * If `t' is a symbol, then `t' is bound to `o' in `e'.
   1168 
   1169         * If `t' is `#ignore', no action is taken.
   1170 
   1171         * If `t' is nil, then `o' must be nil (else matching fails).
   1172 
   1173         * If `t' is a pair, then `o' must be a pair (else matching
   1174           fails). The car of `t' is matched to the car of `o' in `e',
   1175           and the cdr of `t' is matched to the cdr of `o' in `e'.
   1176 
   1177  -- Operative: $let ($let <bindings> . <objects>)
   1178      `<bindings>' should be a finite list of
   1179      formal-parameter-tree/expression pairings, each of the form
   1180      `(formals expression)', where each `formals' is a formal
   1181      parameter, and no symbol occurs in more than one of the `formals'.
   1182 
   1183      The following equivalence holds:
   1184 
   1185           ($let ((form1 exp1) ... (formn expn)) . objects) ==
   1186             (($lambda (form1 ... formn) . objects) exp1 ... expn)
   1187 
   1188      Thus, the `expk' are first evaluated in the dynamic environment,
   1189      in any order; then a child environment `e' of the dynamic
   1190      environment is created, with the `formk' matched in `e' to the
   1191      results of the evaluations of the `expk'; and finally the
   1192      subexpressions of `objects' are evaluated in `e' from left to
   1193      right, with the last (if any) evaluated as a tail context, or if
   1194      `objects' is empty the result is inert.
   1195 
   1196  -- Operative: $binds? ($binds? <exp> . <symbols>)
   1197      Operative `$binds' evaluates `<exp>' in the dynamic environment;
   1198      call the result `env'.  `env' must be an environment.  The
   1199      operative is a predicate that returns true iff all its later
   1200      operands, `<symbols>', are visibly bound in `env'.
   1201 
   1202  -- Applicative: get-current-environment (get-current-environment)
   1203      The `get-current-environment' applicative returns the dynamic
   1204      environment in which it is called.
   1205 
   1206  -- Applicative: make-kernel-standard-environment
   1207           (make-kernel-standard-environment)
   1208      The `make-kernel-standard-environment' applicative returns a
   1209      standard environment; that is, a child of the ground environment
   1210      with no local bindings.
   1211 
   1212  -- Operative: $let* ($let* <bindings> . <body>)
   1213      `<bindings>' should be a finite list of
   1214      formal-parameter-tree/expression pairings, each of the form
   1215      `(formals expression)', where each `formals' is a formal parameter
   1216      tree; `<body>' should be a list of expressions.
   1217 
   1218      The following equivalences hold:
   1219 
   1220           ($let* () . body) == ($let () . body)
   1221 
   1222           ($let* ((form exp) . bindings) . body) ==
   1223             ($let ((form exp)) ($let* bindings . body))
   1224 
   1225  -- Operative: $letrec ($letrec <bindings> . <body>)
   1226      `<bindings>' and `<body>' should be as described for `$let'.
   1227 
   1228      The following equivalence holds:
   1229           ($letrec ((form1 exp1) ... (formn expn)) . body) ==
   1230             ($let () ($define! (form1 ... formn) (list exp1 ... expn)) . body)
   1231 
   1232  -- Operative: $letrec* ($letrec* <bindings> . <body>)
   1233      `<bindings>' and `<body>' should be as described for `$let*'.
   1234 
   1235      The following equivalences hold:
   1236           ($letrec* () . body) == ($letrec () . body)
   1237 
   1238           ($letrec* ((form exp) . bindings) . body) ==
   1239             ($letrec ((form exp)) ($letrec* bindings . body))
   1240 
   1241  -- Operative: $let-redirect ($let-redirect <exp> <bindings> . <body>)
   1242      `<bindings>' and `<body>' should be as described for `$let'.
   1243 
   1244      The following equivalence holds:
   1245 
   1246           ($let-redirect exp ((form1 exp1) ... (formn . body) expn)) ==
   1247             ((eval (list $lambda (form1 ... formn) body) exp) expn ... expn)
   1248 
   1249  -- Operative: $let-safe ($let-safe <bindings> . <body>)
   1250      `<bindings>' and `<body>' should be as described for `$let'.
   1251 
   1252      The following equivalence holds:
   1253 
   1254           ($let-safe bindings . body) ==
   1255             ($let-redirect (make-kernel-standard-environment) bindings . body)
   1256 
   1257  -- Operative: $remote-eval ($remote-eval <exp1> <exp2>)
   1258      Operative `$remote-eval' evaluates `<exp2>' in the dynamic
   1259      environment, then evaluates `<exp1>' as a tail context in the
   1260      environment that must result from the first evaluation.
   1261 
   1262  -- Operative: $bindings->environment ($bindings->environment .
   1263           <bindings>)
   1264      `<bindings>' should be as described for `$let'.
   1265 
   1266      The following equivalence holds:
   1267 
   1268           ($bindings->environment . bindings) ==
   1269             ($let-redirect (make-environment) bindings (get-current-environment))
   1270 
   1271  -- Applicative: eval-string (eval-string string environment)
   1272      `string' should be the external representation of a single object.
   1273      If none or more than one external representation is found in
   1274      `string' then an error is signaled.
   1275 
   1276      Applicative `eval-string' reads an external representation from
   1277      string, and evaluates the resulting object in `environment', as a
   1278      tail context, returning the resulting value.
   1279 
   1280  -- Operative: $set! ($set! <exp1> <formals> <exp2>)
   1281      `<formals>' should be as described for the `$define!' operative.
   1282      The `$set!' operative evaluates `<exp1>' and `<exp2>' in the
   1283      dynamic environment; call the results `env' and `obj'.  If `env'
   1284      is not an environment, an error is signaled.  Then the operative
   1285      matches `<formals>' to `obj' in environment `env'.  Thus, the
   1286      symbols of `<formals>' are bound in `env' to the corresponding
   1287      parts of `obj'.  The result returned by `$set!' is inert.
   1288 
   1289  -- Operative: $provide! ($provide! <symbols> . <body>)
   1290      `<symbols>' must be a finite list of symbols, containing no
   1291      duplicates.  `<body>' must be a finite list.
   1292 
   1293      The `$provide!' operative constructs a child `e' of the dynamic
   1294      environment `d'; evaluates the elements of `<body>' in `e', from
   1295      left to right, discarding all of the results; and exports all of
   1296      the bindings of symbols in `<symbols>' from `e' to `d', i.e.,
   1297      binds each symbol in `d' to the result of looking it up in `e'.
   1298      The result returned by `$provide!'  is inert.
   1299 
   1300      The following equivalence holds:
   1301 
   1302           ($provide!  symbols . body) ==
   1303           ($define!  symbols ($let () ($sequence . body) (list . symbols)))
   1304 
   1305  -- Operative: $import! ($import! <exp> . <symbols>)
   1306      `<symbols>' must be a list of symbols.
   1307 
   1308      The `$import!' operative evaluates `<exp>' in the dynamic
   1309      environment; call the result `env'. `env' must be an environment.
   1310      Each distinct symbol `s' in `<symbols>' is evaluated in `env', and
   1311      `s' is bound in the dynamic environment to the result of this
   1312      evaluation.
   1313 
   1314      The following equivalence holds:
   1315 
   1316           ($import! exp . symbols) ==
   1317           ($define! symbols ($remote-eval (list symbols) exp))
   1318 
   1319 
   1320 File: klisp.info,  Node: Combiners,  Next: Continuations,  Prev: Environments,  Up: Top
   1321 
   1322 9 Combiners
   1323 ***********
   1324 
   1325 There are two types of combiners in Kernel, operative and applicative.
   1326 Both types are encapsulated. All combiners are immutable.  Two
   1327 applicatives are `eq?' iff their underlying combiners are `eq?'.
   1328 However, `eq?'-ness of operatives is only constrained by the general
   1329 rules for `eq?', which leave considerable leeway for variation between
   1330 implementations.  klisp only considers `eq?' those operatives
   1331 constructed by the same call to a constructor (e.g. `$vau').  Two
   1332 combiners are `equal?' iff they are `eq?'.
   1333 
   1334  -- Applicative: operative? (operative? . objects)
   1335      The primitive type predicate for type operative. `operative?'
   1336      returns true iff all the objects in `objects' are of type
   1337      operative.
   1338 
   1339  -- Applicative: applicative? (applicative? . objects)
   1340      The primitive type predicate for type applicative.  `applicative?'
   1341      returns true iff all the objects in `objects' are of type
   1342      applicative.
   1343 
   1344  -- Operative: $vau ($vau <formals> <eformal> . <objects>)
   1345      `<formals>' should be a formal parameter tree; `<eformal>' should
   1346      be either a symbol or `#ignore'.  If `<formals>' does not have the
   1347      correct form for a formal parameter tree, or if `<eformal>' is a
   1348      symbol that also occurs in `<formals>', an error is signaled.
   1349 
   1350      A `vau' expression evaluates to an operative; an operative created
   1351      in this way is said to be compound. The environment in which the
   1352      `vau' expression was evaluated is remembered as part of the
   1353      compound operative, called the compound operative’s static
   1354      environment.  `<formals>' and `<objects>' are copied as by
   1355      `copy-es-immutable' and the copies are stored as part of the
   1356      operative being constructed.  This avoids problem if these
   1357      structures are later mutated.
   1358 
   1359      When the compound operative created by `$vau' is later called with
   1360      an object and an environment, here called respectively the operand
   1361      tree and the dynamic environment, the following happens:
   1362 
   1363        1. A new, initially empty environment is created, with the static
   1364           environment as its parent. This will be called the local
   1365           environment.
   1366 
   1367        2. A stored copy of the formal parameter tree formals is matched
   1368           in the local environment to the operand tree, locally binding
   1369           the symbols of formals to the corresponding parts of the
   1370           operand tree.  eformal is matched to the dynamic environment;
   1371           that is, if eformal is a symbol then that symbol is bound in
   1372           the local environment to the dynamic environment.
   1373 
   1374        3. A stored copy of the expressions is evaluated sequentially
   1375           from left to right, with the last (if any) evaluated as a
   1376           tail context, or if the list of expressions is empty, the
   1377           result is inert.
   1378 
   1379      NOTE: Because compound operatives are not a distinct type in
   1380      Kernel, they are covered by the encapsulation of type operative.
   1381      In particular, an implementation of Kernel cannot provide a
   1382      feature that supports extracting the static environment of any
   1383      given compound operative, nor that supports determining whether or
   1384      not a given operative is compound.
   1385 
   1386  -- Applicative: wrap (wrap combiner)
   1387      The `wrap' applicative returns an applicative whose underlying
   1388      combiner is `combiner'.
   1389 
   1390  -- Applicative: unwrap (unwrap applicative)
   1391      The `unwrap' applicative returns the underlying combiner of
   1392      `applicative'.
   1393 
   1394  -- Operative: $lambda ($lambda <formals> . <objects>)
   1395      `<formals>' should be a formal parameter tree.
   1396 
   1397      The `$lambda' operative is defined by the following equivalence:
   1398           ($lambda formals . objects) ==
   1399             (wrap ($vau formals #ignore . objects))
   1400 
   1401  -- Applicative: apply (apply applicative object [environment])
   1402      Applicative `apply' combines the underlying combiner of
   1403      `applicative' with `object' in a tail context with dynamic
   1404      environment `environment' (if the long form is used) or in an
   1405      empty environment (if the short form is used).
   1406 
   1407      The following equivalences hold:
   1408           (apply applicative object environment) ==
   1409             (eval (cons (unwrap applicative) object) environment)
   1410 
   1411           (apply applicative object) ==
   1412             (apply applicative object (make-environment))
   1413 
   1414  -- Applicative: map (map applicative . lists)
   1415      `lists' must be a nonempty list of lists; if there are two or
   1416      more, they must all have the same length. If `lists' is empty, or
   1417      if all of its elements are not lists of the same length, an error
   1418      is signaled.
   1419 
   1420      The `map' applicative applies `applicative' element-wise to the
   1421      elements of the lists in `lists' (i.e., applies it to a list of
   1422      the first elements of the `lists', to a list of the second
   1423      elements of the `lists', etc.), using the dynamic environment from
   1424      which `map' was called, and returns a list of the results, in
   1425      order. The applications may be performed in any order, as long as
   1426      their results occur in the resultant list in the order of their
   1427      arguments in the original `lists'.  If `lists' is a cyclic list,
   1428      each argument list to which `applicative' is applied is
   1429      structurally isomorphic to `lists'.  If any of the elements of
   1430      `lists' is a cyclic list, they all must be, or they wouldn’t all
   1431      have the same length.  Let `a1...an' be their acyclic prefix
   1432      lengths, and `c1...cn' be their cycle lengths.  The acyclic prefix
   1433      length `a' of the resultant list will be the maximum of the `ak',
   1434      while the cycle length `c' of the resultant list will be the least
   1435      common multiple of the `ck'.  In the construction of the result,
   1436      applicative is called exactly `a + c' times.
   1437 
   1438  -- Applicative: string-map (string-map applicative . strings)
   1439  -- Applicative: vector-map (vector-map applicative . vectors)
   1440  -- Applicative: bytevector-map (bytevector-map applicative .
   1441           bytevectors)
   1442      `strings', `vectors', or `bytevectors' should be non-empty lists
   1443      of the corresponding type and all elements should be of the same
   1444      length.
   1445 
   1446      These applicatives behave as `map' except that the list of
   1447      elements passed to `applicative' are the n-th chars, objects, or
   1448      uint8s of the strings, vectors or bytevectors passed as arguments.
   1449 
   1450      SOURCE NOTE: These are taken from r7rs.
   1451 
   1452  -- Applicative: combiner? (combiner? . objects)
   1453      The primitive type predicate for type combiner. `combiner?'
   1454      returns true iff all the objects in `objects' are of type combiner
   1455      (i.e. applicative or operative).
   1456 
   1457 
   1458 File: klisp.info,  Node: Continuations,  Next: Encapsulations,  Prev: Combiners,  Up: Top
   1459 
   1460 10 Continuations
   1461 ****************
   1462 
   1463 A continuation is a plan for all future computation, parameterized by a
   1464 value to be provided, and contingent on the states of all mutable data
   1465 structures (which notably may include environments). When the Kernel
   1466 evaluator is invoked, the invoker provides a continuation to which the
   1467 result of the evaluation will normally be returned.
   1468 
   1469    For example, when `$if' evaluates its test operand, the continuation
   1470 provided for the result expects to be given a boolean value; and,
   1471 depending on which boolean it gets, it will evaluate either the
   1472 consequent or the alternative operand as a tail context — that is, the
   1473 continuation provided for the result of evaluating the selected operand
   1474 is the same continuation that was provided for the result of the call
   1475 to `$if'.
   1476 
   1477    A Kernel program may sometimes capture a continuation; that is,
   1478 acquire a reference to it as a first-class object. The basic means of
   1479 continuation capture is applicative `call/cc'.  Given a first-class
   1480 continuation `c', a combiner can be constructed that will abnormally
   1481 pass its operand tree to `c' (as opposed to the normal return of values
   1482 to continuations). In the simplest case, the abnormally passed value
   1483 arrives at `c' as if it had been normally returned to `c'. In general,
   1484 continuations bypassed by the abnormal pass may have entry/exit guards
   1485 attached to them, and these guards can intercept the abnormal pass
   1486 before it reaches `c'.  Each entry/exit guard consists of a selector
   1487 continuation, which designates which abnormal passes the guard will
   1488 intercept, and an interceptor applicative that performs the
   1489 interception when selected.
   1490 
   1491    Continuations are immutable, and are `equal?' iff `eq?'.  The
   1492 continuation type is encapsulated.
   1493 
   1494  -- Applicative: continuation? (continuation? . objects)
   1495      The primitive type predicate for type continuation.
   1496      `continuation?' returns true iff all the objects in `objects' are
   1497      of type continuation.
   1498 
   1499  -- Applicative: call/cc (call/cc combiner)
   1500      Calls `combiner' in the dynamic environment as a tail context,
   1501      passing as sole operand to it the continuation to which `call/cc'
   1502      would normally return its result.  (That is, constructs such a
   1503      combination and evaluates it in the dynamic environment.)
   1504 
   1505  -- Applicative: extend-continuation (extend-continuation continuation
   1506           applicative [environment])
   1507      The `extend-continuation' applicative constructs and returns a new
   1508      child of `continuation' that, when it normally receives a value v,
   1509      calls the underlying combiner of `applicative' with dynamic
   1510      environment `environment' (or an empty environment if none was
   1511      specified) and operand tree `v', the result of the call normally
   1512      to be returned to `continuation'.
   1513 
   1514      The following equivalnece defines the short version:
   1515           (extend-continuation c a) ==
   1516             (extend-continuation c a (make-environment))
   1517 
   1518  -- Applicative: guard-continuation (guard-continuation entry-guards
   1519           continuation exit-guards)
   1520      `entry-guards' and `exit-guards' should each be a list of clauses;
   1521      each clause should be a list of length two, whose first element is
   1522      a continuation, and whose second element is an applicative whose
   1523      underlying combiner is operative.
   1524 
   1525      Applicative `guard-continuation' constructs two continuations: a
   1526      child of continuation, called the `outer continuation'; and a
   1527      child of the `outer continuation', called the `inner
   1528      continuation'.  The `inner continuation' is returned as the result
   1529      of the call to `guard-continuation'.
   1530 
   1531      When the `inner continuation' normally receives a value, it passes
   1532      the value normally to the `outer continuation'; and when the
   1533      `outer continuation' normally receives a value, it passes the
   1534      value normally to `continuation'. Thus, in the absence of abnormal
   1535      passing, the inner and outer continuations each have the same
   1536      behavior as `continuation'.
   1537 
   1538      The two elements of each guard clause are called, respectively, the
   1539      `selector' and the `interceptor'.  The `selector' continuation is
   1540      used in deciding whether to intercept a given abnormal pass, and
   1541      the `interceptor' applicative is called to perform customized
   1542      action when interception occurs.
   1543 
   1544      At the beginning of the call to `guard-continuation', internal
   1545      copies are made of the evaluation structures of `entry-guards' and
   1546      `exit-guards', so that the selectors and interceptors contained in
   1547      the arguments at that time remain fixed thereafter, independent of
   1548      any subsequent mutations to the arguments.
   1549 
   1550  -- Applicative: continuation->applicative (continuation->applicative
   1551           continuation)
   1552      Returns an applicative whose underlying operative abnormally passes
   1553      its operand tree to `continuation', thus: A series of interceptors
   1554      are selected to handle the abnormal pass, and a continuation is
   1555      derived that will normally perform all the interceptions in
   1556      sequence and pass some value to the destination of the originally
   1557      abnormal pass.  The operand tree is then normally passed to the
   1558      derived continuation.
   1559 
   1560  -- Variable: root-continuation
   1561      This continuation is the ancestor of all other continuations. When
   1562      it normally receives a value, it terminates the Kernel session.
   1563      (For example, if the system is running a read-eval-print loop, it
   1564      exits the loop.)
   1565 
   1566  -- Variable: error-continuation
   1567      The dynamic extent of this continuation is mutually disjoint from
   1568      the dynamic extent in which Kernel computation usually occurs
   1569      (such as the dynamic extent in which the Kernel system would run a
   1570      read-eval-print loop).
   1571 
   1572      When this continuation normally receives a value, it provides a
   1573      diagnostic message to the user of the Kernel system, on the
   1574      assumption that the received value is an attempt to describe some
   1575      error that aborted a computation; and then resumes operation of
   1576      the Kernel system at some point that is outside of all
   1577      user-defined computation. (For example, if the system is running a
   1578      read-eval-print loop, operation may resume by continuing from the
   1579      top of the loop.)
   1580 
   1581      The diagnostic message is not made available to any Kernel
   1582      computation, and is therefore permitted to contain information that
   1583      violates abstractions within the system.
   1584 
   1585      When an error is signaled during a Kernel computation, the
   1586      signaling action consists of an abnormal pass to some continuation
   1587      in the dynamic extent of `error-continuation'.
   1588 
   1589  -- Applicative: apply-continuation (apply-continuation continuation
   1590           object)
   1591      Applicative `apply-continuation' converts its first argument to an
   1592      applicative as if by `continuation->applicative', and then applies
   1593      it as usual.
   1594 
   1595      That is:
   1596           (apply-continuation continuation object) ==
   1597             (apply (continuation->applicative continuation) object)
   1598 
   1599  -- Operative: $let/cc ($let/cc <symbol> . <objects>)
   1600      A child environment `e' of the dynamic environment is created,
   1601      containing a binding of `<symbol>' to the continuation to which
   1602      the result of the call to `$let/cc' should normally return; then,
   1603      the subexpressions of `<objects>' are evaluated in `e' from left
   1604      to right, with the last (if any) evaluated as a tail context, or
   1605      if `<objects>' is empty the result is inert.
   1606 
   1607      That is:
   1608           ($let/cc symbol . objects) ==
   1609             (call/cc ($lambda (symbol) . objects))
   1610 
   1611  -- Applicative: guard-dynamic-extent (guard-dynamic-extent
   1612           entry-guards combiner exit-guards)
   1613      This applicative extends the current continuation with the
   1614      specified guards, and calls `combiner' in the dynamic extent of
   1615      the new continuation, with no operands and the dynamic environment
   1616      of the call to `guard-dynamic-extent'.
   1617 
   1618  -- Applicative: exit (exit [object])
   1619      Applicative `exit' initiates an abnormal transfer of `object' (or
   1620      `#inert' if `object' was not specified), to `root-continuation'.
   1621      That is:
   1622           (exit) == (apply-continuation root-continuation #inert)
   1623           (exit obj) == (apply-continuation root-continuation obj)
   1624 
   1625      SOURCE NOTE: This applicative doesn't have the optional argument in
   1626      the report.  It was added to klisp to allow a simple way to
   1627      terminate the interpreter passing a value that is then tried to
   1628      convert to an exit status.
   1629 
   1630 
   1631 File: klisp.info,  Node: Encapsulations,  Next: Promises,  Prev: Continuations,  Up: Top
   1632 
   1633 11 Encapsulations
   1634 *****************
   1635 
   1636 An encapsulation is an object that refers to another object, called its
   1637 content.  The Kernel data type encapsulation is encapsulated.  Two
   1638 encapsulations are `equal?' iff they are `eq?'.  Encapsulations are
   1639 immutable.
   1640 
   1641  -- Applicative: make-encapsulation-type (make-encapsulation-type)
   1642      Returns a list of the form `(e p? d)', where `e', `p'?, and `d'
   1643      are applicatives, as follows.  Each call to
   1644      `make-encapsulation-type' returns different applicatives `e',
   1645      `p?', and `d'.
   1646 
   1647         * `e' is an applicative that takes one argument, and returns a
   1648           fresh encapsulation with the argument as content.
   1649           Encapsulations returned on different occasions are not `eq?'.
   1650 
   1651         * `p?' is a primitive type predicate, that takes zero or more
   1652           arguments and returns true iff all of them are encapsulations
   1653           generated by `e'.
   1654 
   1655         * `d' is an applicative that takes one argument; if the
   1656           argument is not an encapsulation generated by `e', an error
   1657           is signaled, otherwise the content of the encapsulation is
   1658           returned.
   1659 
   1660      That is, the predicate `p?' only recognizes, and the decapsulator
   1661      `d' only extracts the content of, encapsulations created by the
   1662      encapsulator `e' that was returned by the same call to
   1663      `make-encapsulation-type'.
   1664 
   1665 
   1666 File: klisp.info,  Node: Promises,  Next: Keyed Variables,  Prev: Encapsulations,  Up: Top
   1667 
   1668 12 Promises
   1669 ***********
   1670 
   1671 A promise is an object that represents the potential to determine a
   1672 value.  The value may be the result of an arbitrary computation that
   1673 will not be performed until the value must be determined (constructor
   1674 `$lazy'); or, in advanced usage, the value may be determined before the
   1675 promise is constructed (constructor `memoize').
   1676 
   1677    The value determined by a promise is obtained by forcing it
   1678 (applicative `force').  A given promise cannot determine different
   1679 values on different occasions that it is forced.  Also, if a promise
   1680 determines its value by computation, and that computation has already
   1681 been completed, forcing the promise again will produce the previously
   1682 determined result without re-initiating the computation to determine it.
   1683 
   1684    The Kernel data type promise is encapsulated.
   1685 
   1686    The general rules for predicate `eq?' only require it to distinguish
   1687 promises if they can exhibit different behavior; the resulting leeway
   1688 for variation between implementations is similar, in both cause and
   1689 effect, to that for `eq?'-ness of operatives.  For example, if two
   1690 promises, constructed on different occasions, would perform the same
   1691 computation to determine their values, and that computation has no
   1692 side-effects and must always return the same value, the promises may or
   1693 may not be `eq?'.  Two promises are `equal?' iff they are `eq?'.
   1694 
   1695  -- Applicative: promise? (promise? . objects)
   1696      The primitive type predicate for type promise.  `promise?' returns
   1697      true iff all the objects in `objects' are of type promise.
   1698 
   1699  -- Applicative: force (force object)
   1700      If `object' is a promise, applicative `force' returns the value
   1701      determined by promise; otherwise, it returns `object'.
   1702 
   1703      The means used to force a promise depend on how the promise was
   1704      constructed.  The description of each promise constructor specifies
   1705      how to force promises constructed by that constructor.
   1706 
   1707  -- Operative: $lazy ($lazy expression)
   1708      Operative `$lazy' constructs and returns a new object of type
   1709      promise, representing potential evaluation of expression in the
   1710      dynamic environment from which `$lazy' was called.
   1711 
   1712      When the promise is forced, if a value has not previously been
   1713      determined for it, `expression' is evaluated in the dynamic
   1714      environment of the constructing call to `$lazy'.  If, when the
   1715      evaluation returns a result, a value is found to have been
   1716      determined for the promise during the evaluation, the result is
   1717      discarded in favor of the previously determined value; otherwise,
   1718      the result is forced, and the value returned by that forcing
   1719      becomes the value determined by the promise.
   1720 
   1721      Forcing an undetermined lazy promise (i.e., a promise constructed
   1722      by $lazy for which no value has yet been determined) may cause a
   1723      sequential series of evaluations, each of which returns a promise
   1724      that is forced and thus initiates the next evaluation in the
   1725      series.  The implementation must support series of this kind with
   1726      unbounded length (i.e., unbounded number of sequential
   1727      evaluations).
   1728 
   1729      Note that forcing concerns the value determined by a given promise,
   1730      not the result of evaluating a given expression in a given
   1731      environment. Distinct promises (judged by `eq?' represent
   1732      different occasions of evaluation; so, even if they do represent
   1733      evaluation of the same expression in the same environment, forcing
   1734      one does not necessarily determine the value for the other, and
   1735      actual evaluation will take place the first time each of them is
   1736      forced.
   1737 
   1738  -- Applicative: memoize (memoize object)
   1739      Applicative `memoize' constructs and returns a new object of type
   1740      promise, representing memoization of `object'.  Whenever the
   1741      promise is forced, it determines `object'.
   1742 
   1743  -- Operative: $delay ($delay <expression>)
   1744      Operative `delay' behaves as the composition of `$lazy' and
   1745      `memoize', that is:
   1746           ($delay <expr>) == ($lazy (memoize <expr>))
   1747      SOURCE NOTE: this is taken from r7rs.
   1748 
   1749 
   1750 File: klisp.info,  Node: Keyed Variables,  Next: Numbers,  Prev: Promises,  Up: Top
   1751 
   1752 13 Keyed Variables
   1753 ******************
   1754 
   1755 A keyed variable is a device that associates a non-symbolic key (in the
   1756 form of an accessor applicative) with a value depending on the context
   1757 in which lookup occurs.  Kernel provides two types of keyed variables:
   1758 dynamic & static.  Keyed Dynamic Variables use the dynamic extent as
   1759 context and Keyed Static Variables use the dynamic environment.
   1760 
   1761 13.1 Keyed Dynamic Variables
   1762 ============================
   1763 
   1764 A keyed dynamic variable is a device that associates a non-symbolic key
   1765 (in the form of an accessor applicative) with a value depending on the
   1766 dynamic extent in which lookup occurs.
   1767 
   1768  -- Applicative: make-keyed-dynamic-variable
   1769           (make-keyed-dynamic-variable)
   1770      Returns a list of the form `(b a)', where `b' and `a' are
   1771      applicatives, as follows.  Each call to
   1772      `make-keyed-dynamic-variable' returns different `b' and `a'.
   1773 
   1774         * `b' is an applicative that takes two arguments, the second of
   1775           which must be a combiner.  It calls its second argument with
   1776           no operands (nil operand tree) in a fresh empty environment,
   1777           and returns the result.
   1778 
   1779         * `a' is an applicative that takes zero arguments. If the call
   1780           to `a' occurs within the dynamic extent of a call to `b', then
   1781           `a' returns the value of the first argument passed to `b' in
   1782           the smallest enclosing dynamic extent of a call to `b'. If the
   1783           call to `a' is not within the dynamic extent of any call to
   1784           `b', an error is signaled.
   1785 
   1786 13.2 Keyed Static Variables
   1787 ===========================
   1788 
   1789 A keyed static variable is a device that binds data in an environment
   1790 by a non-symbolic key, where the key is an accessor applicative.
   1791 
   1792  -- Applicative: make-keyed-static-variable (make-keyed-static-variable)
   1793      Returns a list of the form `(b a)', where `b' and `a' are
   1794      applicatives, as follows.  Each call to
   1795      `make-keyed-static-variable' returns different `b' and `a'.
   1796 
   1797         * `b' is an applicative that takes two arguments, the second of
   1798           which must be an environment.  It constructs and returns a
   1799           child-environment of its second argument, with initially no
   1800           local bindings.
   1801 
   1802         * `a' is an applicative that takes zero arguments. If the
   1803           dynamic environment `e' of the call to a has an improper
   1804           ancestor that was constructed by a call to `b', then a
   1805           returns the value of the first argument passed to `b' in the
   1806           first such environment encountered by a depth-first traversal
   1807           of the improper ancestors of `e'. If `e' has no improper
   1808           ancestors constructed via `b', an error is signaled.
   1809 
   1810 
   1811 File: klisp.info,  Node: Numbers,  Next: Strings,  Prev: Keyed Variables,  Up: Top
   1812 
   1813 14 Numbers
   1814 **********
   1815 
   1816 All numbers are immutable, and `equal?' iff `eq?'.  The number type is
   1817 encapsulated.
   1818 
   1819    The external representation of an undefined number is `#undefined'.
   1820 The external representation of a real with no primary value is `#real'
   1821 (but this may change in the future, the report is missing the output
   1822 representation for reals with no primary values).  All other rules for
   1823 externally representing numbers pertain only to defined numbers with
   1824 primary values.
   1825 
   1826    An external representation of a real number consists of optional
   1827 radix and/or exactness prefixes, optional sign (`+' or `-'), and
   1828 magnitude. The radix prefixes are `#b' (binary), `#o' (octal), `#d'
   1829 (decimal), and `#x' (hexadecimal); the default is decimal.  The
   1830 exactness prefixes are `#e' (exact) and `#i' (inexact); by default, the
   1831 number is inexact iff the magnitude representation uses floating point.
   1832 If both kinds of prefixes are used, they may occur in either order. The
   1833 magnitude is either `infinity'; an unsigned integer (nonempty sequence
   1834 of digits); a ratio of unsigned integers (two unsigned integers with a
   1835 `/' between, of which the second is non-zero); or a floating point
   1836 representation.  If the magnitude is `infinity', there must be an
   1837 exactness prefix and a sign, and no radix prefix.  Floating point
   1838 representation can only be used with decimal radix; it consists of
   1839 nonempty integer part, point (`.'), nonempty fraction part, and
   1840 optional exponent part.  The optional exponent part consists of an
   1841 exponent letter, and an (optionally signed) integer indicating a power
   1842 of ten by which to multiply the magnitude.  The choice of exponent
   1843 letter makes no difference in what mathematical number is indicated by
   1844 the external representation, but does indicate internal representation
   1845 precision. Exponent letters `s', `f', `d', `f' indicate preference for
   1846 successively higher internal precision - short, float, double, long.
   1847 When reading an inexact real number, exponent letter `e' accepts the
   1848 default internal precision, which must be at least double.  When
   1849 writeing an inexact real number, exponent letter `e' may be used for
   1850 the default internal precision, and must be used for any internal
   1851 number format not indicated by any of the other exponent letters.
   1852 Float and double must provide, respectively, at least as much precision
   1853 as IEEE 32-bit and 64-bit floating point standards [IE85].  For
   1854 example, `#i#xa/c' represents an inexact number using hexadecimal
   1855 notation, with signed magnitude positive five sixths (ten over twelve).
   1856 `-3.5l-2' represents an inexact number using decimal notation, with
   1857 signed magnitude negative thirty five thousandths, and requested long
   1858 precision (which must be at least IEEE 64-bit floating point).  When
   1859 reading an external representation of an inexact real, the bounds on
   1860 the resulting inexact number are chosen in accordance with the
   1861 narrow-arithmetic keyed dynamic variable.
   1862 
   1863    NOTE: in klisp, all inexact numbers are stored as IEEE 64-bit
   1864 floating point.  No bounding or robustness info is kept.
   1865 
   1866  -- Applicative: number? (number? . objects)
   1867      The primitive type predicate for type number.  `number?' returns
   1868      true iff all the objects in `objects' are of type number.
   1869 
   1870  -- Applicative: integer? (integer? . objects)
   1871      The primitive type predicate for number subtype integer.
   1872      `integer?'  returns true iff all the objects in `objects' are of
   1873      type integer.
   1874 
   1875  -- Applicative: exact-integer? (exact-integer? . objects)
   1876      The primitive type predicate for number subtype exact integer.
   1877      `exact-integer?'  returns true iff all the objects in `objects'
   1878      are of type integer and exact.
   1879 
   1880      SOURCE NOTE: this is from r7rs.
   1881 
   1882  -- Applicative: u8? (u8? . objects)
   1883      The primitive type predicate for number subtype exact integer
   1884      between 0 and 255.  This is the subtype used in bytevectors.  `u8?'
   1885      returns true iff all the objects in `objects' are of type integer,
   1886      are exact, and lie between 0 and 255 inclusive.
   1887 
   1888      SOURCE NOTE: this is handy for use with bytevectors.
   1889 
   1890  -- Applicative: rational? (rational? . objects)
   1891      The primitive type predicate for number subtype rational.
   1892      `rational?'  returns true iff all the objects in `objects' are of
   1893      type rational.
   1894 
   1895  -- Applicative: real? (real? . objects)
   1896      The primitive type predicate for number subtype real.  `real?'
   1897      returns true iff all the objects in `objects' are of type real.
   1898 
   1899  -- Applicative: finite? (finite? . numbers)
   1900      Predicate `finite?' returns true iff all the numbers in `numbers'
   1901      are finite.
   1902 
   1903  -- Applicative: exact? (exact? . numbers)
   1904      Predicate `exact?' returns true iff all the numbers in `numbers'
   1905      are exact.
   1906 
   1907  -- Applicative: inexact? (inexact? . numbers)
   1908      Predicate `inexact?' returns true iff all the numbers in `numbers'
   1909      are inexact.
   1910 
   1911  -- Applicative: robust? (robust? . numbers)
   1912      Predicate `robust?' returns true iff all the numbers in `numbers'
   1913      are robust.
   1914 
   1915  -- Applicative: undefined? (undefined? . numbers)
   1916      Predicate `undefined?' returns true iff all the numbers in
   1917      `numbers' are undefined.
   1918 
   1919  -- Applicative: =? (=? . numbers)
   1920      Applicative `=?' is a predicate that returns true iff all its
   1921      arguments are numerically equal to each other.  If any of its
   1922      arguments has no primary value, an error is signaled.
   1923 
   1924  -- Applicative: <? (<? . reals)
   1925  -- Applicative: <=? (<=? . reals)
   1926  -- Applicative: >? (>? . reals)
   1927  -- Applicative: >=? (>=? . reals)
   1928      Each of these applicatives is a predicate that returns true iff
   1929      every two consecutive elements of `reals' have primary values in
   1930      the order indicated by the name of the applicative.  If any
   1931      element of `reals' has no primary value, an error is signaled.
   1932 
   1933  -- Applicative: + (+ . numbers)
   1934      Applicative `+' returns the sum of the elements of numbers.  If
   1935      numbers is empty, the sum of its elements is exact zero.  If a
   1936      positive infinity is added to a negative infinity, the result has
   1937      no primary value.  If all the elements of a cycle are zero, the
   1938      sum of the cycle is zero.  If the acyclic sum of the elements of a
   1939      cycle (i.e., the sum of an acyclic list containing just those
   1940      elements) is non-zero, the sum of the cycle is positive infinity
   1941      times the acyclic sum of the elements.  If the acyclic sum of the
   1942      elements of a cycle is zero, but some of the elements of the cycle
   1943      are non-zero, the sum of the cycle has no primary value.
   1944 
   1945  -- Applicative: * (* . numbers)
   1946      Applicative `*' returns the product of the elements of numbers.
   1947      If numbers is empty, the product of its elements is exact one.  If
   1948      an infinity is multiplied by zero, the result has no primary
   1949      value.  If the acyclic product of the elements of a cycle is real
   1950      greater than one, the product of the cycle is positive infinity.
   1951      If all the elements of a cycle are positive one, the product of
   1952      the cycle is positive one.  If the acyclic product of the elements
   1953      of a cycle is positive one, but some of the elements of the cycle
   1954      are not positive one, the product of the cycle has no primary
   1955      value.  If the acyclic product of the elements of a cycle has
   1956      magnitude less than one, the product of the cycle is zero.  If the
   1957      acyclic product of the elements of a cycle has magnitude greater
   1958      than or equal to one, and is not positive real, the product of the
   1959      cycle has no primary value.
   1960 
   1961  -- Applicative: - (- number . numbers)
   1962      `numbers' should be a nonempty list of numbers.
   1963 
   1964      Applicative `-' returns the sum of `number' with the negation of
   1965      the sum of `numbers'.
   1966 
   1967  -- Applicative: zero? (zero? . numbers)
   1968      Applicative `zero?' is a predicate that returns true iff every
   1969      element of `numbers' is zero.  For this purpose, a real number is
   1970      zero if its primary value is zero.  If any element of numbers has
   1971      no primary value an error is signaled.
   1972 
   1973  -- Applicative: div (div real1 real2)
   1974  -- Applicative: mod (mod real1 real2)
   1975  -- Applicative: div-and-mod (div-and-mod real1 real2)
   1976      For all three applicatives, if `real1' is infinite or `real2' is
   1977      zero, an error is signaled.
   1978 
   1979      Let `n' be the greatest integer such that `real2 * n <= real1'.
   1980      Applicative `div' returns `n'.  Applicative `mod' returns `real1 -
   1981      (real2 * n)'.  Applicative `div-and-mod' returns a freshly
   1982      allocated list of length two, whose first element is `n' and whose
   1983      second element is `real1 - (real2 * n)'.
   1984 
   1985      NOTE: I'm not really sure about this description...
   1986 
   1987  -- Applicative: div0 (div0 real1 real2)
   1988  -- Applicative: mod0 (mod0 real1 real2)
   1989  -- Applicative: div0-and-mod0 (div0-and-mod0 real1 real2)
   1990      For all three applicatives, if `real1' is infinite or `real2' is
   1991      zero, an error is signaled.
   1992 
   1993      Let `n' be the greatest integer such that `real2 * n <= real1 +
   1994      |real2/2|'.  Applicative `div0' returns `n'.  Applicative `mod0'
   1995      returns `real1 - (real2 * n)'.  Applicative `div0-and-mod0'
   1996      returns a freshly allocated list of length two, whose first
   1997      element is `n' and whose second element is `real1 - (real2 * n)'.
   1998 
   1999      NOTE: I'm not really sure about this description...
   2000 
   2001  -- Applicative: positive? (positive? . reals)
   2002  -- Applicative: negative? (negative? . reals)
   2003      Applicative `positive?' is a predicate that returns true iff every
   2004      element of `reals' is greater than zero. Applicative `negative?'
   2005      is a predicate that returns true iff every element of `reals' is
   2006      less than zero.  If any argument to either applicative has no
   2007      primary value an error is signaled.
   2008 
   2009  -- Applicative: odd? (odd? . integers)
   2010  -- Applicative: even? (even? . integers)
   2011      Applicative `odd?' is a predicate that returns true iff every
   2012      element of `integers' is odd.  Applicative `even?' is a predicate
   2013      that returns true iff every element of `integers' is even.  If any
   2014      argument to either applicative has no primary value an error is
   2015      signaled.
   2016 
   2017  -- Applicative: abs (abs real)
   2018      Applicative `abs' returns the nonnegative real number with the
   2019      same magnitude as `real'; that is, if `real' is nonnegative it
   2020      returns `real', otherwise it returns the negation of `real'.
   2021 
   2022  -- Applicative: max (max . reals)
   2023  -- Applicative: min (min . reals)
   2024      If `reals' is nil, applicative `max' returns exact negative
   2025      infinity, and applicative `min' returns exact positive infinity.
   2026      If `reals' is non-nil, applicative `max' returns the largest
   2027      number in `reals', and applicative `min' returns the smallest
   2028      number in `reals'.
   2029 
   2030  -- Applicative: lcm (lcm . impints)
   2031  -- Applicative: gcd (gcd . impints)
   2032      `impints' should be a list of improper integers, that is, real
   2033      numbers each of which is either an integer or an infinity.
   2034 
   2035      Applicative `lcm' returns the smallest positive improper integer
   2036      that is an improper0integer multiple of every element of `impints'
   2037      (that is, smallest `n >= 1' such that for every argument `nk'
   2038      there exists `n'k' with `nk * n'k = n').  If any of the arguments
   2039      is zero, the result of `lcm' has no primary value.  According to
   2040      these rules, `lcm' with nil argument list returns `1', and `lcm'
   2041      with any infinite argument returns positive infinity.
   2042 
   2043      Applicative `gcd' returns the largest positive improper integer
   2044      such that every element of `impints' is an improper-integer
   2045      multiple of it (that is, largest `n >= 1' such that for every
   2046      argument `nk' there exists `n'k' with `n * n'k = nk').  `gcd' with
   2047      nil argument list returns exact positive infinity.  If `gcd' is
   2048      called with one or more arguments, and at least one of the
   2049      arguments is zero, but none of the arguments is a non-zero finite
   2050      integer, its result has no primary value.  According to these
   2051      rules, if `gcd' is called with at least one finite non-zero
   2052      argument, its result is the same as if all zero and infinite
   2053      arguments were deleted.
   2054 
   2055  -- Applicative: get-real-internal-bounds (get-real-internal-bounds
   2056           real)
   2057  -- Applicative: get-real-exact-bounds (get-real-exact-bounds real)
   2058      Applicative `get-real-internal-bounds' returns a freshly allocated
   2059      list of reals `(x1 x2)', where the primary value of `x1' is the
   2060      lower bound of `real', using the same internal representation as
   2061      the primary value of `real', and the primary value of `x2' is the
   2062      upper bound of `real', using the same internal representation as
   2063      the primary value of `real'.  The `xk' are inexact iff real is
   2064      inexact.  The `xk' are robust (i.e., tagged if the implementation
   2065      supports such), and the bounds of each `xk' are only required to
   2066      contain its primary value (i.e., the implementation is allowed to
   2067      make the bounds equal to the primary value).
   2068 
   2069      Applicative `get-real-exact-bounds' returns a freshly allocated
   2070      list of exact reals `(x1 x2)', where `x1' is not greater than the
   2071      lower bound of `real', and `x2' is not less than the upper bound
   2072      of `real'.
   2073 
   2074  -- Applicative: get-real-internal-primary (get-real-internal-primary
   2075           real)
   2076  -- Applicative: get-real-exact-primary (get-real-exact-primary real)
   2077      If `real' is exact, both applicatives return `real'.  If `real'
   2078      has no primary value, both applicatives signal an error.
   2079 
   2080      If `real' is inexact with a primary value, applicative
   2081      `get-real-internal-primary' returns a real number `x0' whose
   2082      primary value is the same as, and has the same internal format as,
   2083      the primary value of `real'.  `x0' is robust, and its bounds are
   2084      only required to contain its primary value.
   2085 
   2086      If `real' is inexact with a primary value, applicative
   2087      `get-real-exact-primary' returns an exact real number `x0' within
   2088      the exact bounds that would be returned for `real' by applicative
   2089      `get-real-exact-bounds'.  Preferably, `x0' should be as close to
   2090      the primary value of `real' as the implementation can reasonably
   2091      arrange. If the implementation does not support any exact `real'
   2092      that reasonably approximates `real', an error may be signaled.
   2093 
   2094  -- Applicative: make-inexact (make-inexact real1 real2 real3)
   2095      Applicative `make-inexact' returns an inexact real number, as
   2096      follows.  If `real2' is inexact, the result has the same primary
   2097      value as `real2'; and if `real2' has no primary value, the result
   2098      has no primary value.  The result has the same robustness as
   2099      `real2'.  If possible, the result uses the same internal
   2100      representation as `real2'.  If `real2' is exact, the primary value
   2101      of the result is as close to `real2' as the implementation can
   2102      reasonably arrange; overflow and underflow are handled as
   2103      described in ....  The lower bound of the result is no greater than
   2104      the lower bound of `real1', the primary value of `real2', and the
   2105      primary value of the result.  The upper bound of the result is no
   2106      less than the upper bound of `real3', the primary value of
   2107      `real2', and the primary value of the result.
   2108 
   2109  -- Applicative: real->inexact (real->inexact real)
   2110  -- Applicative: real->exact (real->exact real)
   2111      Applicative `real->exact' behaves just as `get-real-exact-primary'.
   2112 
   2113      If `real' is inexact, applicative `real->inexact' returns `real'.
   2114      If `real' is exact, applicative `real->inexact' returns an inexact
   2115      real `x0' such that `real' would be a permissible result of
   2116      passing `x0' to `real->exact'.  If the implementation does not
   2117      support any such `x0', an error may be signaled.  Otherwise, `x0'
   2118      is robust, and its bounds are only required to contain its primary
   2119      value and `real'.
   2120 
   2121  -- Applicative: with-strict-arithmetic (with-strict-arithmetic boolean
   2122           combiner)
   2123  -- Applicative: get-string-arithmetic (get-strict-arithmetic?)
   2124      These applicatives are the binder and accessor of the
   2125      `strict-arithmetic' keyed dynamic variable.  When this keyed
   2126      variable is true, various survivable but dubious arithmetic events
   2127      signal an error - notably, operation results with no primary value,
   2128      and over- and underflows.
   2129 
   2130  -- Applicative: / (/ number . numbers)
   2131      `numbers' should be a nonempty list of numbers.
   2132 
   2133      Applicative `/' returns `number' divided by the product of
   2134      `numbers'.  If the product of `numbers' is zero, an error is
   2135      signaled.  If `number' is infinite and the product of `numbers' is
   2136      infinite, an error is signaled.
   2137 
   2138  -- Applicative: numerator (numerator rational)
   2139  -- Applicative: denominator (denominator rational)
   2140      These applicatives return the numerator and denominator of
   2141      `rational', in least terms (i.e., chosen for the least positive
   2142      denominator).  Note that if `rational' is inexact, and either of
   2143      its bounds is not its primary value, the denominator has upper
   2144      bound positive infinity, and the numerator must have at least one
   2145      infinite bound (two infinite bounds if the bounds of rational
   2146      allow values of both signs).
   2147 
   2148  -- Applicative: floor (floor real)
   2149  -- Applicative: ceiling (ceiling real)
   2150  -- Applicative: truncate (truncate real)
   2151  -- Applicative: round (round real)
   2152      Applicative `floor' returns the largest integer not greater than
   2153      `real'.
   2154 
   2155      Applicative `ceiling' returns the smallest integer not less than
   2156      `real'.
   2157 
   2158      Applicative `truncate' returns the integer closest to `real' whose
   2159      absolute value is not greater than that of `real'.
   2160 
   2161      Applicative `round' returns the closest integer to `real',
   2162      rounding to even when `real' is halfway between two integers.
   2163 
   2164  -- Applicative: rationalize (rationalize real1 real2)
   2165  -- Applicative: simplest-rational (simplest-rational real1 real2)
   2166      A rational number `r1' is simpler than another rational `r2' if
   2167      `r1 = p1 / q1' and `r2 = p2 / q2', both in lowest terms, and `|p1|
   2168      <= |p2|' and `|q1| <= |q2|'. Thus `3/5' is simpler than `4/7'. Not
   2169      all rationals are comparable in this ordering, as for example
   2170      `2/7' and `3/5'.  However, any interval (that contains rational
   2171      numbers) contains a rational number that is simpler than every
   2172      other rational number in that interval.  Note that `0 = 0/1' is
   2173      simpler than any other rational (so that one never has to choose
   2174      between `p/q' and `−p/q').
   2175 
   2176      For applicative `simplest-rational', let `x0' be the simplest
   2177      rational mathematically not less than the primary value of `real1'
   2178      and not greater than the primary value of `real2'.  If no such
   2179      `x0' exists (because the primary value of `real1' is greater, or
   2180      because the primary values of the arguments are equal and
   2181      irrational), or if either argument does not have a primary value,
   2182      an error is signaled.
   2183 
   2184      For applicative `rationalize', let `x0' be the simplest rational
   2185      mathematical number within the interval bounded by the primary
   2186      value of `real1' plus and minus the primary value of `real2'.  If
   2187      no such `x0' exists (because the primary value of `real1' is
   2188      irrational and the primary value `real2' is zero), or if either
   2189      argument does not have a primary value, an error is signaled.
   2190 
   2191      If `real1' and `real2' are exact, the applicative (whichever it
   2192      is) returns exact `x0'.  If one or both of `real1' and `real2' are
   2193      inexact, the applicative returns an inexact rational approximating
   2194      `x0' (as by `real->inexact'.  Note that an inexact result returned
   2195      is not necessarily bounded by the primary values of the arguments;
   2196      but the result is an approximation of `x0', which is so bounded,
   2197      and the bounds of the result include `x0'.
   2198 
   2199  -- Applicative: sqrt (sqrt number)
   2200      If `number' is negative, the result is undefined.
   2201 
   2202      Applicative `sqrt' returns the positive square root of number.
   2203      The result may be inexact even if `number' is exact and the square
   2204      root is rational.
   2205 
   2206  -- Applicative: expt (expt number1 number2)
   2207      Applicative `expt' returns `number1' to the power of `number2'.
   2208      If `number1' is zero, then the result is 1 if `number2' is zero
   2209      and 0 otherwise.
   2210 
   2211  -- Applicative: exp (exp number)
   2212  -- Applicative: log (log number)
   2213  -- Applicative: sin (sin number)
   2214  -- Applicative: cos (cos number)
   2215  -- Applicative: tan (tan number)
   2216  -- Applicative: asin (asin number)
   2217  -- Applicative: acos (acos number)
   2218  -- Applicative: atan (atan number1 [number2])
   2219      These applicatives compute the usual transcendental functions.
   2220      `log' computes the natural logarithm (not the base-10 logarithm).
   2221      The two argument version of `atan' computes `(angle
   2222      (make-recutangular number1 number2))' even thou klisp doesn't
   2223      support complex numbers.
   2224 
   2225      All results may be inexact even if `number' is exact and the
   2226      result of the transcendental function is rational.  TODO add
   2227      intervals returned for multidefined functions (inverses and log)
   2228 
   2229  -- Applicative: string->number (string->number string [radix])
   2230      `radix' should be an exact integer, either 2, 8, 10, or 16.
   2231      `string' should be a string describing a number in the specified
   2232      radix, but may contain a radix prefix to override it.  The default
   2233      `radix', if not supplied, is 10.
   2234 
   2235      Applicative `string->number' returns the best approximation of the
   2236      number represented by `string'.  If `string' is not a valid
   2237      representation of a number in the given `radix' an error is
   2238      signaled.
   2239 
   2240      Examples:
   2241           (string->number "100") => 100
   2242           (string->number "100" 16) => 256
   2243           (string->number "#o100" 2) => 64
   2244           (string->number "1.0") => 1.0
   2245 
   2246      SOURCE NOTE: this is taken from r7rs.
   2247 
   2248  -- Applicative: number->string (number->string number [radix])
   2249      `radix' should be an exact integer, either 2, 8, 10, or 16.  The
   2250      default `radix', if not supplied, is 10.
   2251 
   2252      Applicative `number->string' returns a string representing
   2253      `number' in the given `radix'.  No radix prefix is present in the
   2254      returned string.  If an inexact number is passed together with a
   2255      radix other from 10, an error is signaled.
   2256 
   2257      The returned string is such that
   2258           (string->number (number->string number radix) radix) == number
   2259 
   2260      Examples:
   2261           (number->string 100) => "100"
   2262           (number->string 256 16) => "100"
   2263           (number->string 1.0) => "1.0"
   2264 
   2265      SOURCE NOTE: this is taken from r7rs.
   2266 
   2267 
   2268 File: klisp.info,  Node: Strings,  Next: Characters,  Prev: Numbers,  Up: Top
   2269 
   2270 15 Strings
   2271 **********
   2272 
   2273 A string is an object that represent a sequence of characters (for now,
   2274 only ASCII is supported in klisp, in the future, full UNICODE will be
   2275 supported).  The external representation of strings consists of a
   2276 leading """, the characters of the string and a closing """.  Both
   2277 double quote and backslash should be escaped to appear withing strings.
   2278 Some other characters also have an escaped form for convenience.  All
   2279 of these are written with a leading slash ("\").  In klisp these are:
   2280 double quote ("\""), backslash ("\\"), null ("\0"), alarm ("\a"),
   2281 backspace ("\b"), tab ("\t"), newline ("\n"), return ("\r"), vertical
   2282 tab ("\v"), and formfeed ("\f").  You can also use inline hex escapes
   2283 to include arbitary unicode codepoints (only ASCII range supported for
   2284 now).  The syntax is "\x<hex codepoint>;".  New lines can be escaped to
   2285 simplify the accomodation of literal strings in source code, to do
   2286 this: use "\" followed by any ammount of intraline whitespace, a new
   2287 line and another ammount of intraline whitespace.  All of that intraline
   2288 whitespace and the newline, together with the leading slash is
   2289 discarded by the reader and doesn't end up in the string being read.
   2290 
   2291    A string has a length that is fixed at creation time, and as many
   2292 characters, indexed from `0' to `length-1'.
   2293 
   2294    Strings may be mutable or immutable.  If an attempt is made to
   2295 mutate an immutable string, an error is signaled.  Two immutable
   2296 strings are "eq?" iff they are "equal?".  Two mutable strings are "eq?"
   2297 if they were created by the same constructor call.  Two mutable strings
   2298 are "equal?" iff they are "string=?".  For now it is undefined if a
   2299 mutable and an immutable strings that are "string=?" are "equal?" or
   2300 not.  The only exception is the empty string.  There is only one empty
   2301 string (all empty strings are "eq?"  to each other) and it should be
   2302 considered immutable.  Even if an attempt is made to return a new empty
   2303 string (like calling `(string)', the canonical immutable empty string
   2304 is returned.  The string type is encapsulated.
   2305 
   2306    SOURCE NOTE: This section is still missing from the report.  The
   2307 features defined here were taken mostly from r7rs scheme.  It is
   2308 possible that in the future, klisp only admits immutable strings (like
   2309 lua and java), and that operations for contructing strings are moved to
   2310 a new type (like Java's StringBuilder/StringBuffer).  But for now,
   2311 compatibility with r7rs was preferred/simpler.
   2312 
   2313  -- Applicative: string? (string? . objects)
   2314      The primitive type predicate for type string.  `string?' returns
   2315      true iff all the objects in `objects' are of type string.
   2316 
   2317  -- Applicative: immutable-string? (immutable-string? objects)
   2318  -- Applicative: mutable-string? (mutable-string? objects)
   2319      The primitive type predicates for types immutable string and
   2320      mutable string.  These return true iff all the objects in
   2321      `objects' are of type immutable string or mutable string
   2322      respectively.
   2323 
   2324      SOURCE NOTE: these aren't provided in the Kernel report, but added
   2325      for convenience.  These can be implemented in standard kernel by
   2326      using guards.
   2327 
   2328  -- Applicative: string=? (string=? . strings)
   2329  -- Applicative: string<? (string<? . strings)
   2330  -- Applicative: string<=? (string<=? . strings)
   2331  -- Applicative: string>? (string>? . strings)
   2332  -- Applicative: string>=? (string>=? . strings)
   2333      These predicates compare any number of strings by their
   2334      lexicographic order.
   2335 
   2336  -- Applicative: string-ci=? (string-ci=? . strings)
   2337  -- Applicative: string-ci<? (string-ci<? . strings)
   2338  -- Applicative: string-ci<=? (string-ci<=? . strings)
   2339  -- Applicative: string-ci>? (string-ci>? . strings)
   2340  -- Applicative: string-ci>=? (string-ci>=? . strings)
   2341      These predicates convert the strings to lowercase and then compare
   2342      them using their lexicographic order.
   2343 
   2344  -- Applicative: make-string (make-string k [char])
   2345      Applicative `make-string' constructs and returns a new mutable
   2346      string of length `k'.  If `char' is specified, then all characters
   2347      in the returned string are `char', otherwise the content of the
   2348      string is unspecified.
   2349 
   2350  -- Applicative: string (string . chars)
   2351      Applicative `string' contructs and return a new mutable string
   2352      composed of the character arguments.
   2353 
   2354  -- Applicative: string-length (string-length string)
   2355      Applicative `string-length' returns the length of `string'.
   2356 
   2357  -- Applicative: string-ref (string-ref string k)
   2358      Applicative `string-ref' returns the character of `string' at
   2359      position `k'.  If `k' is out of bounds (i.e. less than `0' or
   2360      greater or equal than `(string-length string)') an error is
   2361      signaled.
   2362 
   2363  -- Applicative: string-set! (string-set! string k char)
   2364      Applicative `string-set!' replaces the character with index `k' in
   2365      `string' with character `char'.  If `k' is out of bounds, or
   2366      `string' is immutable, an error is signaled.
   2367 
   2368  -- Applicative: string-fill! (string-fill! string char)
   2369      Applicative `string-fill!' replaces all the characters in `string'
   2370      with character `char'.  If `string' is an immutable string, an
   2371      error is signaled.
   2372 
   2373  -- Applicative: substring (substring string k1 k2)
   2374      Both `k1' & `k2-1' should be valid indexes in `string'.  Also it
   2375      should be the case that `k1 <= k2'.
   2376 
   2377      Applicative `substring' constructs and returns a new mutable
   2378      string with length `k2 - k1', with the characters from `string',
   2379      starting at index `k1' (inclusive) and ending at index `k2'
   2380      (exclusive).
   2381 
   2382  -- Applicative: string-append (string-append . strings)
   2383      Applicative `string-append' constructs and returns a new mutable
   2384      string consisting of the concatenation of all its arguments.
   2385 
   2386  -- Applicative: string-copy (string-copy string)
   2387      Applicative `string-copy' constructs and returns a new mutable
   2388      string with the same length and characters as `string'.
   2389 
   2390  -- Applicative: string->immutable-string (string->immutable-string
   2391           string)
   2392      Applicative `string->immutable-string' constructs and returns a
   2393      new immutable string with the same length and characters as
   2394      `string'.
   2395 
   2396  -- Applicative: string->list (string->list string)
   2397  -- Applicative: list->string (list->string chars)
   2398  -- Applicative: string->vector (string->vector string)
   2399  -- Applicative: vector->string (vector->string vchars)
   2400  -- Applicative: string->bytevector (string->bytevector string)
   2401  -- Applicative: bytevector->string (bytevector->string bvchars)
   2402      These applicatives convert between strings and list of characters,
   2403      vectors of characters, and bytevectors of characters.  The objects
   2404      returned by these applicatives are always mutable.
   2405 
   2406  -- Applicative: string-upcase (string-upcase string)
   2407  -- Applicative: string-downcase (string-downcase string)
   2408  -- Applicative: string-titlecase (string-titlecase string)
   2409  -- Applicative: string-foldcase (string-foldcase string)
   2410      These applicatives perform the respective case folding on the
   2411      passed `string' and return a new mutable strings as a result.  The
   2412      original `string' is not modified.  For now in klisp only ASCII is
   2413      implemented, and so `string-foldcase' is the same as
   2414      `string-downcase'.
   2415 
   2416 
   2417 File: klisp.info,  Node: Characters,  Next: Ports,  Prev: Strings,  Up: Top
   2418 
   2419 16 Characters
   2420 *************
   2421 
   2422 A character is an object that represents an ASCII character (for now,
   2423 only ASCII is supported in klisp, in the future, full UNICODE will be
   2424 supported).
   2425 
   2426    The external representation of characters consists of a leading "#\"
   2427 and the character or character name or "#\x" followed by the hex
   2428 unicode code point (only ASCII supported for now).  The supported names
   2429 for now are "null", "alarm", "backspace", "tab", "newline", "return",
   2430 "escape", "space", "delete", "vtab", and "formfeed" (this is a
   2431 combination of the ones accepted in r6rs and r7rs).
   2432 
   2433    Characters are immutable.  The character type is encapsulated.
   2434 
   2435    SOURCE NOTE: This section is still missing from the report.  The
   2436 features defined here were taken mostly from r7rs.
   2437 
   2438  -- Applicative: char? (char? . objects)
   2439      The primitive type predicate for type character.  `char?' returns
   2440      true iff all the objects in `objects' are of type character.
   2441 
   2442  -- Applicative: char=? (char=? . chars)
   2443  -- Applicative: char<? (char<? . chars)
   2444  -- Applicative: char<=? (char<=? . chars)
   2445  -- Applicative: char>? (char>? . chars)
   2446  -- Applicative: char>=? (char>=? . chars)
   2447      These predicates compare any number of characters using their
   2448      ASCII value for the comparison.
   2449 
   2450  -- Applicative: char-ci=? (char-ci=? . chars)
   2451  -- Applicative: char-ci<? (char-ci<? . chars)
   2452  -- Applicative: char-ci<=? (char-ci<=? . chars)
   2453  -- Applicative: char-ci>? (char-ci>? . chars)
   2454  -- Applicative: char-ci>=? (char-ci>=? . chars)
   2455      These predicates convert the chars to lowercase and then compare
   2456      their ASCII values.
   2457 
   2458  -- Applicative: char-alphabetic? (char-alphabetic? . chars)
   2459  -- Applicative: char-numeric? (char-numeric? . chars)
   2460  -- Applicative: char-whitespace? (char-whitespace? . chars)
   2461      These predicates return true iff all of their arguments are
   2462      respectively "alphabetic", "numeric", or "whitespace".
   2463 
   2464  -- Applicative: char-upper-case? (char-upper-case? . chars)
   2465  -- Applicative: char-lower-case? (char-lower-case? . chars)
   2466  -- Applicative: char-title-case? (char-title-case? . chars)
   2467      These predicates return true iff all of their arguments are
   2468      respectively "upper case, "lower case", or "title case".
   2469 
   2470      Currently klisp only supports ASCII, so there are no title-cased
   2471      characters (i.e. `char-title-case?' always returns false).
   2472 
   2473  -- Applicative: char-upcase (char-upcase char)
   2474  -- Applicative: char-downcase (char-downcase char)
   2475  -- Applicative: char-titlecase (char-downcase char)
   2476  -- Applicative: char-foldcase (char-downcase char)
   2477      These applicatives return a character `char2' so that:
   2478           (char-ci=? char char2) => #t
   2479 
   2480      If `char' is alphabetic then the following holds:
   2481 
   2482           (char-upper-case? (char-upcase char)) => #t
   2483           (char-lower-case? (char-downcase char)) => #t
   2484 
   2485      Currently klisp only supports ASCII, so `char-foldcase' behaves as
   2486      `char-downcase' and `char-titlecase' behaves as `char-upcase'.
   2487 
   2488  -- Applicative: char->integer (char->integer char)
   2489  -- Applicative: integer->char (integer->char k)
   2490      These applicatives convert between ASCII values (as exact integers
   2491      between 0 and 127) and characters.  If an integer that is out of
   2492      range for ASCII characters is passed to `integer->char', an error
   2493      is signaled.
   2494 
   2495  -- Applicative: char-digit? (char-digit? char [base])
   2496      `base' must be an exact integer, between 2 and 36, it omitted it
   2497      defaults to `10'.
   2498 
   2499      Applicative `char-digit?' is a predicate that returns true iff
   2500      `char' is a digit in base `base'.  If `base' is greater than 10,
   2501      then either upper case or lower case letters can be used.
   2502 
   2503      SOURCE NOTE:  This is like char-numeric? but with bases other than
   2504      10.
   2505 
   2506  -- Applicative: char->digit (char->digit char [base])
   2507  -- Applicative: digit->char (digit->char digit [base])
   2508      `base' must be an exact integer, between 2 and 36, it omitted it
   2509      defaults to `10'.  In `char->digit', `char' should be a character
   2510      such that
   2511           (char-digit? char base) => #t
   2512      In `digit->char', `digit' should be an exact integer such that
   2513           (>=? (- base 1) digit 0) => #t
   2514 
   2515      These two applicatives convert between chars representing digits
   2516      and the corresponding integer values, in arbitrary bases (between
   2517      2 and 36).
   2518 
   2519      `char->digit' accepts either lower or upper case characters (if
   2520      the base is greater than 10), `digit->char' always returns lower
   2521      characters (or numbers of course).
   2522 
   2523      SOURCE NOTE: These are like r7rs digit-value but augmented with a
   2524      base argument.
   2525 
   2526 
   2527 File: klisp.info,  Node: Ports,  Next: Vectors,  Prev: Characters,  Up: Top
   2528 
   2529 17 Ports
   2530 ********
   2531 
   2532 A port is an object that mediates data from an input or to a
   2533 destination.  In the former case, the port is an input port, in the
   2534 latter case, an output port.  The data itself can consist of either
   2535 characters or bytes.  In the former case the port is a textual port and
   2536 in the latter case, a binary port.
   2537 
   2538    There are three textual ports open, binded by dynamic variables, one
   2539 for standard input, output, and error.
   2540 
   2541    Although ports are not considered immutable, none of the operations
   2542 on ports described in this section constitute mutation.  Ports are
   2543 `equal?' iff `eq?'.  The port type is encapsulated.
   2544 
   2545    An auxiliary data type used to signal the end of file was reached is
   2546 `eof'. The eof type consists of a single immutable value, having an
   2547 output only external representation (so that it can never be the normal
   2548 result of a call to read).  The eof type is encapsulated.
   2549 
   2550    SOURCE NOTE:  the eof type is not in the Kernel report, it is used in
   2551 klisp and was taken from r7rs.
   2552 
   2553  -- Applicative: port? (port? . objects)
   2554      The primitive type predicate for type port.  `port?'  returns true
   2555      iff all the objects in `objects' are of type port.
   2556 
   2557  -- Applicative: input-port? (input-port? . objects)
   2558  -- Applicative: output-port? (output-port? . objects)
   2559      Applicative `input-port?' is a predicate that returns true unless
   2560      one or more of its arguments is not an input port.  Applicative
   2561      `output-port?' is a predicate that returns true unless one or more
   2562      of its arguments is not an output port.
   2563 
   2564      Every port must be admitted by at least one of these two
   2565      predicates.
   2566 
   2567  -- Applicative: textual-port? (textual-port? . objects)
   2568  -- Applicative: binary-port? (binary-port? . objects)
   2569      Applicative `textual-port?' is a predicate that returns true
   2570      unless one or more of its arguments is not a textual port.
   2571      Applicative `binary-port?' is a predicate that returns true unless
   2572      one or more of its arguments is not a binary port.
   2573 
   2574      Every port must be admitted by at least one of these two
   2575      predicates.
   2576 
   2577      SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
   2578 
   2579  -- Applicative: file-port? (file-port? . objects)
   2580  -- Applicative: string-port? (string-port? . objects)
   2581  -- Applicative: bytevector-port? (bytevector-port? . objects)
   2582      These applictives are predicates that returns true unless one or
   2583      more of its arguments is not a file, string or bytevector port,
   2584      repectively.
   2585 
   2586      Every port in klisp is be admitted by exactly one of these
   2587      predicates.
   2588 
   2589      SOURCE NOTE: this is missing from Kernel, but convenient in the
   2590      face of the different port types admited by klisp.
   2591 
   2592  -- Applicative: port-open? (port-open? port)
   2593      Applicative `port-open?' returns true iff `port' is still open.
   2594 
   2595      SOURCE NOTE: this is taken from r7rs.
   2596 
   2597  -- Applicative: with-input-from-file (with-input-from-file string
   2598           combiner)
   2599  -- Applicative: with-output-to-file (with-output-to-file string
   2600           combiner)
   2601  -- Applicative: with-error-to-file (with-error-to-file string combiner)
   2602      These three applicatives open the file named in `string' for
   2603      textual input or output, an invoke the binder of either the
   2604      input-port, the output-port or the error-port keyed dynamic
   2605      variables respectively with the opened port & the passed
   2606      `combiner' (this means that the combiner is called in a fresh,
   2607      empty dynamic environment).  When/if the binder normally returns,
   2608      the port is closed.  The result of the applicatives
   2609      `with-input-from-file' and `with-output-from-file' is inert.
   2610 
   2611      SOURCE NOTE: The first two are enumerated in the Kernel report but
   2612      the text is still missing.  The third applicative is from r7rs.
   2613 
   2614  -- Applicative: get-current-input-port (get-current-input-port)
   2615  -- Applicative: get-current-output-port (get-current-output-port)
   2616  -- Applicative: get-current-error-port (get-current-error-port)
   2617      These are the accessors for the input-port, output-port, and
   2618      error-port keyed dynamic variables repectively.
   2619 
   2620      SOURCE NOTE: The first two are enumerated in the Kernel report but
   2621      the text is still missing.  The third applicative is from r7rs.
   2622 
   2623  -- Applicative: open-input-file (open-input-file string)
   2624  -- Applicative: open-binary-input-file (open-binary-input-file string)
   2625      `string' should be the name/path for an existing file.
   2626 
   2627      Applicative `open-input-file' creates and returns a textual input
   2628      port associated with the file represented with `string'.
   2629      Applicative `open-binary-input-file' creates and returns a binary
   2630      input port associated with the file represented with `string'.  In
   2631      either case, if the file can't be opened (e.g. because it doesn't
   2632      exists, or there's a permissions problem), an error is signaled.
   2633 
   2634      SOURCE NOTE: `open-input-file' is enumerated in the Kernel report
   2635      but the text is still missing. `open-binary-input-file' is from
   2636      r7rs.
   2637 
   2638  -- Applicative: open-output-file (open-output-file string)
   2639  -- Applicative: open-binary-output-file (open-binary-output-file
   2640           string)
   2641      `string' should be the name/path for an existing file.
   2642 
   2643      Applicative `open-output-file' creates and returns a textual
   2644      output port associated with the file represented with `string'.
   2645      Applicative `open-binary-output-file' creates and returns a binary
   2646      output port associated with the file represented with `string'.
   2647      In either case, if the file can't be opened (e.g. if there's a
   2648      permissions problem), an error is signaled.
   2649 
   2650      In klisp, for now, applicative `open-output-file' and
   2651      `open-binary-output-file' truncate the file if it already exists,
   2652      but that could change later (i.e. like in Scheme the behaviour
   2653      should be considered unspecified).
   2654 
   2655      SOURCE NOTE: `open-output-file' is enumerated in the Kernel report
   2656      but the text is still missing. `open-binary-output-file' is from
   2657      r7rs.
   2658 
   2659  -- Applicative: open-input-string (open-output-string string)
   2660  -- Applicative: open-input-bytevector (open-output-bytevector
   2661           bytevector)
   2662      These applicative return a fresh input port that reads characters
   2663      or unsigned bytes from the passed sequence.
   2664 
   2665      SOURCE NOTE: These are taken from r7rs.
   2666 
   2667  -- Applicative: open-output-string (open-output-string)
   2668      Applicative `open-output-string' returns a fresh textual output
   2669      port that accumulates characters.  The accumulated data can be
   2670      obtained via applicative `get-output-string'.
   2671 
   2672      SOURCE NOTE: This is taken from r7rs.
   2673 
   2674  -- Applicative: open-output-bytevector (open-output-bytevector)
   2675      Applicative `open-output-bytevector' returns a fresh binary output
   2676      port that accumulates unsigned bytes.  The accumulated data can be
   2677      obtained via applicative `get-output-bytevector'.
   2678 
   2679      SOURCE NOTE: This is taken from r7rs.
   2680 
   2681  -- Applicative: close-input-file (close-input-file input-port)
   2682  -- Applicative: close-output-file (close-output-file output-port)
   2683      These applicatives close the port argument, so that no more
   2684      input/output may be performed on them, and the resources can be
   2685      freed.  If the port was already closed these applicatives have no
   2686      effect.
   2687 
   2688      The result returned by applicatives `close-input-file' and
   2689      `close-output-file' is inert.
   2690 
   2691      SOURCE NOTE: this is enumerated in the Kernel report but the text
   2692      is still missing.  There's probably a name error here.  These
   2693      should probably be called close-input-port & close-output-port.
   2694 
   2695  -- Applicative: close-input-port (close-input-port input-port)
   2696  -- Applicative: close-output-port (close-output-port output-port)
   2697  -- Applicative: close-port (close-port port)
   2698      These applicatives close the port argument, so that no more
   2699      input/output may be performed on them, and the resources can be
   2700      freed.  If the port was already closed these applicatives have no
   2701      effect.  If at some time klisp provided input/output ports these
   2702      could be used to selectively close only one direction of the port.
   2703 
   2704      The result returned by applicatives `close-input-port',
   2705      `close-output-port', and `close-port' is inert.
   2706 
   2707      SOURCE NOTE: this is from r7rs. The equivalent `close-input-file'
   2708      and `close-output-file' are probably name errors and only retained
   2709      here till the draft standard rectifies them.
   2710 
   2711  -- Applicative: get-output-string (get-output-string port)
   2712      `port' should be a string output port.
   2713 
   2714      Applicative `get-output-string' returns a freshly created mutable
   2715      string representing the characters accumulated in `port' so far.
   2716      `port' can be either open or closed.
   2717 
   2718      SOURCE NOTE: This is taken from r7rs.
   2719 
   2720  -- Applicative: get-output-bytevector (get-output-bytevector port)
   2721      `port' should be a bytevector output port.
   2722 
   2723      Applicative `get-output-bytevector' returns a freshly created
   2724      mutable bytevector representing the unsigned bytes accumulated in
   2725      `port' so far.  `port' can be either open or closed.
   2726 
   2727      SOURCE NOTE: This is taken from r7rs.
   2728 
   2729  -- Applicative: read (read [port])
   2730      If the `port' optional argument is not specified, then the value
   2731      of the `input-port' keyed dynamic variable is used.  If the port
   2732      is closed, an error is signaled.  The port should be a textual
   2733      input port.
   2734 
   2735      Applicative `read' reads & returns the next parseable object from
   2736      the given port, or the `eof' if no objects remain.  If `read'
   2737      finds and unparseable object in the port, an error is signaled.
   2738      In that case, the remaining position in the port is unspecified.
   2739 
   2740      SOURCE NOTE: this is enumerated in the Kernel report but the text
   2741      is still missing.
   2742 
   2743  -- Applicative: write (write object [port])
   2744      If the `port' optional argument is not specified, then the value
   2745      of the `output-port' keyed dynamic variable is used.  If the port
   2746      is closed, an error is signaled.  The port should be a textual
   2747      output port.
   2748 
   2749      Applicative `write' writes an external representation of `object'
   2750      to the specified port.  This may be an output-only representation
   2751      that can't be read by applicative `read' in cases where the type
   2752      of `object' doen't have a parseable external representation (e.g.
   2753      combiners and environments).  The result returned by `write' is
   2754      inert.  `write' is guaranteed to terminate even in the case of
   2755      objects with shared or cyclic structure.  In those cases `write'
   2756      will use special syntax to preserve sharing info.
   2757 
   2758      SOURCE NOTE: this is enumerated in the Kernel report but the text
   2759      is still missing.
   2760 
   2761  -- Applicative: write-simple (write-simple object [port])
   2762      Applicative `write-simple' is like `write' except that it doesn't
   2763      write sharing info. It will hang if handed a cyclic structure.
   2764 
   2765      SOURCE NOTE: this is taken from r7rs.
   2766 
   2767  -- Applicative: eof-object? (eof-object? . objects)
   2768      The primitive type predicate for type eof.  `eof-object?' returns
   2769      true iff all the objects in `objects' are of type eof.
   2770 
   2771      SOURCE NOTE: This is not in the report, the idea is from Scheme.
   2772      The `eof-object?' name is also from Scheme, but this will probably
   2773      be changed to just `eof?', for consistency with the other primitive
   2774      type predicates.
   2775 
   2776  -- Applicative: newline (newline [port])
   2777      If the `port' optional argument is not specified, then the value
   2778      of the `output-port' keyed dynamic variable is used.  If the port
   2779      is closed, an error is signaled.  The port should be a textual
   2780      output port.
   2781 
   2782      Applicative `newline' writes a newline to the specified port.  The
   2783      result returned by `newline' is inert.
   2784 
   2785      SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
   2786 
   2787  -- Applicative: display (display object [port])
   2788      If the `port' optional argument is not specified, then the value
   2789      of the `output-port' keyed dynamic variable is used.  If the port
   2790      is not a textual output port, or is closed, an error is signaled.
   2791 
   2792      Applicative `display' behaves like `write' except that strings are
   2793      not enclosed in double quotes and no character is escaped within
   2794      those strings and character objects are output as if by
   2795      `write-char' instead of `write'. The result returned by `display'
   2796      is inert.
   2797 
   2798      SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
   2799 
   2800  -- Applicative: read-line (read-line [port])
   2801      If the `port' optional argument is not specified, then the value
   2802      of the `input-port' keyed dynamic variable is used.  If the port
   2803      is closed or if it is not a textual input port, an error is
   2804      signaled.
   2805 
   2806      Applicative `read-line'
   2807 
   2808      SOURCE NOTE: this is taken from r7rs.
   2809 
   2810  -- Applicative: flush-output-port (flush-output-port [port])
   2811      If the `port' optional argument is not specified, then the value
   2812      of the `output-port' keyed dynamic variable is used.  If the port
   2813      is closed or if it is not an output port, an error is signaled.
   2814 
   2815      Applicative `flush-output-port' flushes any buffered data in the
   2816      output port to the underlying object (file, socket, pipe, memory
   2817      sector, device, etc).  The result returned by `flush-output-port'
   2818      is inert.
   2819 
   2820      SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
   2821 
   2822  -- Applicative: write-char (write-char char [port])
   2823      If the `port' optional argument is not specified, then the value
   2824      of the `output-port' keyed dynamic variable is used.  If the port
   2825      is closed, an error is signaled.  The port should be a textual
   2826      output port.
   2827 
   2828      Applicative `write-char' writes the `char' character (not an
   2829      external representation of the character) to the specified port.
   2830      The result returned by `write-char' is inert.
   2831 
   2832      SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
   2833 
   2834  -- Applicative: read-char (read-char [port])
   2835      If the `port' optional argument is not specified, then the value
   2836      of the `input-port' keyed dynamic variable is used.  If the port
   2837      is closed, an error is signaled.  The port should be a textual
   2838      input port.
   2839 
   2840      Applicative `read-char' reads and returns a character (not an
   2841      external representation of a character) from the specified port,
   2842      or an `eof' if the end of file was reached.
   2843 
   2844      SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
   2845 
   2846  -- Applicative: peek-char (peek-char [port])
   2847      If the `port' optional argument is not specified, then the value
   2848      of the `input-port' keyed dynamic variable is used.  If the port
   2849      is closed, an error is signaled.  The port should be a textual
   2850      input port.
   2851 
   2852      Applicative `peek-char' reads and returns a character (not an
   2853      external representation of a character) from the specified port,
   2854      or an `eof' if the end of file was reached.  The position of the
   2855      port remains unchanged so that new call to `peek-char' or
   2856      `read-char' on the same port return the same character.
   2857 
   2858      SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
   2859 
   2860  -- Applicative: char-ready? (char-ready? [port])
   2861      If the `port' optional argument is not specified, then the value
   2862      of the `input-port' keyed dynamic variable is used.  If the port
   2863      is closed, an error is signaled.  The port should be a textual
   2864      input port.
   2865 
   2866      Predicate `char-ready?' checks to see if a character is available
   2867      in the specified port.  If it returns true, then a `read-char' or
   2868      `peek-char' on that port is guaranteed not to block/hang.  For now
   2869      in klisp this is hardcoded to `#t' because the code to do this is
   2870      non-portable.
   2871 
   2872      SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
   2873 
   2874  -- Applicative: write-u8 (write-u8 u8 [port])
   2875      If the `port' optional argument is not specified, then the value
   2876      of the `output-port' keyed dynamic variable is used.  If the port
   2877      is closed, an error is signaled.  The port should be a binary
   2878      output port.
   2879 
   2880      Applicative `write-u8' writes the byte represented by the unsigned
   2881      integer `u8', that should be between 0 and 255 inclusive, (not an
   2882      external representation of byte) to the specified port.  The
   2883      result returned by `write-u8' is inert.
   2884 
   2885      SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
   2886 
   2887  -- Applicative: read-u8 (read-u8 [port])
   2888      If the `port' optional argument is not specified, then the value
   2889      of the `input-port' keyed dynamic variable is used.  If the port
   2890      is closed, an error is signaled.  The port should be a binary input
   2891      port.
   2892 
   2893      Applicative `read-u8' reads and returns a byte as an exact
   2894      unsigned integer between 0 and 255 inclusive (not an external
   2895      representation of a byte) from the specified port, or an `eof' if
   2896      the end of file was reached.
   2897 
   2898      SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
   2899 
   2900  -- Applicative: peek-u8 (peek-u8 [port])
   2901      If the `port' optional argument is not specified, then the value
   2902      of the `input-port' keyed dynamic variable is used.  If the port
   2903      is closed, an error is signaled.  The port should be a binary
   2904      input port.
   2905 
   2906      Applicative `peek-u8' reads and returns a byte as an exact
   2907      unsigned integer between 0 and 255 inclusive (not an external
   2908      representation of a byte) from the specified port, or an `eof' if
   2909      the end of file was reached.  The position of the port remains
   2910      unchanged so that new call to `peek-u8' or `read-u8' on the same
   2911      port return the same byte.
   2912 
   2913      SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
   2914 
   2915  -- Applicative: u8-ready? (u8-ready? [port])
   2916      If the `port' optional argument is not specified, then the value
   2917      of the `input-port' keyed dynamic variable is used.  If the port
   2918      is closed, an error is signaled.  The port should be a binary
   2919      input port.
   2920 
   2921      Predicate `u8-ready?' checks to see if a byte is available in the
   2922      specified port.  If it returns true, then a `read-u8' or `peek-u8'
   2923      on that port is guaranteed not to block/hang.  For now in klisp
   2924      this is hardcoded to `#t' because the code to do this is
   2925      non-portable.
   2926 
   2927      SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
   2928 
   2929  -- Applicative: call-with-input-file (call-with-input-file string
   2930           combiner)
   2931  -- Applicative: call-with-output-file (call-with-output-file string
   2932           combiner)
   2933      These applicatives open file named in `string' for textual
   2934      input/output respectively and call their `combiner' argument in a
   2935      fresh empty environment passing it as a sole operand the opened
   2936      port.  When/if the combiner normally returns a value the port is
   2937      closed and that value is returned as the result of the applicative.
   2938 
   2939      SOURCE NOTE: this is enumerated in the Kernel report but the text
   2940      is still missing.
   2941 
   2942  -- Applicative: load (load string)
   2943      Applicative `load' opens the file named `string' for textual
   2944      input; reads immutable objects from the file until the end of the
   2945      file is reached; evaluates those objects consecutively in the
   2946      created environment.  The result from applicative `load' is inert.
   2947 
   2948      Notice that if `string' is a relative path it is looked in the
   2949      current directory (whatever that means in your OS, normally the
   2950      directory from which the interpreted was run or the directory where
   2951      the interpreter executable lives).  klisp doesn't track the
   2952      directory from which the current code was read, so there's in
   2953      principle no way to load a file in the same directory as the
   2954      currently executing code with a relative path.  See
   2955      `find-required-filename' for a way to look for a file in a number
   2956      of directories.
   2957 
   2958      SOURCE NOTE: load is enumerated in the Kernel report, but the
   2959      description is not there yet.  This seems like a sane way to define
   2960      it, taking the description of `get-module' that there is in the
   2961      report.  The one detail that I think is still open, is whether to
   2962      return `#inert' (as is the case with klisp currently) or rather
   2963      return the value of the last evaluation.
   2964 
   2965  -- Applicative: require (require string)
   2966      Applicative `require' looks for `string' following the algorithm
   2967      described in applicative `find-required-filename'.  If an
   2968      appropriate file can't be found, and error is signaled.  Otherwise,
   2969      the file is opened for textual input; immutable objects are read
   2970      and acumulated until the end of file is found; those objects are
   2971      evaluated in a fresh standard environment; the results of
   2972      evaluation are discarded and the result from applicative `require'
   2973      is inert.
   2974 
   2975      Applicative `require' also register `string' (as via applicative
   2976      `register-requirement!') so that subsequent calls to `require'
   2977      with exactly the same `string' will not cause any search or
   2978      evaluation.  The mechanism used for this can also be manipulated
   2979      directly by the programmer via applicatives
   2980      `registered-requirement?', `register-requirement!',
   2981      `unregister-requirement!', and `find-required-filename'.
   2982 
   2983      Applicative `require' is useful to load klisp libraries.
   2984 
   2985      SOURCE NOTE: require is taken from lua and r7rs.
   2986 
   2987  -- Applicative: registered-requirement? (registered-requirement?
   2988           string)
   2989  -- Applicative: register-requirement! (register-requirement! string)
   2990  -- Applicative: unregister-requirement! (unregister-requirement!
   2991           string)
   2992  -- Applicative: find-required-filename (find-required-filename string)
   2993      `string' should be non-empty.
   2994 
   2995      These applicatives control the underlying facilities used by
   2996      `require' to register already required files.  Predicate
   2997      `registered-requirement?' returns true iff `string' is already
   2998      registered.  `register-requirement!' marks `string' as registered
   2999      (throws an error if it was already registered).
   3000      `unregister-requirement!' marks `string' as not being registered
   3001      (throws an error if it wasn't registered).
   3002      `find-required-filename' looks for an appropriate file for
   3003      `string' using the algorithm described below.
   3004 
   3005      filename search in controlled by environment variable
   3006      `KLISP_PATH'.  This environment variable should be a list of
   3007      templates separated with semicolons (";").  Each template is a
   3008      string that may contain embedded question mark characters ("?") to
   3009      be replaced with `string'.  After replacements, each template
   3010      represents the path to a file.  All templates are probed in order,
   3011      and the first to name an existing readable file is returned.  If no
   3012      template corresponds to an existing readable file, an error is
   3013      signaled.
   3014 
   3015      NOTE: in the future there will be some mechanism to alter the
   3016      search algorithm dinamically, in the meantime this environment
   3017      variable is the only way to customize it.
   3018 
   3019      SOURCE NOTE: this is not in Kernel, they are supplied per guideline
   3020      G1b of the report (extensibility), so that klisp programs can
   3021      easily duplicate the behaviour of `require'
   3022 
   3023  -- Applicative: get-module (get-module string [environment])
   3024      Applicative `get-module' creates a fresh standard environment;
   3025      opens the file named `string' for textual input; reads objects
   3026      from the file until the end of the file is reached; evaluates those
   3027      objects consecutively in the created environment; and, lastly,
   3028      returns the created environment.  If the optional argument
   3029      `environment' is specified, the freshly created standard
   3030      environment is augmented, prior to evaluating read expressions, by
   3031      binding symbol `module-parameters' to the `environment' argument.
   3032 
   3033 
   3034 File: klisp.info,  Node: Vectors,  Next: Bytevectors,  Prev: Ports,  Up: Top
   3035 
   3036 18 Vectors
   3037 **********
   3038 
   3039 A vector is an object that contains a sequence of arbitrary klisp
   3040 objects.  A vector has a length that is fixed at creation time, and as
   3041 many objects, indexed from `0' to `length-1'.  Compared to lists, klisp
   3042 vectors use less size and have constant access time for any element.
   3043 
   3044    Vectors may be mutable or immutable.  If an attempt is made to mutate
   3045 an immutable vector, an error is signaled.  Two immutable vectors are
   3046 "eq?" iff they are "equal?".  Two mutable vectors are "eq?" if they
   3047 were created by the same constructor call.  Two mutable vectors are
   3048 "equal?" iff they have the same length and have "equal?"  objects in
   3049 each position.  As is the case for lists, in order to handle possibly
   3050 cyclic structures, the "equal?" algorithm considers vectors as FSMs
   3051 where it position is a state change.  There is only one empty vector
   3052 (that is, a vector of length 0) and that vector is immutable.  The
   3053 vector type is encapsulated.
   3054 
   3055    SOURCE NOTE: The report doesn't currently include vectors. They are
   3056 taken from r7rs scheme.
   3057 
   3058  -- Applicative: vector? (vector? . objects)
   3059      The primitive type predicate for type vector.  `vector?' returns
   3060      true iff all the objects in `objects' are of type vector.
   3061 
   3062  -- Applicative: immutable-vector? (immutable-vector? objects)
   3063  -- Applicative: mutable-vector? (mutable-vector? objects)
   3064      The primitive type predicates for types immutable vector and
   3065      mutable vector.  These return true iff all the objects in
   3066      `objects' are of type immutable vector or mutable vector
   3067      respectively.
   3068 
   3069  -- Applicative: make-vector (make-vector k [obj])
   3070      Applicative `make-vector' constructs and returns a new mutable
   3071      vector of length `k'.  If `obj' is specified, then all objects in
   3072      the returned vector are `obj', otherwise the content of the vector
   3073      is unspecified.
   3074 
   3075  -- Applicative: vector-length (vector-length vector)
   3076      Applicative `vector-length' returns the length of `vector'.
   3077 
   3078  -- Applicative: vector-ref (vector-ref vector k)
   3079      Applicative `vector-ref' returns the object of `vector' at
   3080      position `k'.  If `k' is out of bounds (i.e. less than `0' or
   3081      greater or equal than `(vector-length vector)') an error is
   3082      signaled.
   3083 
   3084  -- Applicative: vector-set! (vector-set! vector k obj)
   3085      Applicative `vector-set!' replaces the object with index `k' in
   3086      `vector' with object `obj'.  If `k' is out of bounds, or `vector'
   3087      is immutable, an error is signaled. The result returned by
   3088      `vector-set!' is inert.
   3089 
   3090  -- Applicative: vector (vector . objs)
   3091      Applicative `vector' contructs and return a new mutable vector
   3092      composed of the object arguments.
   3093 
   3094  -- Applicative: vector->list (vector->list vector)
   3095  -- Applicative: list->vector (list->vector objs)
   3096      These applicatives convert between vectors and lists.  The objects
   3097      returned by these applicatives are always mutable.
   3098 
   3099  -- Applicative: vector-copy (vector-copy vector)
   3100      Applicative `vector-copy' constructs and returns a new mutable
   3101      vector with the same length and objects as `vector'.
   3102 
   3103  -- Applicative: vector->bytevector (vector->bytevector vector)
   3104  -- Applicative: bytevector->vector (bytevector->vector bytevector)
   3105      These applicatives convert between vectors and bytevectors.  If a
   3106      vector containing objects other than exact integers between 0 and
   3107      255 inclusive are passed to `vector->bytevector', an error is
   3108      signaled.  The objects returned by these applicatives are always
   3109      mutable.
   3110 
   3111  -- Applicative: vector->string (vector->string vector)
   3112  -- Applicative: string->vector (string->vector string)
   3113      These applicatives convert between vectors and strings.  If a
   3114      vector containing objects other than characters is passed to
   3115      `vector->string', an error is signaled.  The objects returned by
   3116      these applicatives are always mutable.
   3117 
   3118  -- Applicative: vector-copy! (vector-copy! vector1 vector2)
   3119      vector2 should have a length greater than or equal to that of
   3120      vector1.
   3121 
   3122      Copies the values in vector1 to the corresponding positions in
   3123      vector2.  If vector2 is immutable, an error is signaled.  The
   3124      result returned by `vector-copy!' is inert.
   3125 
   3126  -- Applicative: vector-copy-partial (vector-copy-partial vector k1 k2)
   3127      Both `k1' & `k2' should be valid indexes in `vector'.  Also it
   3128      should be the case that `k1 <= k2'.
   3129 
   3130      Applicative `vector-copy-partial' constructs and returns a new
   3131      mutable vector with length `k2 - k1', with the objects from
   3132      `vector', starting at index `k1' (inclusive) and ending at index
   3133      `k2' (exclusive).
   3134 
   3135  -- Applicative: vector-copy-partial! (vector-copy-partial! vector1 k1
   3136           k2 vector2 k3)
   3137      Both `k1' & `k2-1' should be valid indexes in `vector1'.  Also it
   3138      should be the case that `k1 <= k2'.  Both `k3' & `k3 + (k2-k1) -
   3139      1' should be valid indexes in `vector2'.
   3140 
   3141      Applicative `vector-copy-partial!' copies objects k1 (inclusive)
   3142      through k2 (exclusive) from `vector1' to the `k2-k1' positions in
   3143      `vector2' starting at `k3'.  If `vector2' is an immutable vector,
   3144      an error is signaled.  The result returned by
   3145      `vector-copy-partial!' is inert.
   3146 
   3147  -- Applicative: vector-fill! (vector-fill! vector obj)
   3148      Applicative `vector-fill!' replaces all the objects in `vector'
   3149      with object `obj'.  If `vector' is an immutable vector, an error
   3150      is signaled.  The result returned by `vector-fill!' is inert.
   3151 
   3152  -- Applicative: vector->immutable-vector (vector->immutable-vector
   3153           vector)
   3154      Applicative `vector->immutable-vector' constructs and returns a
   3155      new immutable vector with the same length and objects as `vector'.
   3156 
   3157 
   3158 File: klisp.info,  Node: Bytevectors,  Next: Errors,  Prev: Vectors,  Up: Top
   3159 
   3160 19 Bytevectors
   3161 **************
   3162 
   3163 A bytevector is an object that contains a sequence of bytes, that is,
   3164 exact integers between 0 and 255 inclusive.  A bytevector has a length
   3165 that is fixed at creation time, and as many bytes, indexed from `0' to
   3166 `length-1'.  Compared to vectors, bytevectors use less size for each
   3167 element.
   3168 
   3169    Bytevectors may be mutable or immutable.  If an attempt is made to
   3170 mutate an immutable bytevector, an error is signaled.  Two immutable
   3171 bytevectors are "eq?" iff they are "equal?".  Two mutable bytevectors
   3172 are "eq?" if they were created by the same constructor call.  Two
   3173 mutable bytevectors are "equal?" iff they have the same length and have
   3174 "equal?"  bytes in each position.  There is only one empty bytevector
   3175 (that is, a bytevector of length 0) and that bytevector is immutable.
   3176 The bytevector type is encapsulated.
   3177 
   3178    SOURCE NOTE: The report doesn't currently include bytevectors. They
   3179 are taken from r7rs scheme.
   3180 
   3181  -- Applicative: bytevector? (bytevector? . obje)
   3182      The primitive type predicate for type bytevector.  `bytevector?'
   3183      returns true iff all the objects in `objects' are of type
   3184      bytevector.
   3185 
   3186  -- Applicative: immutable-bytevector? (immutable-bytevector? objects)
   3187  -- Applicative: mutable-bytevector? (mutable-bytevector? objects)
   3188      The primitive type predicates for types immutable bytevector and
   3189      mutable bytevector.  These return true iff all the objects in
   3190      `objects' are of type immutable bytevector or mutable bytevector
   3191      respectively.
   3192 
   3193  -- Applicative: make-bytevector (make-bytevector k [u8])
   3194      Applicative `make-bytevector' constructs and returns a new mutable
   3195      bytevector of length `k'.  If `u8' is specified, then all bytes in
   3196      the returned bytevector are `obj', otherwise the content of the
   3197      bytevector is unspecified.
   3198 
   3199  -- Applicative: bytevector-length (bytevector-length bytevector)
   3200      Applicative `bytevector-length' returns the length of `bytevector'.
   3201 
   3202  -- Applicative: bytevector-ref (bytevector-ref bytevector k)
   3203      Applicative `bytevector-ref' returns the byte of `bytevector' at
   3204      position `k'.  If `k' is out of bounds (i.e. less than `0' or
   3205      greater or equal than `(bytevector-length bytevector)') an error
   3206      is signaled.
   3207 
   3208  -- Applicative: bytevector-set! (bytevector-set! bytevector k u8)
   3209      Applicative `bytevector-set!' replaces the byte with index `k' in
   3210      `bytevector' with byte `u8'.  If `k' is out of bounds, or
   3211      `bytevector' is immutable, an error is signaled. The result
   3212      returned by `bytevector-set!' is inert.
   3213 
   3214  -- Applicative: bytevector (bytevector . u8s)
   3215      Applicative `bytevector' contructs and return a new mutable
   3216      bytevector composed of the byte arguments.
   3217 
   3218  -- Applicative: bytevector->list (bytevector->list bytevector)
   3219  -- Applicative: list->bytevector (list->bytevector u8s)
   3220      These applicatives convert between bytevectors and lists of bytes.
   3221      If the list passed to `list->bytevector' contains an object that
   3222      isn't a byte, an error is signaled.  The objects returned by these
   3223      applicatives are always mutable.
   3224 
   3225  -- Applicative: bytevector-copy (bytevector-copy bytevector)
   3226      Applicative `bytevector-copy' constructs and returns a new mutable
   3227      bytevector with the same length and bytes as `bytevector'.
   3228 
   3229  -- Applicative: bytevector->vector (bytevector->vector bytevector)
   3230  -- Applicative: vector->bytevector (vector->bytevector vector)
   3231      These applicatives convert between bytevectors and vectors.  If a
   3232      vector containing objects other than bytes (exact integers between
   3233      0 and 255 inclusive) is passed to `vector->bytevector', an error is
   3234      signaled.  The objects returned by these applicatives are always
   3235      mutable.
   3236 
   3237  -- Applicative: bytevector-copy! (bytevector-copy! bytevector1
   3238           bytevector2)
   3239      bytevector2 should have a length greater than or equal to that of
   3240      bytevector1.
   3241 
   3242      Copies the bytes in bytevector1 to the corresponding positions in
   3243      bytevector2.  If bytevector2 is immutable, an error is signaled.
   3244      The result returned by `bytevector-copy!' is inert.
   3245 
   3246  -- Applicative: bytevector-copy-partial (bytevector-copy-partial
   3247           bytevector k1 k2)
   3248      Both `k1' & `k2' should be valid indexes in `bytevector'.  Also it
   3249      should be the case that `k1 <= k2'.
   3250 
   3251      Applicative `bytevector-copy-partial' constructs and returns a new
   3252      mutable bytevector with length `k2 - k1', with the bytes from
   3253      `bytevector', starting at index `k1' (inclusive) and ending at
   3254      index `k2' (exclusive).
   3255 
   3256  -- Applicative: bytevector-copy-partial! (bytevector-copy-partial!
   3257           bytevector1 k1 k2 bytevector2 k3)
   3258      Both `k1' & `k2-1' should be valid indexes in `bytevector1'.  Also
   3259      it should be the case that `k1 <= k2'.  Both `k3' & `k3 + (k2-k1)
   3260      - 1' should be valid indexes in `bytevector2'.
   3261 
   3262      Applicative `bytevector-copy-partial!' copies bytes k1 (inclusive)
   3263      through k2 (exclusive) from `bytevector1' to the `k2-k1' positions
   3264      in `bytevector2' starting at `k3'.  If `bytevector2' is an
   3265      immutable bytevector, an error is signaled.  The result returned
   3266      by `bytevector-copy-partial!' is inert.
   3267 
   3268  -- Applicative: bytevector-fill! (bytevector-fill! bytevector u8)
   3269      Applicative `bytevector-fill!' replaces all the bytes in
   3270      `bytevector' with byte `u8'.  If `bytevector' is an immutable
   3271      bytevector, an error is signaled.  The result returned by
   3272      `bytevector-fill!' is inert.
   3273 
   3274  -- Applicative: bytevector->immutable-bytevector
   3275           (bytevector->immutable-bytevector bytevector)
   3276      Applicative `bytevector->immutable-bytevector' constructs and
   3277      returns a new immutable bytevector with the same length and bytes
   3278      as `bytevector'.
   3279 
   3280 
   3281 File: klisp.info,  Node: Errors,  Next: Libraries,  Prev: Bytevectors,  Up: Top
   3282 
   3283 20 Errors
   3284 *********
   3285 
   3286 An error object contains information that can be used to describe an
   3287 error that occured in the klisp system.  The interpreter will pass an
   3288 error object to an error continuation whenever it needs to signal that
   3289 an error occured while executing a program or evaluating an expression.
   3290 
   3291    An error object contains a message describing the situation and a
   3292 (possibly empty) list of objects, called its irritants, that provide
   3293 some context or additional info depending on the error condition.  The
   3294 error type is encapsulated.
   3295 
   3296    Notice that unlike in most other languages, the error object in klisp
   3297 isn't used to classify the error in error handlers, the error
   3298 continuation being passed the error object is used for that.  The error
   3299 object is used only to convey additional info, not the type of error.
   3300 
   3301    SOURCE NOTE: The type of object passed to the error continuation is
   3302 not specified in the Kernel Report.  This type was inspired by r7rs
   3303 scheme.
   3304 
   3305  -- Applicative: error-object? (error-object? . objs)
   3306      The primitive type predicate for type error.  `error-object?'
   3307      returns true iff all the objects in `objects' are of type error.
   3308 
   3309  -- Applicative: error (error msg . objs)
   3310      Create an error object with message `msg' and irritants the list
   3311      of objects `objs' and then send that error object to the error
   3312      continuation.  This is the recommended way to signal an error in
   3313      klisp.
   3314 
   3315  -- Applicative: raise (raise obj)
   3316      Send `obj' to the error continuation.  `obj' needs not be an error
   3317      object, any kind of object can be sent to the error continuation
   3318      (but that's not recommended!).
   3319 
   3320  -- Applicative: error-object-message (error-object-message error)
   3321      Applicative `error-object-message' extracts the message of `error'.
   3322 
   3323  -- Applicative: error-object-irritants (error-object-irritants error)
   3324      Applicative `error-object-irritants' extracts the irritants of
   3325      `error'.
   3326 
   3327 
   3328 File: klisp.info,  Node: Libraries,  Next: System,  Prev: Errors,  Up: Top
   3329 
   3330 21 Libraries
   3331 ************
   3332 
   3333 Libraries provide a way to organize klisp code with a clean & clear
   3334 interface to the rest of the program.  They are first class objects (as
   3335 all manipulable entities in Kernel, and according to the guidelines in
   3336 the Kernel report). A library has list of exported symbols and values
   3337 for those symbols (generally combiners but may be any object). The
   3338 library type is encapsulated.
   3339 
   3340    In addition there's a mechanism to refer to library objects by name
   3341 (where a name is actually a unique list of symbols and numbers), with
   3342 the ability to register new libraries, get the library object from a
   3343 name, unregister libraries, etc.
   3344 
   3345    These two ways of working with libraries conform the low level API to
   3346 libraries and are orthogonal to each other.  They are provided to allow
   3347 klisp programs to construct their own interface to library definition
   3348 and use, and to respect the guidelines and spirit of the Kernel Report.
   3349 
   3350    There's also a higher level API that is a combination of the lower
   3351 level APIs and behaves more like traditional module systems.  This is
   3352 probably what most klisp programs will use.  This API consist of the
   3353 `$provide-library!' operative to define (and register) new libraries
   3354 and the `$import-library!' operative to extract bindings out of
   3355 existing libraries.  This allows various forms of controlling which
   3356 bindings are extracted from the libraries and allows various forms of
   3357 renaming. It can be used both in the body of libraries or in the top
   3358 level.
   3359 
   3360    No association is made by klisp between source files and libraries.
   3361 For a possible mechanism to handle this see `require' in the ports
   3362 module. Also no special meaning is assigned to the library names.  This
   3363 could be used by an even higher level API, for example to map to
   3364 version numbers and/or to the underlying filesystem.
   3365 
   3366    SOURCE NOTE: This is mostly an adaptation from the r7rs draft of
   3367 scheme.  There's no mention of libraries in the Kernel Report, but they
   3368 were deemed important for klisp in order to share and distribute code
   3369 with a common interface.  A number of adaptations were made to the
   3370 scheme version to sit more comfortably with the Kernel way of doing
   3371 things (first class status, exposing of the library register, etc).
   3372 
   3373  -- Applicative: library? (library? . objects)
   3374      The primitive type predicate for type library.  `library?' returns
   3375      true iff all the objects in `objects' are of type library.
   3376 
   3377      NOTE: This is part of the low level API to libraries. It won't be
   3378      needed to writers or users of libraries that stick to the higher
   3379      level API (i.e. `$provide-library!' & `$import-library!').
   3380 
   3381  -- Applicative: make-library (make-library bindings)
   3382      `bindings' should be an acyclic list of `(symbol . value)' pairs.
   3383      Each symbol may only occur once in the list.
   3384 
   3385      Constructs a new library object with the passed `bindings' as
   3386      exported objects.
   3387 
   3388      NOTE: This is part of the low level API to libraries, writers of
   3389      libraries are encouraged to use `$provide-library!' to define
   3390      their libraries.
   3391 
   3392  -- Applicative: get-library-export-list (get-library-export-list
   3393           library)
   3394  -- Applicative: get-library-environment (get-library-environment
   3395           library)
   3396      `get-library-export-list' returns the list of symbols exported
   3397      from the passed library.  `get-library-environment' returns a
   3398      fresh empty environment whose parent has all exported symbols of
   3399      the library bound to the exported objects.
   3400 
   3401      NOTE: This is part of the low level API to libraries, users of
   3402      libraries are encouraged to use `$import-library!' to get bindings
   3403      out of libraries (and into the current environment).
   3404 
   3405  -- Operative: $registered-library? ($registered-library? name)
   3406  -- Operative: $get-registered-library ($get-registered-library name)
   3407  -- Operative: $register-library! ($register-library! name library)
   3408  -- Operative: $unregister-library! ($unregister-library! name)
   3409      `name' should a an acyclic list of symbols and exact non-negative
   3410      integers.  Two registered libraries can't have the same name (in
   3411      the sense of `equal?').
   3412 
   3413      These operatives control the library registry that maps names to
   3414      libraries.
   3415 
   3416      Predicate `$registered-library?' returns true iff a library named
   3417      `name' is already registered.  `get-registered-library' returns
   3418      the library object associated with `name' (or throws an error if
   3419      no library named `name' is registered).  `$register-library!'
   3420      registers `library' with name `name' (throws an error if `name' is
   3421      already registered.  `$unregister-library!' removes the library
   3422      registered as `name' from the library register (throws an error if
   3423      no such library was registered).
   3424 
   3425      NOTE: This is part of the low level API to libraries, users &
   3426      writers of libraries are encouraged to use `$provide-library!' to
   3427      create & register new libraries.
   3428 
   3429  -- Operative: $provide-library! ($provide-library! name exports . body)
   3430  -- Operative: $import-library! ($import-library! . imports)
   3431      `name' should be as for `register-library!' and not already
   3432      registered.  `exports' should be a list of `(#:export
   3433      <export-spec> ...)'. Where `<export spec>' is either:
   3434         * `symbol'
   3435 
   3436         * `(#:rename internal-symbol external-symbol)'
   3437 
   3438      A lone symbol has the same semantics as the pair with that symbol
   3439      in both internal and external positions.  No symbol can appear
   3440      more than once as external.  `body' should be an acyclic list of
   3441      expressions.  `imports' should be a list like `(<import-spec>
   3442      ...)' where `<import-spec>' is either
   3443         * `<name>'
   3444 
   3445         * `(#:only <import-spec> symbol ...)'
   3446 
   3447         * `(#:except <import-spec> symbol ...)'
   3448 
   3449         * `(#:prefix <import-spec> symbol)'
   3450 
   3451         * `(#:rename <import-spec> (orig-symbol new-symbol) ...)'
   3452 
   3453      These two operatives conform the higher level API for klisp
   3454      libraries.  They are what most users of klisp (both writers and
   3455      users of libraries) will use.
   3456 
   3457      Operative `$provide-library!' creates and register a library with
   3458      name `name' and exported symbols obtained from the `exports' list
   3459      and values prepared by the `body'.  First a child of the dynamic
   3460      environment is created.  Then, `body' is evaluated sequentially as
   3461      if by `$sequence' in that environment.  Next a new library is
   3462      created with a list of exported bindings that use the external
   3463      symbols in `exports' as names and the values bound by the
   3464      corresponding internal symbols in the created environment, as
   3465      values.  If a lone symbol is used in `exports' it is used both as
   3466      internal and external symbol for that binding.  Lastly, the new
   3467      library object is registered as `name'.  This mechanism more or
   3468      less follows the idea of operative `$provide!' from the Kernel
   3469      Report, but it also allows for renaming.
   3470 
   3471      Operative `$import-library!' imports to the current environment
   3472      any combination of bindings from any number of named libraries,
   3473      while allowing renaming of said bindings.  It can be used in any
   3474      context, as any other Kernel expression.  `$import-library!' looks
   3475      for the named libraries and then extracts & renames the specified
   3476      bindings according to each `<import-spec>' and defines them (in
   3477      the sense of `$define!'  and `$set!') in the current dynamic
   3478      environment.  The set of bindings to import are generated in a
   3479      recursive manner.  This allows a great deal of control of the
   3480      imported bindings and their names.  The semantics for the set of
   3481      bindings generated by the various `<import-spec>'s are as follows:
   3482         * `<name>': All bindings from library `name'.
   3483 
   3484         * `(#:only <import-spec> symbol ...)': Only the named bindings
   3485           from the set of bindings in `<import-spec>'.
   3486 
   3487         * `(#:except <import-spec> symbol ...)': All bindings from the
   3488           set in `<import-spec>' except those named in the list.
   3489 
   3490         * `(#:prefix <import-spec> symbol)': All bindings from the set
   3491           in `<import-spec>' but renamed by prefixing each one with the
   3492           specified prefix `symbol'.
   3493 
   3494         * `(#:rename <import-spec> (orig-symbol new-symbol) ...)': All
   3495           bindings from the set in `<import-spec>' but renaming all
   3496           `orig-symbol' to the corresponding `new-symbol'.
   3497 
   3498      If two values are tried to be imported with the same name, they are
   3499      checked for `eq?'-ness, if they are deemed `eq?' to each other
   3500      they are imported, otherwise `$import-library!' throws an error.
   3501      This helps catch name collisions while allowing to reexport
   3502      bindings from used libraries without conflict.
   3503 
   3504 
   3505 File: klisp.info,  Node: System,  Next: Alphabetical Index,  Prev: Libraries,  Up: Top
   3506 
   3507 22 System
   3508 *********
   3509 
   3510 Module System contains some useful features for interacting with the
   3511 host environment.
   3512 
   3513    SOURCE NOTE: most of these come from r7rs.
   3514 
   3515  -- Applicative: get-current-second (get-current-second)
   3516      Applicative `get-current-second' returns the number of seconds
   3517      elapsed since the UNIX/POSIX epoch (that is midnight January 1st,
   3518      1970, UTC).
   3519 
   3520      NOTE: r7rs specifies TAI seconds, but for now we are sticking to
   3521      POSIX here.
   3522 
   3523  -- Applicative: get-current-jiffies (get-current-jiffies)
   3524      Applicative `get-current-jiffies' returns the number of jiffies
   3525      (fractions of a second) elapsed since an arbitrary epoch that may
   3526      change in each run of the klisp interpreter.  Applicative
   3527      `get-jiffies-per-second' can be used to determine which fraction
   3528      of a second a jiffy represents.
   3529 
   3530  -- Applicative: get-jiffies-per-second (get-jiffies-per-second)
   3531      Applicative `get-jiffies-per-second' returns a constant
   3532      representing the number of jiffies that correspond to one second.
   3533 
   3534  -- Applicative: file-exists (file-exists string)
   3535      Predicate `file-exists?' checks to see if a file named `string'
   3536      exists.
   3537 
   3538  -- Applicative: delete-file (delete-file string)
   3539      `string' should be the name/path for an existing file.
   3540 
   3541      Applicative `delete-file' deletes the file named `string'.  If it
   3542      doesn't exists or can't be deleted, an error is signaled. The
   3543      result returned by `delete-file' is inert.
   3544 
   3545  -- Applicative: rename-file (rename-file string1 string2)
   3546      `string1' should be the name/path for an existing file, `string2'
   3547      should be the name/path for a non existing file.
   3548 
   3549      Applicative `rename-file' renames the file named `string1' to
   3550      `string2'. If the file doesn't exists or can't be renamed for any
   3551      reason, an error is signaled. The result returned by `rename-file'
   3552      is inert.
   3553 
   3554      SOURCE NOTE: this is missing from r7rs, it is taken from C, being
   3555      quite similar to `delete-file'.
   3556 
   3557  -- Applicative: get-script-arguments (get-script-arguments)
   3558  -- Applicative: get-interpreter-arguments (get-interpreter-arguments)
   3559      These applicatives return respectively the script and interpreter
   3560      arguments.  The script arguments are a list of the arguments
   3561      passed to the klisp interpreter starting from (and including) the
   3562      script name.  The interpreter arguments are the complete list of
   3563      arguments passed to the klisp interpreter (including the name of
   3564      the interpreter as the first item in the list, the interpreter
   3565      flag arguments and the script name and arguments.
   3566 
   3567  -- Applicative: defined-environment-variable?
   3568           (defined-environment-variable? string)
   3569      Predicate `defined-environment-variable?' returns true iff
   3570      `string' represents a defined envrionment variable.
   3571 
   3572  -- Applicative: get-environment-variable (get-environment-variable
   3573           string)
   3574      Applicative `get-environment-variable' returns the value of the
   3575      environment variable represented by `string'.  If `string' doesn't
   3576      represent a defined environment variable an error is signaled.
   3577 
   3578  -- Applicative: get-environment-variables (get-environment-variables)
   3579      Applicative `get-environment-variable' returns an alist
   3580      representing the defined environment variables and their values.
   3581      The alist is a list of `(variable . value)' entries, where both
   3582      `variable' and `value' are strings.
   3583 
   3584 
   3585 File: klisp.info,  Node: Alphabetical Index,  Next: (dir),  Prev: System,  Up: Top
   3586 
   3587 Index
   3588 *****
   3589 
   3590 
   3591 * Menu:
   3592 
   3593 * $and?:                                 Booleans.            (line  28)
   3594 * $bindings->environment:                Environments.        (line 175)
   3595 * $binds?:                               Environments.        (line 108)
   3596 * $cond:                                 Control.             (line  32)
   3597 * $define!:                              Environments.        (line  49)
   3598 * $delay:                                Promises.            (line  79)
   3599 * $get-registered-library:               Libraries.           (line  80)
   3600 * $if:                                   Control.             (line  15)
   3601 * $import!:                              Environments.        (line 217)
   3602 * $import-library!:                      Libraries.           (line 104)
   3603 * $lambda:                               Combiners.           (line  76)
   3604 * $lazy:                                 Promises.            (line  43)
   3605 * $let:                                  Environments.        (line  89)
   3606 * $let*:                                 Environments.        (line 124)
   3607 * $let-redirect:                         Environments.        (line 153)
   3608 * $let-safe:                             Environments.        (line 161)
   3609 * $let/cc:                               Continuations.       (line 143)
   3610 * $letrec:                               Environments.        (line 137)
   3611 * $letrec*:                              Environments.        (line 144)
   3612 * $or?:                                  Booleans.            (line  42)
   3613 * $provide!:                             Environments.        (line 201)
   3614 * $provide-library!:                     Libraries.           (line 103)
   3615 * $register-library!:                    Libraries.           (line  81)
   3616 * $registered-library?:                  Libraries.           (line  79)
   3617 * $remote-eval:                          Environments.        (line 169)
   3618 * $sequence:                             Control.             (line  23)
   3619 * $set!:                                 Environments.        (line 192)
   3620 * $unless:                               Control.             (line  68)
   3621 * $unregister-library!:                  Libraries.           (line  82)
   3622 * $vau:                                  Combiners.           (line  26)
   3623 * $when:                                 Control.             (line  67)
   3624 * *:                                     Numbers.             (line 136)
   3625 * +:                                     Numbers.             (line 124)
   3626 * -:                                     Numbers.             (line 152)
   3627 * /:                                     Numbers.             (line 321)
   3628 * <=?:                                   Numbers.             (line 116)
   3629 * <?:                                    Numbers.             (line 115)
   3630 * =?:                                    Numbers.             (line 110)
   3631 * >=?:                                   Numbers.             (line 118)
   3632 * >?:                                    Numbers.             (line 117)
   3633 * abs:                                   Numbers.             (line 208)
   3634 * acos:                                  Numbers.             (line 408)
   3635 * and?:                                  Booleans.            (line  20)
   3636 * append:                                Pairs and lists.     (line 246)
   3637 * append!:                               Pairs and lists.     (line 348)
   3638 * applicative descriptions:              A Sample Applicative Description.
   3639                                                               (line   6)
   3640 * applicative?:                          Combiners.           (line  21)
   3641 * applicatives:                          Combiners.           (line   6)
   3642 * apply:                                 Combiners.           (line  83)
   3643 * apply-continuation:                    Continuations.       (line 134)
   3644 * asin:                                  Numbers.             (line 407)
   3645 * assoc:                                 Pairs and lists.     (line 290)
   3646 * assq:                                  Pairs and lists.     (line 375)
   3647 * atan:                                  Numbers.             (line 409)
   3648 * binary-port?:                          Ports.               (line  43)
   3649 * boolean?:                              Booleans.            (line  12)
   3650 * booleans:                              Booleans.            (line   6)
   3651 * bytevector:                            Bytevectors.         (line  58)
   3652 * bytevector->immutable-bytevector:      Bytevectors.         (line 119)
   3653 * bytevector->list:                      Bytevectors.         (line  62)
   3654 * bytevector->string:                    Strings.             (line 135)
   3655 * bytevector->vector <1>:                Bytevectors.         (line  73)
   3656 * bytevector->vector:                    Vectors.             (line  72)
   3657 * bytevector-copy:                       Bytevectors.         (line  69)
   3658 * bytevector-copy!:                      Bytevectors.         (line  82)
   3659 * bytevector-copy-partial:               Bytevectors.         (line  91)
   3660 * bytevector-copy-partial!:              Bytevectors.         (line 101)
   3661 * bytevector-fill!:                      Bytevectors.         (line 112)
   3662 * bytevector-for-each:                   Control.             (line  56)
   3663 * bytevector-length:                     Bytevectors.         (line  43)
   3664 * bytevector-map:                        Combiners.           (line 123)
   3665 * bytevector-port?:                      Ports.               (line  56)
   3666 * bytevector-ref:                        Bytevectors.         (line  46)
   3667 * bytevector-set!:                       Bytevectors.         (line  52)
   3668 * bytevector?:                           Bytevectors.         (line  25)
   3669 * Bytevectors:                           Bytevectors.         (line   6)
   3670 * caaaar:                                Pairs and lists.     (line 111)
   3671 * caaadr:                                Pairs and lists.     (line 112)
   3672 * caaar:                                 Pairs and lists.     (line 103)
   3673 * caadar:                                Pairs and lists.     (line 113)
   3674 * caaddr:                                Pairs and lists.     (line 114)
   3675 * caadr:                                 Pairs and lists.     (line 104)
   3676 * caar:                                  Pairs and lists.     (line  99)
   3677 * cadaar:                                Pairs and lists.     (line 115)
   3678 * cadadr:                                Pairs and lists.     (line 116)
   3679 * cadar:                                 Pairs and lists.     (line 105)
   3680 * caddar:                                Pairs and lists.     (line 117)
   3681 * cadddr:                                Pairs and lists.     (line 118)
   3682 * caddr:                                 Pairs and lists.     (line 106)
   3683 * cadr:                                  Pairs and lists.     (line 100)
   3684 * call-with-input-file:                  Ports.               (line 405)
   3685 * call-with-output-file:                 Ports.               (line 407)
   3686 * call/cc:                               Continuations.       (line  43)
   3687 * car:                                   Pairs and lists.     (line  95)
   3688 * cdaaar:                                Pairs and lists.     (line 119)
   3689 * cdaadr:                                Pairs and lists.     (line 120)
   3690 * cdaar:                                 Pairs and lists.     (line 107)
   3691 * cdadar:                                Pairs and lists.     (line 121)
   3692 * cdaddr:                                Pairs and lists.     (line 122)
   3693 * cdadr:                                 Pairs and lists.     (line 108)
   3694 * cdar:                                  Pairs and lists.     (line 101)
   3695 * cddaar:                                Pairs and lists.     (line 123)
   3696 * cddadr:                                Pairs and lists.     (line 124)
   3697 * cddar:                                 Pairs and lists.     (line 109)
   3698 * cdddar:                                Pairs and lists.     (line 125)
   3699 * cddddr:                                Pairs and lists.     (line 126)
   3700 * cdddr:                                 Pairs and lists.     (line 110)
   3701 * cddr:                                  Pairs and lists.     (line 102)
   3702 * cdr:                                   Pairs and lists.     (line  96)
   3703 * ceiling:                               Numbers.             (line 340)
   3704 * char->digit:                           Characters.          (line  91)
   3705 * char->integer:                         Characters.          (line  73)
   3706 * char-alphabetic?:                      Characters.          (line  43)
   3707 * char-ci<=?:                            Characters.          (line  37)
   3708 * char-ci<?:                             Characters.          (line  36)
   3709 * char-ci=?:                             Characters.          (line  35)
   3710 * char-ci>=?:                            Characters.          (line  39)
   3711 * char-ci>?:                             Characters.          (line  38)
   3712 * char-digit?:                           Characters.          (line  80)
   3713 * char-downcase:                         Characters.          (line  59)
   3714 * char-foldcase:                         Characters.          (line  61)
   3715 * char-lower-case?:                      Characters.          (line  50)
   3716 * char-numeric?:                         Characters.          (line  44)
   3717 * char-ready?:                           Ports.               (line 335)
   3718 * char-title-case?:                      Characters.          (line  51)
   3719 * char-titlecase:                        Characters.          (line  60)
   3720 * char-upcase:                           Characters.          (line  58)
   3721 * char-upper-case?:                      Characters.          (line  49)
   3722 * char-whitespace?:                      Characters.          (line  45)
   3723 * char<=?:                               Characters.          (line  29)
   3724 * char<?:                                Characters.          (line  28)
   3725 * char=?:                                Characters.          (line  27)
   3726 * char>=?:                               Characters.          (line  31)
   3727 * char>?:                                Characters.          (line  30)
   3728 * char?:                                 Characters.          (line  23)
   3729 * characters:                            Characters.          (line   6)
   3730 * close-input-file:                      Ports.               (line 156)
   3731 * close-input-port:                      Ports.               (line 170)
   3732 * close-output-file:                     Ports.               (line 157)
   3733 * close-output-port:                     Ports.               (line 171)
   3734 * close-port:                            Ports.               (line 172)
   3735 * combiner?:                             Combiners.           (line 134)
   3736 * combiners:                             Combiners.           (line   6)
   3737 * cons:                                  Pairs and lists.     (line  45)
   3738 * continuation->applicative:             Continuations.       (line  95)
   3739 * continuation?:                         Continuations.       (line  38)
   3740 * continuations:                         Continuations.       (line   6)
   3741 * control:                               Control.             (line   6)
   3742 * copy-es:                               Pairs and lists.     (line 363)
   3743 * copy-es-immutable!:                    Pairs and lists.     (line  59)
   3744 * cos:                                   Numbers.             (line 405)
   3745 * countable-list?:                       Pairs and lists.     (line 307)
   3746 * defined-environment-variable?:         System.              (line  65)
   3747 * delete-file:                           System.              (line  35)
   3748 * denominator:                           Numbers.             (line 330)
   3749 * description format:                    Format of Descriptions.
   3750                                                               (line   6)
   3751 * digit->char:                           Characters.          (line  92)
   3752 * display:                               Ports.               (line 262)
   3753 * div:                                   Numbers.             (line 164)
   3754 * div-and-mod:                           Numbers.             (line 166)
   3755 * div0:                                  Numbers.             (line 178)
   3756 * div0-and-mod0:                         Numbers.             (line 180)
   3757 * documentation notation:                Evaluation Notation. (line   6)
   3758 * empty list:                            Pairs and lists.     (line   6)
   3759 * encapsulations:                        Encapsulations.      (line   6)
   3760 * encycle!:                              Pairs and lists.     (line 196)
   3761 * environment?:                          Environments.        (line  23)
   3762 * environments:                          Environments.        (line   6)
   3763 * eof-object?:                           Ports.               (line 242)
   3764 * eq?:                                   Equivalence.         (line  12)
   3765 * equal?:                                Equivalence.         (line  16)
   3766 * equivalence:                           Equivalence.         (line   6)
   3767 * error:                                 Errors.              (line  30)
   3768 * error message notation:                Error Messages.      (line   6)
   3769 * error-continuation:                    Continuations.       (line 110)
   3770 * error-object-irritants:                Errors.              (line  44)
   3771 * error-object-message:                  Errors.              (line  41)
   3772 * error-object?:                         Errors.              (line  26)
   3773 * Errors:                                Errors.              (line   6)
   3774 * eval:                                  Environments.        (line  32)
   3775 * eval-string:                           Environments.        (line 183)
   3776 * evaluation notation:                   Evaluation Notation. (line   6)
   3777 * even?:                                 Numbers.             (line 201)
   3778 * exact-integer?:                        Numbers.             (line  66)
   3779 * exact?:                                Numbers.             (line  94)
   3780 * exit:                                  Continuations.       (line 162)
   3781 * exp:                                   Numbers.             (line 402)
   3782 * expt:                                  Numbers.             (line 397)
   3783 * extend-continuation:                   Continuations.       (line  50)
   3784 * file-exists:                           System.              (line  31)
   3785 * file-port?:                            Ports.               (line  54)
   3786 * filter:                                Pairs and lists.     (line 277)
   3787 * find-required-filename:                Ports.               (line 467)
   3788 * finite-list?:                          Pairs and lists.     (line 303)
   3789 * finite?:                               Numbers.             (line  90)
   3790 * floor:                                 Numbers.             (line 339)
   3791 * flush-output-port:                     Ports.               (line 285)
   3792 * fonts:                                 Some Terms.          (line  13)
   3793 * foo:                                   A Sample Applicative Description.
   3794                                                               (line  15)
   3795 * for-each:                              Control.             (line  42)
   3796 * force:                                 Promises.            (line  35)
   3797 * gcd:                                   Numbers.             (line 222)
   3798 * get-current-environment:               Environments.        (line 114)
   3799 * get-current-error-port:                Ports.               (line  91)
   3800 * get-current-input-port:                Ports.               (line  89)
   3801 * get-current-jiffies:                   System.              (line  20)
   3802 * get-current-output-port:               Ports.               (line  90)
   3803 * get-current-second:                    System.              (line  12)
   3804 * get-environment-variable:              System.              (line  70)
   3805 * get-environment-variables:             System.              (line  75)
   3806 * get-interpreter-arguments:             System.              (line  55)
   3807 * get-jiffies-per-second:                System.              (line  27)
   3808 * get-library-environment:               Libraries.           (line  69)
   3809 * get-library-export-list:               Libraries.           (line  67)
   3810 * get-list-metrics:                      Pairs and lists.     (line 161)
   3811 * get-module:                            Ports.               (line 498)
   3812 * get-output-bytevector:                 Ports.               (line 195)
   3813 * get-output-string:                     Ports.               (line 186)
   3814 * get-real-exact-bounds:                 Numbers.             (line 248)
   3815 * get-real-exact-primary:                Numbers.             (line 267)
   3816 * get-real-internal-bounds:              Numbers.             (line 247)
   3817 * get-real-internal-primary:             Numbers.             (line 266)
   3818 * get-script-arguments:                  System.              (line  54)
   3819 * get-string-arithmetic:                 Numbers.             (line 314)
   3820 * guard-continuation:                    Continuations.       (line  63)
   3821 * guard-dynamic-extent:                  Continuations.       (line 156)
   3822 * ignore:                                Environments.        (line   6)
   3823 * ignore?:                               Environments.        (line  28)
   3824 * immutable-bytevector?:                 Bytevectors.         (line  30)
   3825 * immutable-pair?:                       Pairs and lists.     (line  35)
   3826 * immutable-string?:                     Strings.             (line  51)
   3827 * immutable-vector?:                     Vectors.             (line  30)
   3828 * inert:                                 Control.             (line   6)
   3829 * inert?:                                Control.             (line  11)
   3830 * inexact?:                              Numbers.             (line  98)
   3831 * input-port?:                           Ports.               (line  32)
   3832 * integer->char:                         Characters.          (line  74)
   3833 * integer?:                              Numbers.             (line  61)
   3834 * interpreter:                           Interpreter.         (line   6)
   3835 * Kernel history:                        Kernel History.      (line   6)
   3836 * keyed dynamic variables:               Keyed Variables.     (line  15)
   3837 * keyed static variables:                Keyed Variables.     (line  40)
   3838 * keyed variables:                       Keyed Variables.     (line   6)
   3839 * lcm:                                   Numbers.             (line 221)
   3840 * length:                                Pairs and lists.     (line 229)
   3841 * libraries:                             Libraries.           (line   6)
   3842 * library?:                              Libraries.           (line  47)
   3843 * list:                                  Pairs and lists.     (line  82)
   3844 * list*:                                 Pairs and lists.     (line  88)
   3845 * list->bytevector:                      Bytevectors.         (line  63)
   3846 * list->string:                          Strings.             (line 131)
   3847 * list->vector:                          Vectors.             (line  63)
   3848 * list-copy:                             Pairs and lists.     (line 142)
   3849 * list-neighbors:                        Pairs and lists.     (line 266)
   3850 * list-ref:                              Pairs and lists.     (line 236)
   3851 * list-tail:                             Pairs and lists.     (line 185)
   3852 * lists:                                 Pairs and lists.     (line   6)
   3853 * load:                                  Ports.               (line 417)
   3854 * log:                                   Numbers.             (line 403)
   3855 * make-bytevector:                       Bytevectors.         (line  37)
   3856 * make-encapsulation-type:               Encapsulations.      (line  12)
   3857 * make-environment:                      Environments.        (line  36)
   3858 * make-inexact:                          Numbers.             (line 285)
   3859 * make-kernel-standard-environment:      Environments.        (line 119)
   3860 * make-keyed-dynamic-variable:           Keyed Variables.     (line  21)
   3861 * make-keyed-static-variable:            Keyed Variables.     (line  44)
   3862 * make-library:                          Libraries.           (line  55)
   3863 * make-list:                             Pairs and lists.     (line 133)
   3864 * make-string:                           Strings.             (line  78)
   3865 * make-vector:                           Vectors.             (line  37)
   3866 * map <1>:                               Combiners.           (line  96)
   3867 * map:                                   Pairs and lists.     (line 207)
   3868 * max:                                   Numbers.             (line 213)
   3869 * member?:                               Pairs and lists.     (line 297)
   3870 * memoize:                               Promises.            (line  74)
   3871 * memq?:                                 Pairs and lists.     (line 380)
   3872 * min:                                   Numbers.             (line 214)
   3873 * mod:                                   Numbers.             (line 165)
   3874 * mod0:                                  Numbers.             (line 179)
   3875 * mutable-bytevector?:                   Bytevectors.         (line  31)
   3876 * mutable-pair?:                         Pairs and lists.     (line  36)
   3877 * mutable-string?:                       Strings.             (line  52)
   3878 * mutable-vector?:                       Vectors.             (line  31)
   3879 * negative?:                             Numbers.             (line 193)
   3880 * newline:                               Ports.               (line 251)
   3881 * nil:                                   Pairs and lists.     (line   6)
   3882 * not?:                                  Booleans.            (line  16)
   3883 * null?:                                 Pairs and lists.     (line  31)
   3884 * number->string:                        Numbers.             (line 439)
   3885 * number?:                               Numbers.             (line  57)
   3886 * numbers:                               Numbers.             (line   6)
   3887 * numerator:                             Numbers.             (line 329)
   3888 * object descriptions:                   A Sample Applicative Description.
   3889                                                               (line   6)
   3890 * odd?:                                  Numbers.             (line 200)
   3891 * open-binary-input-file:                Ports.               (line  99)
   3892 * open-binary-output-file:               Ports.               (line 115)
   3893 * open-input-bytevector:                 Ports.               (line 136)
   3894 * open-input-file:                       Ports.               (line  98)
   3895 * open-input-string:                     Ports.               (line 134)
   3896 * open-output-bytevector:                Ports.               (line 149)
   3897 * open-output-file:                      Ports.               (line 113)
   3898 * open-output-string:                    Ports.               (line 142)
   3899 * operative descriptions:                A Sample Applicative Description.
   3900                                                               (line   6)
   3901 * operative?:                            Combiners.           (line  16)
   3902 * operatives:                            Combiners.           (line   6)
   3903 * or?:                                   Booleans.            (line  24)
   3904 * output-port?:                          Ports.               (line  33)
   3905 * pair?:                                 Pairs and lists.     (line  27)
   3906 * pairs:                                 Pairs and lists.     (line   6)
   3907 * peek-char:                             Ports.               (line 321)
   3908 * peek-u8:                               Ports.               (line 375)
   3909 * port-open?:                            Ports.               (line  67)
   3910 * port?:                                 Ports.               (line  28)
   3911 * ports:                                 Ports.               (line   6)
   3912 * positive?:                             Numbers.             (line 192)
   3913 * printing notation:                     Printing Notation.   (line   6)
   3914 * promise?:                              Promises.            (line  31)
   3915 * promises:                              Promises.            (line   6)
   3916 * raise:                                 Errors.              (line  36)
   3917 * rational?:                             Numbers.             (line  81)
   3918 * rationalize:                           Numbers.             (line 355)
   3919 * read:                                  Ports.               (line 204)
   3920 * read-char:                             Ports.               (line 309)
   3921 * read-line:                             Ports.               (line 275)
   3922 * read-u8:                               Ports.               (line 362)
   3923 * real->exact:                           Numbers.             (line 301)
   3924 * real->inexact:                         Numbers.             (line 300)
   3925 * real?:                                 Numbers.             (line  86)
   3926 * reduce:                                Pairs and lists.     (line 312)
   3927 * register-requirement!:                 Ports.               (line 464)
   3928 * registered-requirement?:               Ports.               (line 463)
   3929 * rename-file:                           System.              (line  42)
   3930 * require:                               Ports.               (line 440)
   3931 * reverse:                               Pairs and lists.     (line 150)
   3932 * robust?:                               Numbers.             (line 102)
   3933 * root-continuation:                     Continuations.       (line 104)
   3934 * round:                                 Numbers.             (line 342)
   3935 * set-car!:                              Pairs and lists.     (line  51)
   3936 * set-cdr!:                              Pairs and lists.     (line  52)
   3937 * simplest-rational:                     Numbers.             (line 356)
   3938 * sin:                                   Numbers.             (line 404)
   3939 * sqrt:                                  Numbers.             (line 390)
   3940 * string:                                Strings.             (line  84)
   3941 * string->bytevector:                    Strings.             (line 134)
   3942 * string->immutable-string:              Strings.             (line 125)
   3943 * string->list:                          Strings.             (line 130)
   3944 * string->number:                        Numbers.             (line 420)
   3945 * string->symbol:                        Symbols.             (line  26)
   3946 * string->vector <1>:                    Vectors.             (line  80)
   3947 * string->vector:                        Strings.             (line 132)
   3948 * string-append:                         Strings.             (line 116)
   3949 * string-ci<=?:                          Strings.             (line  72)
   3950 * string-ci<?:                           Strings.             (line  71)
   3951 * string-ci=?:                           Strings.             (line  70)
   3952 * string-ci>=?:                          Strings.             (line  74)
   3953 * string-ci>?:                           Strings.             (line  73)
   3954 * string-copy:                           Strings.             (line 120)
   3955 * string-downcase:                       Strings.             (line 141)
   3956 * string-fill!:                          Strings.             (line 102)
   3957 * string-foldcase:                       Strings.             (line 143)
   3958 * string-for-each:                       Control.             (line  53)
   3959 * string-length:                         Strings.             (line  88)
   3960 * string-map:                            Combiners.           (line 120)
   3961 * string-port?:                          Ports.               (line  55)
   3962 * string-ref:                            Strings.             (line  91)
   3963 * string-set!:                           Strings.             (line  97)
   3964 * string-titlecase:                      Strings.             (line 142)
   3965 * string-upcase:                         Strings.             (line 140)
   3966 * string<=?:                             Strings.             (line  64)
   3967 * string<?:                              Strings.             (line  63)
   3968 * string=?:                              Strings.             (line  62)
   3969 * string>=?:                             Strings.             (line  66)
   3970 * string>?:                              Strings.             (line  65)
   3971 * string?:                               Strings.             (line  47)
   3972 * strings:                               Strings.             (line   6)
   3973 * substring:                             Strings.             (line 107)
   3974 * symbol->string:                        Symbols.             (line  22)
   3975 * symbol?:                               Symbols.             (line  18)
   3976 * symbols:                               Symbols.             (line   6)
   3977 * system:                                System.              (line   6)
   3978 * tan:                                   Numbers.             (line 406)
   3979 * textual-port?:                         Ports.               (line  42)
   3980 * truncate:                              Numbers.             (line 341)
   3981 * u8-ready?:                             Ports.               (line 390)
   3982 * u8?:                                   Numbers.             (line  73)
   3983 * undefined?:                            Numbers.             (line 106)
   3984 * unregister-requirement!:               Ports.               (line 466)
   3985 * unwrap:                                Combiners.           (line  72)
   3986 * vector:                                Vectors.             (line  58)
   3987 * vector->bytevector <1>:                Bytevectors.         (line  74)
   3988 * vector->bytevector:                    Vectors.             (line  71)
   3989 * vector->immutable-vector:              Vectors.             (line 121)
   3990 * vector->list:                          Vectors.             (line  62)
   3991 * vector->string <1>:                    Vectors.             (line  79)
   3992 * vector->string:                        Strings.             (line 133)
   3993 * vector-copy:                           Vectors.             (line  67)
   3994 * vector-copy!:                          Vectors.             (line  86)
   3995 * vector-copy-partial:                   Vectors.             (line  94)
   3996 * vector-copy-partial!:                  Vectors.             (line 104)
   3997 * vector-fill!:                          Vectors.             (line 115)
   3998 * vector-for-each:                       Control.             (line  54)
   3999 * vector-length:                         Vectors.             (line  43)
   4000 * vector-map:                            Combiners.           (line 121)
   4001 * vector-ref:                            Vectors.             (line  46)
   4002 * vector-set!:                           Vectors.             (line  52)
   4003 * vector?:                               Vectors.             (line  26)
   4004 * Vectors:                               Vectors.             (line   6)
   4005 * with-error-to-file:                    Ports.               (line  76)
   4006 * with-input-from-file:                  Ports.               (line  73)
   4007 * with-output-to-file:                   Ports.               (line  75)
   4008 * with-strict-arithmetic:                Numbers.             (line 313)
   4009 * wrap:                                  Combiners.           (line  68)
   4010 * write:                                 Ports.               (line 218)
   4011 * write-char:                            Ports.               (line 297)
   4012 * write-simple:                          Ports.               (line 236)
   4013 * write-u8:                              Ports.               (line 349)
   4014 * zero?:                                 Numbers.             (line 158)
   4015 
   4016 
   4017 
   4018 Tag Table:
   4019 Node: Top708
   4020 Node: License2942
   4021 Node: Introduction4629
   4022 Node: Caveats7562
   4023 Node: Kernel History8348
   4024 Node: Conventions9793
   4025 Node: Some Terms10464
   4026 Node: Evaluation Notation11135
   4027 Node: Printing Notation12156
   4028 Node: Error Messages12632
   4029 Node: Format of Descriptions13280
   4030 Node: A Sample Applicative Description13844
   4031 Node: Acknowledgements15607
   4032 Node: Interpreter15993
   4033 Ref: Command Line Options18293
   4034 Ref: Interpreter Exit Status19227
   4035 Node: Booleans20455
   4036 Node: Equivalence23132
   4037 Node: Symbols23925
   4038 Node: Control25555
   4039 Node: Pairs and lists29646
   4040 Node: Environments48526
   4041 Node: Combiners59199
   4042 Node: Continuations65853
   4043 Node: Encapsulations74396
   4044 Node: Promises75849
   4045 Node: Keyed Variables80004
   4046 Node: Numbers82775
   4047 Node: Strings105229
   4048 Node: Characters112502
   4049 Node: Ports117148
   4050 Node: Vectors140847
   4051 Node: Bytevectors146601
   4052 Node: Errors152420
   4053 Node: Libraries154435
   4054 Node: System163195
   4055 Node: Alphabetical Index166693
   4056 
   4057 End Tag Table