Munger(1)               FreeBSD General Commands Manual              Munger(1)

NAME
     munger -- Lisp specialized for 8-bit text processing

SYNOPSIS
     munger [<script> [<args> ...]]

DESCRIPTION
     Munger is a simple, statically-scoped lisp interpreter, specialized for
     writing processors for 8-bit text.  Munger makes it easy to write edi-
     tors, shells, filters, CGI scripts, and low-demand network client and
     server programs.  The name "Munger" is a joke.  Mung (or munge) means to
     destructively scramble data, in computer jargon.

     Munger can manipulate strings with regular expressions, perform limited
     magnitude integer arithmetic, and communicate with child processes and
     remote hosts.  The interpreter has an optional interface to the SQLite
     library, which may be included at compilation time.  With Munger the pro-
     grammer may write text-processing filters, if serial access to the text
     is sufficient, or the programmer may load text into buffers and have
     line-oriented random access to those lines, if that is more convenient.
     Buffer lines can be inserted, removed, overwritten, retrieved in whole or
     in part, with or without tabs expanded, searched for matches on regular
     expressions, be read from and written to files, and be piped to and from,
     or filtered through, external processes.

     Having used a number of "dynamic" languages over the years for text-pro-
     cessing, I came to the conclusion what I really wanted was a simple lan-
     guage which could do what ed(1) and sed(1) could do, which is to say, a
     regular-expression-wielding tool which could be used to write filters, or
     if it were more convenient, load files into buffers in order to manipu-
     late lines in arbitrary order.  In response to this want, I hacked-up an
     interpreter in C and hung some functions off of it, stealing a few ideas
     from Perl.  It is best at interpreting programs written in an imperative
     style.  You can use it to write programs in a functional style, but they
     will run less efficiently.  In particular, do not use lists to represent
     large complex data structures, and do not use recursive algorithms or you
     may overflow the process stack.  Use tables, stacks, and records, and use
     imperative algorithms.

     This document begins with an overview of the language, followed by a com-
     plete reference for every intrinsic function and macro, and library func-
     tion and macro included in the Munger package.  A list of these precedes
     the reference section, immediately after the following overview.

     A variety of example programs are included in the source distribution.
     They are installed in (libdir), and are described below.  Dickens, a text
     editor written in Munger, is available as a separate port in ${PORTS-
     DIR}/editors/dkns.

     The munger website is here:

     http://www.mammothcheese.ca/munger.html

   Included Example Programs
     cat.munger        is a version of the cat utility, the simplest possible
                       filter.

     grep.munger       is an egrep-like filter.

     options.munger    is a module which simplifies the processing of command-
                       line arguments.

     fmt.munger        is a version of the fmt utility.

     cal.munger        Prints a calender of the current month to stdout.
                       Demonstrates date arithmetic functions.

     filter.munger     is a simple filter which expands documents with embed-
                       ded munger code in them.

     transform.munger  performs a set of regular expression based substitu-
                       tions destructively over a set of files.

     view.munger       is a file viewer resembling vi when invoked as view.
                       It demonstrates character-I/O and cursor addressing.

     mush.munger       is a job control shell. It demonstrates how to control
                       process groups.

     xml2alist.munger  is a minimal XML parser which will convert a standalone
                       XML 1.0 document into an alist which may be queried for
                       structure and content with the xmlquery.munger module.
                       The program is a filter, reading XML from stdin and
                       printing to stdout a lisp representation of the XML.

     xml2buffer.munger
                       This is another version of the above XML parser which
                       instead of printing the lisp representation of the con-
                       verted XML document to stdout, inserts it into the cur-
                       rent buffer, from where it may be read by the lisp
                       reader with the "eval_buffer" intrinsic.  This module
                       can also read the XML document from a string.

     xml2sqlite.munger
                       is another version of the XML parser, which serializes
                       the XML document into an SQLite database file.

     xmlsqlite.munger  is a module providing helper functions to access a
                       database containing an XML document serialized by
                       xml2sqlite.munger.

     rss.munger        prints to stdout an RSS feed which has been converted
                       into a SQLite database file by xml2sqlite.munger.  It
                       demonstrates accessing a database created by
                       xml2sqlite.munger.

     xmlquery.munger   is a module which may be used to extract data from a
                       document processed with the XML parsers included in the
                       Munger distribution, which store their results in
                       lists.

     echo.munger       is an echo server, demonstrating the basic form of net-
                       work servers in Munger.  See the entry for the "lis-
                       ten", "listen_unix", "accept", and "daemonize" intrin-
                       sics, in the LANGUAGE REFERENCE part of this document,
                       below, for more information on writing servers.  Munger
                       is best suited to creating moderate-demand servers for
                       private use.

     httpd.munger      is a non fully-conforming HTTP/1.1 server.  This server
                       is not intended for use on public websites.  It is an
                       example of how to write a non-trival server in Munger.
                       Munger is best suited to writing moderate-demand
                       servers for private use, and for prototyping.

IMPLEMENTATION NOTES
     o   The Munger implementation is designed to be easy to understand and
         extend.  It is a naive implementation, and will perform best when
         interpreting programs written in an imperative programming style.
         Any general-purpose lisp/Scheme implementation out there will out-
         perform Munger.

     o   Munger's strings are 8-bit clean, but some of the intrinsic functions
         in the interpreter cannot handle embedded NULs.  This should not be a
         problem, as it is unlikely you will want to apply these functions to
         binary strings.  A full list of 8-bit safe intrinsics is specified in
         the section below entitled STRINGS.

     o   Munger's string-manipulation functions are "functional" in that they
         do not modify their arguments, but return new strings.

     o   There is only one namespace, but namespaces may be simulated with
         lexical closures.

     o   There is a "dynamic_let" to impose dynamically-scoped changes upon a
         single global at a time.

     o   The function position of applications is fully-evaluated and must
         evaluate to an intrinsic function or a closure, as in Scheme.  The
         order of evaluation of the terms of an application is fixed, from
         left to right, and may be relied upon in computations.

     o   Munger does not recognize tail-calls, however you may explicitly
         request tail-calls with the "tailcall" intrinsic.  This mechanism
         allows even anonymous functions to be tail-recursive, and can be used
         to turn non-tail positions into tail positions.  Using function
         calls, whether they be tail-calls or not, to perform iteration in
         Munger will always be orders of magnitude slower than using one of
         the looping intrinsics.

     o   As in Perl, all values are considered to be boolean "true" values
         except for the empty list, the empty string, and zero.  There is no T
         nor NIL object, nor #t or #f.

     o   All functions return a value.  There are no undefined or unspecified
         return values used in this interpreter.

     o   Improper lists cannot be formed in Munger.  The final "cdr" of all
         lists is the empty list.

     o   The empty list is a constant which evaluates to itself, and it is a
         list, not an atom.  Every empty list is identical to every other
         empty list, which is to say they are "eq" to each other.

     o   "eq" in Munger behaves similarly to "eql" in Common Lisp.  A true
         "eq", which only returns a true value when comparing an object to
         itself, has very limited use, and therefore I have not bothered to
         include one.  There is an "equal" as well, which does what you think
         it does.  It is defined in (join "/" (libdir) "library.lsp").

     o   "eval" does not contain the lisp reader, therefore applying "eval" to
         a string will not parse lisp code in the string, but simply cause the
         original string to be returned (strings are constants).  There is a
         separate "eval_string" intrinsic.

     o   There are no destructive list operations.  Munger forces the program-
         mer to use simple constructive list manipulations.  Munger's "list"
         and "append" intrinsics are "functional" in that they make copies of
         their arguments before forming them into the final returned lists.

     o   Munger's looping constructs are modelled on those of C.  The most
         efficient way to iterate is to use the "for", "iterate", or "loop"
         intrinsics.

     o   The set of intrinsics is purposefully-limited to a minimal set useful
         for text processing.  There are many intrinsics with names similar to
         those of other lisp dialects, which do not perform similar tasks.  Be
         forewarned.

     o   Symbol syntax is similar to symbol syntax in C, including case-sensi-
         tivity.  "let*" therefore, is "letn" in Munger.  If you are used to
         hyphenating symbol names, you will have to get used to using the
         underscore in place of the hyphen to be happy here.

     o   Simple "eval-twice" macros and gensyms are supported.  A macro defi-
         nition differs from a function definition in that the initial
         "lambda" symbol is replaced with the "macro" symbol.

     o   Besides lists, three other aggregate types are provided by the lan-
         guage: one-dimensional dynamically-resizable arrays called "stacks",
         associative arrays called "tables", and statically-sized one-dimen-
         sional arrays called "records".

     o   There are no interactive debugging facilities in the interpreter, nor
         any editing capabilities at the interpreter prompt, beyond those pro-
         vided by the terminal driver (CTRL-H, CTRL-W, CTRL-U).  To debug
         scripts the `(print "I made it here!")(exit 1)' technique is used by
         the author.

   STARTUP
     The interpreter attempts to read three files at startup, in order.  The
     first, the system library (library.munger), is read from the Munger data
     directory (the "libdir" intrinsic will return the fully-qualified path of
     the data directory).  Then, if the user has a custom lisp library
     (.munger) in his or her home directory, it is read, and lastly, any file
     specified by the first command-line argument is read.

     The succeeding command-line arguments, if present, are considered to be
     arguments to the script referenced by the first command-line argument,
     and are not accessed by the interpreter.  All the command line arguments
     may be accessed from lisp programs with the "current" "rewind", "next",
     and "prev" intrinsics, described in the reference section at the end of
     this document.

   COMMENTS
     If the parser encounters a semicolon (;) or an octothorpe (#), outside of
     a string token, the rest of the line from that character to the next new-
     line or carriage return is considered to be a comment and discarded.
     Recognizing the octothorpe as well as the traditional semicolon comment-
     character, allows one to put a "shebang" line at the top of one's
     scripts, in order to have the system feed the script to the interpreter,
     if the script itself is invoked as a command from the shell.

           #!/usr/local/bin/munger

   SYMBOLS
     The interpreter is case-sensitive when it comes to recognizing all
     tokens.  Symbol names must consist of only sequences of alphanumeric
     characters and the underscore (_), and must not start with numerical
     characters.

   NUMBERS
     The interpreter supports only one numerical type, the fixnum.  Fixnums
     are fixed-size integers which can be manipulated efficiently by the
     interpreter.  The binary size of the fixnum is the word size of the
     machine the interpreter is running on.  Arithmetical operations which
     overflow this size, will not be detected.  The "maxidx" intrinsic will
     return the value of the largest fixnum the interpreter can represent.
     The lowest supported fixnum will be one more than the value returned by
     "maxidx", negated.  This can be demonstrated by adding 1 to the value
     returned by "maxidx" to cause the two's-complement representation to
     "wrap-around" to the negative side.  There is an "unsigned" intrinsic
     which can be used to display the result of unsigned arithmetic operations
     which wrap-around to the negative side.

     > (setq max (maxidx))
     1073741823
     > (+ max 1)
     -1073741824

     When an integer value is read by the lisp reader it is represented inter-
     nally as a fixnum.  If the value is too large or too small to be repre-
     sented in that form, the value is silently truncated to fit.

   STRINGS
     Arbitrary strings of character data can be placed between " marks (ASCII
     34).  Such tokens are constants and evaluate to themselves. " marks may
     be embedded into strings if they are escaped with a backslash:

     > "asd\""
     "asd""

     A backslash occurring at the end of a string will be interpreted as
     escaping the closing " character.  To make it possible for the lisp
     reader to read a string ending with a backslash, it is necessary, there-
     fore, to have a means of escaping backslashes.  Backslashes are therefore
     escaped with themselves:

     > "asd\\"
     "asd\"

     Backslashes are interpreted as escapes only when the occur before another
     backslash or a " character.  Backslashes not followed by a " character or
     another backslash, are inserted into the string.  The following two
     strings are therefore identical:

     > "\a"
     "\a"
     > "\\a"
     "\a"

     It is only necessary to employ these escapes in strings to be parsed by
     the lisp reader, that is to say, in the literal strings in your source
     code.  These two characters may be inserted into strings programmati-
     cally, without escaping them:

     > (char 34)
     """
     > (char 92)
     "\"

     The interpreter has a small set of string manipulation intrinsics, some
     you would expect in any language, such as the "substring" and "strcmp"
     functions, and others like the "split", "join", "chomp" and "chop"
     intrinsics, which are inspired by similar functions in Perl.  Regular
     expressions can be used to find matches on substrings or to transform
     strings.  There is no character data type.  Single-character strings are
     used instead.  All string operations are documented in the LANGUAGE REF-
     ERENCE section of this document.

     Munger's strings are 8-bit clean, but not all of the intrinsics which use
     strings will function correctly when confronted with strings which have
     embedded NULs in them.  The following intrinsics will, however:

     getline, getchar, getchars, print, cgi_read, cgi_print, code, substring,
     stringify, concat, join, chop, chomp, insert, retrieve, slice, strcmp,
     child_read, child_write, getline_ub

     Due to a change in the regular expression library used by Munger, as of
     Munger 4.172, the following regular expression related intrinsics no
     longer work with strings with embedded NULs in them:

     regcomp, match, matches, substitute, replace

     The "split" intrinsic, notably, will work correctly when its first argu-
     ment is the empty string and its second argument contains NULs.  The pro-
     grammer should avoid presenting binary strings to any other intrinsics
     than those guaranteed to work with them.

   STACKS, TABLES, AND RECORDS
     Munger supports an associative array type called a table.  Associative
     arrays are collections of pairs of lisp atoms and arbitrary lisp objects.
     The atom is called the "key" and is used to retrieve the other object,
     called the "value" from the table.  Tables are implemented internally as
     hash tables, hence the name.  For more information on usings tables, see
     the entries for the intrinsics listed under the heading entitled, Tables,
     in the LANGUAGE REFERENCE occurring later in this document.

     Munger also supports a dynamically-resizable unidimensional array type
     called a stack.  Stacks may be treated as push-down stacks or indexed as
     arrays.  Internally, stacks are implemented as unidimensional arrays, but
     they are called stacks to emphasize their one-dimensional nature.  Any
     lisp object may be stored in a stack.  The capacity of stacks may be
     increased dynamically, simply by "pushing" items onto them, but stacks
     never decrease in size.  Multi-dimensional arrays may be simulated using
     stacks of stacks.  For more information on using stacks, see the entries
     for the intrinsics listed under the heading entitled, Stacks, in the LAN-
     GUAGE REFERENCE occurring later in this document.

     In addition to stacks and tables, an aggregate type called a record is
     provided.  Records are fixed-size unidimensional arrays.  They are more
     time-and-space-efficient means of representing fixed-size structures than
     lists, tables, or stacks.

     Tables, stacks, and records are opaque constant atoms which evaluate to
     themselves.

   FILES
     File I/O may be performed in one of two ways.  The content of files may
     be read into text buffers, manipulated, then written out again, if random
     access to the files' content is desired, or the standard descriptors may
     be redirected onto files with the "redirect" intrinsic, if line-oriented,
     serial (filter-like) access is sufficient.  Three convenience macros
     "with_input_file", "with_output_file", and "with_error_file" simplify the
     process:

     > (with_input_file "README"
     >> (for (a 1 4) (print a (char 9) (getline))))
     1  Munger
     2  ======
     3
     4  Munger is a simple, statically-scoped, interpreted lisp that has

     All redirections are undone upon return to toplevel.  Redirections made
     with "redirect" may be explicitly undone in programs with the "resume"
     intrinsic.  Redirections made with the "with_input_file", "with_out-
     put_file", and "with_error_file" macros are undone automatically when
     those macros return.  Redirections made with these macros are dynami-
     cally-scoped, which is to say their visibility is unlimited, but their
     extent is limited to the duration of the macro.  Redirections exhibit
     stack-like behavior, allowing nested redirections to "shadow" enclosing
     redirections:

     > (with_input_file "README"
     >> (print (getline))
     Munger
     >> (with_input_file "lisp.h"
     >>> (print (getline)))
     /*
     >> (print (getline)))
     ======

     The "temporary" intrinsic will redirect stdout onto a temporary file
     opened for writing, via mkstemp(2).  The function returns the name of the
     file.  A convenience macro is provided, "with_temporary_output_file":

     > (setq filename (with_temporary_output_file (print "foobar")))
     "/tmp/munger2nvIa8D98M"

     > (with_input_file filename
     >> (print (getline)))
     "foobar"

     > (unlink filename)
     1

     Two macros simplify the writing of filters:  "foreach_line" and "fore-
     ach_line_callback".  Both accept a monadic function to be applied succes-
     sively to each line of input, the second also accepts an additional func-
     tion to be called when the input source changes.  Both macros determine
     whether to read data from the standard input or from files specified on
     the command line based on the existence of command line arguments after
     the first two, which will always be the name of the interpreter and the
     name of the currently-executing script, respectively.  Here is what "cat"
     looks like in Munger:

     (next)
     (foreach_line print)
     (exit 0)

     The example programs further demonstrate the use of these macros.  They
     are fully documented later in this document.

   COMMUNICATING WITH CHILD PROCESSES
     The interpreter's standard descriptors can be redirected onto processes
     with the "pipe" intrinsic.  Successive invocations of "pipe" inherit any
     already-made redirections, allowing pipelines to be created.  The
     "with_input_process" and "with_output_process" macros simplify the
     process:

     > (with_input_process "jot 100"
     >> (with_input_process "fmt"
     >>> (while (setq l (getline))
     >>>> (print l))))
     1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
     26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
     48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
     70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91
     92 93 94 95 96 97 98 99 100

     Upon return to toplevel, all redirections are undone.  Redirections are
     explicitly undone with the "resume" intrinsic.  The first argument is
     passed to the shell (always /bin/sh), and so may be any expression that
     program understands.  Because of this it is actually more efficient to
     let the shell create the pipeline for us:

     > (with_input_process "jot 100 | fmt" ...

     The curl(1) utility may be used to redirect standard input onto a remote
     file via ftp or http:

     > (with_input_process "curl -s 'ftp://www.freebsd.org/pub/FreeBSD/README.TXT'"
     >> (for (n 1 10) (print n (char 9) (getline))))
     1  Welcome to the FreeBSD archive!
     2  -------------------------------
     3
     4  Here you will find the official releases of FreeBSD, along with
     5  the ports and packages collection and other FreeBSD-related
     6  material.  For those who have World Wide Web access, we encourage
     7  you to visit the FreeBSD home page at:
     8
     9   http://www.FreeBSD.org/
     10

     The munger code below is the equivalent of the shell command:

     # cmd < infile 2> errfile | cmd2 > outfile

     (redirect 0 "infile")
     (redirect 2 "errfile")
     (pipe 0 "cmd")
     (redirect 1 "outfile")
     (resume 2)
     (exec "cmd2")

     The "getstring" library function will fork a local program and accumulate
     all the returned data from it into a single string.  Here we run curl
     locally to retrieve a remote file as a single string:

     > (getstring "curl -s 'http://www.mammothcheese.ca/robots.txt'")
     "User-Agent: *
     Disallow: /cgi-bin/"

     If we use curl(1) as intermediary, it can handle HTTP redirects, remove
     the HTTP header and merge chunked responses, leaving us with just the
     requested resource's data.  To see the HTTP header for ourselves, we can
     connect a socket directly to the server with the "child_open" intrinsic.
     The presence of a second port number argument to "child_open" tells the
     interpreter this is a request to connect to a network server.

     > (child_open "www.mammothcheese.ca" 80)
     1
     > (child_write "GET /robots.txt HTTP/1.0" (char 13) (char 10) (char 13) (char 10))
     1
     > (while (stringp (setq line (child_read)))
     >>  (print line))
     HTTP/1.0 200 OK
     Content-Type: text/plain; charset=utf-8
     Content-Length: 24
     Last-Modified: Tue, 12 Jun 2007 16:10:51 GMT
     Server: Drood/1.14 (FreeBSD/6.1/i386)
     Date: Sun, 02 Sep 2007 01:27:20 GMT

     User-agent: *
     Disallow:

     "child_open" creates a full-duplex communication stream, while "pipe",
     "redirect", and the "with_input_*" and "with_output_*" macros create only
     unidirectional streams off of the standard descriptors.  Only one full-
     duplex connection can be active at any time, but it exists independently
     of whatever source the standard descriptors are connected to.  With a
     port number argument of 0, "child_open" attempts to connect to another
     process listening on a UNIX domain socket.  Without a port number argu-
     ment "child_open" forks a local program:

     > (child_open "munger")
     1
     > (child_write "(setq foobar 43)")
     1
     > (chomp (child_read))
     "43"
     > (child_close)
     1

   TEXT BUFFERS
     Munger provides line-oriented buffers for storing large amounts of text.
     A buffer must be opened before it can be used, with the "open" intrinsic,
     and may be closed with the "close" intrinsic.  A whole number is returned
     by "open" upon success, called the buffer number of the opened buffer.
     Only one buffer, out of those currently open, can be active at any time,
     and is called the current buffer.  Each call to "open" creates a new
     buffer and makes the new buffer the current buffer.  The buffer number of
     an open buffer may be passed as the argument to the "switch" intrinsic to
     make that buffer the current buffer.

     A number of intrinsics are provided which act upon the current buffer, to
     insert, retrieve, and delete lines, to report the number of words and
     lines in the buffer, and to write and read buffer lines, to and from,
     files and programs.  Lines may be retrieved whole, or in slices with tabs
     expanded.  A range of buffer lines may be processed through an external
     program with the "filter" intrinsic, while the "find" intrinsic may be
     used to search through the current buffer to find non-overlapping matches
     on regular expressions.  A range of lines may be copied from one buffer
     to another with the "transfer" intrinsic.  There is also intrinsics to
     set and find bookmarks in buffers.  The full list of buffer intrinsics
     can be found later in this document at the top of the LANGUAGE REFERENCE
     section, under the subheading, Buffer Operations.  Each is fully
     described in its own particular entry.

     ; Loading a buffer from a file:

     > (open)
     0
     > (read 0 "README")
     38 ; Number of lines read.
     > (for (a 1 5) (print (retrieve a)))
     Munger
     ======

     Munger is a simple, statically-scoped, interpreted lisp that has
     line-editor-like access to multiple text buffers, for use on the FreeBSD

     ; Loading a buffer from a process:

     > (empty)
     1
     > (input 0 "ls")
     20
     > (for (a 1 (lastline)) (print (retrieve a)))
     LICENSE
     Makefile
     README
     cat.munger
     client.munger
     err.munger
     cgi.munger
     fmt.munger
     grep.munger
     intrinsics.c
     library.munger
     lisp.c
     lisp.h
     options.munger
     munger.man
     transform.munger

     ; Filtering buffer content through a process:

     > (filter 1 (lastline) "fmt")
     3 ; Number of lines received back from filter.

     > (for (a 1 (lastline)) (print (retrieve a)))
     LICENSE Makefile README cat.munger client.munger err.munger cgi.munger
     fmt.munger grep.munger intrinsics.c library.munger lisp.c lisp.h options.munger
     munger.man transform.munger

     ; Loading a buffer from a remote file using curl(1):

     > (empty)
     1
     > (input 0 "curl -s 'http://www.mammothcheese.ca/index.html'")
     296 ; Number of lines read.

     ; Finding the location of a match on a regular expression:

     > (setq rx (regcomp "<body[^>]*>"))
     <REGEX#1>
     > (find 1 1 0 rx 0)
     (27 3 6)
     > (slice 27 3 6 1 0)
     "<body>"

     ; Filtering a buffer through an HTTP server:

     > (empty)
     1
     > (insert 1 (concat "GET /Slashdot/slashdot HTTP/1.0" (char 13) (char 10)) 0)
     1
     > (insert 2 (concat (char 13) (char 10)) 0)
     1
     > (filter_server 1 2 "rss.slashdot.org" 80)
     272

     ; Get rid of the HTTP header and condense a possibly chunked response body:

     > (remove_http_stuff)
     0

     ; Filter the XML document left in the buffer through the xml2alist example
     ; program:

     > (filter 1 (lastline) (join "/" (libdir) "xml2alist.munger"))
     264

     ; The buffer now contains a lisp representation of the XML we can use
     ; the xmlquery.munger example module with:

     > (load (join "/" (libdir) "xmlquery.munger"))
     <CLOSURE#24>

     ; Evaluate the buffer content as lisp:

     > (eval_buffer)
     [ Converted document scrolls by dramatically! ]

     ; Make a query.  Let's see the cdata content of the title elements of the
     ; RSS feed:

     > (dynamic_let (document (get_elements "item" "document" 1 "rdf:RDF" 1))
     >> (while document
     >>> (println (get_cdata "item" 1 "title" 1))
     >>> (setq document (cdr document))))

     Unrefined "Musician" Gains a Global Audience
     Open Source Laser Business Opens In New York
     OpenOffice.org 2.1 Released With New Templates
     Texas Lawmaker Wants To Let the Blind Hunt
     Designer Glasses With Microdisplay Unveiled
     Arctic Ice May Melt By 2040
     DIY Service Pack For Windows 2000/XP/2003
     Sea Snail Toxin Offers Promise For Pain
     A Press Junket To Redmond
     The Dutch Kill Analog TV Nationwide
     Google  Web Toolkit Now 100% Open Source
     Novell and Microsoft Claim Customer Support
     Wikipedia Founder to Give Away Web Hosting
     How Craigslist is Keeping up Internet Ideals
     Norman &amp; Spolsky - Simplicity is Out

   REGULAR EXPRESSIONS
     Munger provides five intrinsic functions for working with extended regu-
     lar expressions.  All regular expressions must be compiled with the "reg-
     comp" intrinsic before they may be used by the other regular-expression
     wielding intrinsics.  The "match" intrinsic returns a list of two charac-
     ter indices describing a match.  The "matches" intrinsic returns a list
     of the text matched by the regular expression and up to 20 parenthesized
     subexpressions.  The "substitute" intrinsic is modelled after the substi-
     tute command from the vi/ex editor, and may be used to perform regular-
     expression-based substitution operations upon strings.  the "replace"
     library function allows snippets of lisp to be used for the replacement
     expression, allowing replacement text to be dynamically generated for
     each match in a string.  Lastly, the "find" intrinsic may be used to find
     the location of matches against a particular regular expression in the
     text in the current buffer.

     > (set 'rx (regcomp "munger"))
     <REGEXP#1>

     > (set 's "/usr/local/share/munger/library.munger")

     > (match rx s)
     (17 23)

     ; Text before match:

     > (substring s 0 17)
     "/usr/local/share/"

     ; Text of match:

     > (substring s 17 (- 23 17))
     "munger"

     ; Text after match:

     > (substring s 23 0)
     "/library.munger"

     > (set 'rx (regcomp "^/?([^/]+/)*([^/]+)"))
     <REGEXP#2>

     ; Full match and matched subexpressions:

     > (matches rx s)
     ("/usr/local/share/munger/library.munger" "munger/" "library.munger"
     "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "")

     ; Ex-like substitution:

     > (substitute rx "\U\2" "/usr/local/bin/munger" 1)
     "MUNGER"

     ; Dynamically-generated replacement strings for each match:

     (let ((r0 (regcomp "%([0-9A-Fa-f][0-9A-Fa-f])"))
           (r1 (regcomp "\+")))

        (defun decode (str)
           (replace r0
              (char (hex2dec m1))
              (substitute r1 " " str 0))))

     > (decode "foobar+tooley%7Efunbag%24%25%26")
     "foobar tooley~funbag$%&"

   FUNCTIONS
     The elements of function or macro applications are evaluated from left to
     right, with the function position being evaluated in the same environment
     as the succeeding positions.  The function position must be occupied by
     an expression that evaluates to a an intrinsic function object or a clo-
     sure.  Lambda- and macro-expressions evaluate to closure objects and are
     closed over the local bindings visible at that time:

     > (let ((a 10))
     >> (defun booger () a))
     <CLOSURE#32>
     > (booger)
     10

     With static scoping, the local bindings visible to a function are limited
     by the block structure in place at the time the function is created, but
     variable extent is unlimited, so the function "booger"'s reference to the
     enclosing block's variable "a" is still valid after the enclosing block
     has returned.  The binding is said to be "closed" within "booger" and is
     no longer visible anywhere else.

     In the example above, the invocation of "defun" creates a toplevel bind-
     ing, and not a new locally-visible binding, as an invocation of "define"
     would do in this position in Scheme.  Locally-visible bindings can only
     be created by function application ("let" is syntactic sugar for the
     application of an anonymous function), or by the "extend" intrinsic.  If
     the variable "booger" were a local variable in an enclosing scope, its
     binding would have been modified, creating a locally-visible function,
     but in this case, since no local binding exists, a new toplevel binding
     is created.

     When a lambda-expression is evaluated it is closed over the environment
     in which it is embedded to become a closure.  This means free variables
     visible in containing functions remain accessible.  Closures can be used
     to create shared lexical environments for functions which need to commu-
     nicate with each other, or they can be used to create static bindings
     which persist between invocations of a function, much like local vari-
     ables in C declared with the "static" storage class.  Because closures
     perform encapsulation they can be used to simulate objects in the mes-
     sage-passing style of object programming.  Closures can also be used to
     capture state for use in the continuation-passing style of programming.
     A full discussion of these topics is beyond the scope of this manual
     page.

     Functions may be defined to accept variable-length argument lists.  To
     specify that a function accepts a varying number of arguments, a final
     parameter to reference the optional arguments is enclosed in parentheses
     in the parameter list of the function definition.  For example,

     (lambda ((a)) (print a))

     defines a function which accepts zero or more arguments.  Upon invoca-
     tion, all arguments passed to the function will be collected into a list
     and bound to "a" inside the function body.  If no arguments are passed to
     the function, "a" will be bound to the empty list.

     The function below accepts two or more arguments, with any arguments
     after the second argument collected into a list bound to "c" in the func-
     tion body:

     (lambda (a b (c)) (print a b c))

     The "labels" intrinsic facilitates the creation of local function bind-
     ings, where each binding is visible inside each function definition.
     Recursive and mutually-recursive temporary functions therefore may be
     created with "labels".

     >(labels ((even (lambda (n) (or (eq n 0) (tailcall odd (- n 1)))))
     >>>       (odd  (lambda (n) (and (not (eq n 0)) (tailcall even (- n 1))))))
     >> (print (even 11))
     >> (newline)
     >> (print (even 12))
     >> (newline))
     0
     1
     1 ; this is the return value of the last (newline).

     There are "let", "letn", and "letf" macros to facilitate the creation of
     new lexical bindings.  "letn" corresponds to let* in other lisp dialects,
     while "letf" corresponds to a named let in Scheme or flet in lisp.  It
     may not be necessary to use these macros to create new lexical bindings,
     depending upon the needs of a particular situation.

     If the interpreter is a toplevel, then one of these macros must be used,
     or a closure applied, to create a lexical environment.  Inside a lexical
     environment, however, new bindings may be dynamically created with the
     "extend" intrinsic.  These bindings have unlimited extent just as all
     lexical bindings do, and so may be safely closed-over by closures.

     > (defun (a)
     >> (extend 'b (* a a))
     >> (lambda () b))

     If the programmer wishes to limit the extent of the new binding, the
     invocation of "extend" and the expressions which use the new binding may
     be wrapped in a "dynamic_extent" intrinsic:

     > (lambda (a)
     >> (extend 'f (lambda () b))

     >> (dynamic_extent
     >>> (extend 'b (* a a))
     >>> (print (f))) ; Works here inside "dynamic_extent"
                      ; even though f was closed before "extend" was invoked.
                      ; b suddenly "pops-up" into the lexical environment.
     >> (f)) ; ERROR: b is no longer extant here.

     Tail recursion is not recognized by the interpreter, but must be
     requested explicitly by the "tailcall" intrinsic.  This mechanism allows
     even anonymous functions to perform tail recursion.  See the entry for
     "tailcall" later in this document for more details.

     > (let ((n 10)
     >>>     (a 1))
     >> (if (< n 2)
     >>> a
     >>> (tailcall 0 (- n 1) (* a n))))
     3628800

   MACROS
     Macros allow us to define syntactic transformations.  With macros we can
     create new special operators for the interpreter in lisp.  A macro is
     simply a function which receives its arguments unevaluated, and instead
     has its return expression evaluated.  In other words, the purpose of a
     macro is to compose a new expression out of its arguments, which the
     interpreter then evaluates.  Despite this simple definition, the use of
     macros can become confusingly complex.  With macros, we write lisp which
     writes the lisp to be ultimately evaluated.

     A simple example is the "quit" macro defined in library.munger:

     (set 'quit (macro () '(exit 0)))

     We can see how a macro will expand with the test intrinsic:

     > (test (quit))
     (exit 0)

     Macros typically consist of a template expression into which we plug sub-
     expressions to produce the expression which is finally returned by the
     macro.  The "qquote" (quasiquote) macro aids in the defining of other
     macros, by allowing us to use the template paradigm directly.  This
     greatly simplifies complex macro definitions.  The "qquote" macro is sim-
     ilar to the "quote" intrinsic in that it prevents evaluation of its argu-
     ment, but the quoting can be selectively turned off for sub-expressions
     by prefacing them with a (",") comma character.  Here is the definition
     of the "with_input_file" macro from library.munger:

     (set 'with_input_file
        (macro (file (code))
           (qquote
              (when (> (redirect 0 ,file) 0)
                 (protect ,(cons 'progn code)
                    (resume 0))))))

     The sub-expressions prefaced by commas are evaluated and the result of
     the evaluations are inserted into the template expression.

     We can see how the macro will expand with the "test" intrinsic:

     > (test (with_input_file "library.munger" (getline)))
     (when (> (redirect 0 "library.munger") 0)
        (protect (progn (getline))
           (resume 0)))

     There is a "defmac" macro in library.munger which allows macros to be
     created with the following syntax:

     (defmac with_input_file (file (code))
        (qquote
           (when (> (redirect 0 ,file) 0)
              (protect ,(cons 'progn code)
                 (resume 0)))))

   PROGRAMMING STYLE
     Programs written in an imperative style will always out-perform programs
     written in a functional style because Munger is a naive interpreter.  A
     Scheme programmer might be tempted to write a factorial function in
     Munger like this:

     (defun fact (n)
        (labels ((f (lambda (n a)
                       (if (< n 2)
                          a
                          (f (- n 1) (* n a))))))
           (f n 1)))

     This function will work as expected in Munger, but there are some
     improvements we can make to it increase its efficiency.  First of all,
     the recursive invocation of "f" will not be recognized as a tail-call by
     the Munger interpreter, so we will use use the "tailcall" intrinsic to
     make this call.  Secondly, "tailcall" does not need to "see" a binding in
     order to make a recursive call.  It can restart the currently-running
     function internally.  This means we can use a "let" to make the binding
     to "f":

     (defun fact (n)
        (let ((f (lambda (n a)
                    (if (< n 2)
                       a
                       (tailcall 0 (- n 1) (* n a))))))
           (f n 1)))

     We can simplify this further.  We don't actually need to use "let" to
     create new local bindings, unless the interpreter is at toplevel, where
     no local lexical environment exists.  The "extend" intrinsic will extend
     the current local environment with a new binding more efficiently,
     because "let" is a macro internal to the interpreter, which must be
     expanded and re-evaluated, resulting in another function application.  If
     we wish to limit the extent of the bindings introduced by "extend" we can
     wrap expressions with the "dynamic_extent" intrinsic.  Replacing the
     "let" with "extend" gives us:

     (defun fact (n)
        (extend 'f
           (lambda (n a)
              (if (< n 2)
                 a
                 (tailcall 0 (- n 1) (* n a)))))
        (f n 1))

     We don't use it here, but the binding to "f" is actually visible inside
     the function body.  Although the function is closed over the environment
     before the environment is extended, the binding will nonetheless be visi-
     ble when the closure is applied, because closures do not simply close
     over visible bindings, but rather the environments which contain them.
     At the time the closure is applied, the environment will have been dynam-
     ically extended to make "f" visible.

     Using function calls to iterate will always result in slow programs in
     Munger.  The only reason we are introducing the helper function is to
     create a new binding to "a" to act as an accumulator, but we can use
     "extend" to do that directly, and replace the closure with a loop:

     (defun fact (n)
        (extend 'a 1)
        (while (> n 1)
           (setq a (* n a))
           (dec n))
        a)

     This function is very different than the factorial we started with and
     will run much more efficiently in the Munger interpreter.  But there is
     one last change we can make to further improve efficiency.  The most
     efficient way to iterate in Munger is to use the "iterate" intrinsic.  It
     can be used when the number of iterations can be calculated before enter-
     ing the body of the loop:

     (defun fact (n)
        (extend 'a 1)
        (iterate n (setq a (* a n)) (dec n))
        a)

     This is the fastest form of this function.

RETURN VALUES
     Munger returns 1 if the interpreter stopped due to an error, 0 otherwise.

AUTHORS
     James Bailie <jimmy@mammothcheese.ca>
     http://www.mammothcheese.ca

LANGUAGE REFERENCE
     Do not assume you know what an intrinsic does because it has a similar
     name to an intrinsic of another Lisp dialect, or you may have some nasty
     surprises working in Munger.

     The following functions are either built-in to the interpreter, or are
     library functions or macros defined in library.munger.  To find the entry
     for a particular item, search this document for the name of the item fol-
     lowed by a colon.

     List Operations:

     cons,          car,          cdr,           list,     length,
     caar,          cdar,         cadr,          cddr,     cdddr,
     cddddr,        caddr,        cadddr,        caddddr,  append,
     alist_lookup,  alist_remove, alist_replace, reverse,  sort,
     sortlist,      sortcar,      mapcar,        foreach,  remove,
     nthcdr,        nth,          member,        map

     Predicates and Conditionals:

     eq,        atomp,       if,        when,     unless,
     and,       or,          not,       nullp,    boundp,
     pairp,     equal        <,         <=,       >,
     >=,        stringp,     fixnump,   symbolp,  regexpp,
     tablep,    stackp,      intrinsicp,          closurep,
     macrop,    recordp,

     Assignment:

     set,       setq,        inc,       dec,     defun
     defmac

     Evaluation and Control Flow:

     progn,     throw,       while,     until,    do,
     catch,     continue,    main,      eval,     quote,
     load,      gensym,      version,   test,     let,
     letn,      labels,      cond,      apply,    exit,
     quit,      interact,    fatal,     nofatal,  extract,
     qquote     protect,     letf,      tailcall, prog1
     printer,   noprinter    die,       dynamic_let,
     extend,    gc,          for,       iterate   loop,
     dynamic_extent          gc_freq,   case,     eval_string
     blind_eval_string,      eval_buffer

     Fixnum Arithmetic:

     +,         -,           *,         /,        %,
     abs,       random,      negate,    unsigned

     Type Conversions:

     stringify, digitize,    intern,    char,     code,
     hex2dec,   dec2hex

     Buffer Operations:

     open,      close,       insert,    delete,    retrieve,
     lastline,  filter,      write,     read,      empty,
     slice,     find,        input,     output,    words,
     maxidx,    buffer,      buffers,   switch,    transfer,
     setmark,   getmark,     with_buffer,          filter_server
     remove_http_stuff

     Regular Expressions:

     regcomp,   match,       matches,   substitute, replace,

     String Operations:

     split,      join,        expand,    substring, concat
     chop,       chomp,       upcase,    downcase,  length,
     reverse,    strcmp,      split_rx,  tokenize,  rootname,
     suffix,     explode      base64_encode,        base64_decode
     form_encode form_decode

     Filesystem Operations:

     chdir,     libdir,      directory, unlink,    rmdir,
     pwd,       exists,      stat,      rename,    seek
     mkdir,     complete,    realpath,  access,    truncate,
     redirect,  resume,      chown,     chmod,     basename,
     readlock,  writelock,   unlock     dirname,   symlink

     Command-Line Arguments:

     current,   next,        prev,      rewind

     Line-Oriented I/O:

     print,                     println,               warn,
     with_input_file,           with_output_file,      with_output_file_appending,
     with_input_process,        with_output_process,   with_error_file,
     with_error_file_appending, with_temporary_output_file
     foreach_line,              foreach_line_callback, pipe
     newline,                   redirect,              resume,
     stderr2stdout,             getline,               rescan_path,
     stdout2stderr,             flush_stdout           getline_ub
     reset_history,             save_history,          load_history

     Network daemon-related:

     listen,      listen_unix, stop_listening,      accept,   daemonize,
     syslog,      getpeername, receive_descriptors, send_descriptors,
     busymap,     nobusymap,   busy,                notbusy,
     get_scgi_header           busyp,

     System Access:

     system,    getenv,      setenv,    block,     unblock,
     suspend,   lines,       cols,      date,      time,
     beep,      checkpass,   crypt,     setuid,    getuid,    setgid
     geteuid,   seteuid,     getgid,    hostname,  gecos,
     timediff,  timethen,    date2days, days2date, date2time,
     localtime, utctime,     week,      weekday,   month,     getpid,
     getppid,   setpgid,     getpgrp,   tcsetpgrp, tcgetpgrp
     kill,      killpg,      fork,      glob,      wait,
     zombies,   nozombies,   zombiesp,  exec,      shexec,
     forkpipe,  command_lookup,         unsetenv   getstring
     datethen,  chroot,      isatty,    sle

     Tables:

     table,     hash,        unhash,    lookup,    keys,
     values

     Stacks:

     stack,    push,         pop,       index,    store,
     used,     topidx,       assign,    flatten,  shift,
     clear,
     unshift

     Records:

     record,  getfield,     setfield,

     Communication with a child process:

     child_open,              child_write,          child_read,
     child_close,             child_running,        child_ready,
     child_wait,              child_eof

     SQLite Interface:

     sqlite_open,      sqlite_close,  sqlite_exec,  sqlite_prepare, sqlite_step,
     sqlite_finalize,  sqlite_reset,  sqlite_row,   sqlite_bind,    sqlp,
     sqlitep

     Character-Oriented I/O

     display,           clearscreen,    pause,        clearline,
     getchar,           goto,           scrolldn,     scrollup,       hide,
     show,              pushback,       insertln,     getchars
     fg_black,          fg_red,         fg_green,
     fg_yellow,         fg_blue,        fg_magenta,
     fg_cyan,           fg_white,       bg_black,
     bg_red,            bg_green,       bg_yellow,
     bg_blue,           bg_magenta,     bg_cyan,
     bg_white,          boldface,       normal,

     A description of each follows:

   cons: (cons expr1 expr2)
     Intrinsic "cons" adds an element to the beginning of a list.  Expr2 must
     evaluate to a list.

     > (cons 'a (b c)
     (a b c)

   car: (car expr1)
     Intrinsic "car" returns the first element of a list. An error is gener-
     ated if expr1 does not evaluate to a list.

     > (car '(a b c))
     a

   cdr: (cdr expr1)
     Intrinsic "cdr" returns the sublist of a list, beginning from the second
     element of the list. An error is generated if expr1 does not evaluate to
     a list.

     > (cdr '(a b c))
     (b c)

   boundp: (boundp expr1)
     The "boundp" intrinsic accepts one argument which must evaluate to a sym-
     bol.  The function returns 1 if the symbol is currently bound, 0 other-
     wise.

   caar, cadr, cdar, caddr, cadddr, caddddr, cddr, cdddr, cddddr: (form expr)
     These four library functions take the same argument as the car and cdr
     intrinsics and are built out of nested groupings of those intrinsics.

     > (caar '((a) b c)) ; is equivalent to: (car (car '((a) b c)))
     a

     > (cadr '(a b c)) ; is equivalent to: (car (cdr '(a b c)))
     b

     > (cdar '((a) b c)) ; is equivalent to: (cdr (car '((a) b c)))
     ()

     > (cddr '(a b c)) ; is equivalent to: (cdr (cdr '(a b c)))
     (c)

        etc.

   eq: (eq expr1 expr2)
     Intrinsic "eq" returns 1 if expr1 and expr2 evaluate to the same atom
     token, to atoms representing equivalent numbers, or to the exact same
     list, otherwise it returns 0.

     > (eq 'a 'a)
     1

     > (eq '(a b c) '(a b c))
     0

     > (set 'l '(a b c))
     (a b c)
     > (eq l l)
     1

     > (eq 0001 1)
     1

   equal: (equal expr1 expr2)
     Library function "equal" returns 1 in all the situations where "eq"
     returns 1, and additionally will return 1 if both of its arguments evalu-
     ate to lists having the same structure and content.  While "eq" will fail
     if its arguments evaluate to different lists with the same structure and
     content, equal will return 1 for these arguments..

     > (equal '(a b c) '(a b c))
     1

     > (set 'l '(a b c))
     (a b c)
     > (equal l l)
     1

     > (equal '(00 01 02) '(0 1 2))
     1

   atomp: (atomp expr)
     Intrinsic "atomp" returns 1 if its argument evaluates to an atom, and
     returns 0 otherwise.

     > (atomp 'a)
     1

     > (atomp '(a b c))
     0

   set: (set expr1 expr2)
     Intrinsic "set" accepts two arguments.  The result of evaluating the sec-
     ond argument is bound to the result of evaluating the first argument.
     The first argument must evaluate to a symbol.  If a local variable with
     the syntax of the symbol exists, its binding will be modified, otherwise
     "set" will create or modify a toplevel binding.  Locals can only be cre-
     ated by function application, or with the "extend" intrinsic.

     > (set 's '(a b c))
     (a b c)
     > s
     (a b c)

     > (set (car '(a b c)) ((lambda (x) (* x x)) 4))
     16
     > a
     16

   setq: (setq symbol expr)
     The "setq" intrinsic works similarly to the "set" intrinsic, except the
     first argument to the function is not evaluated and must be a symbol.

     (setq a b)

     is equivalent to:

     (set 'a b)

   eval_buffer: (eval_buffer)
     The "eval_buffer" intrinsic evaluates Munger lisp in the current buffer.
     The function accepts no arguments.  The buffer is evaluated in the cur-
     rent lexical context.  Recursive invocations of "eval_buffer" are not
     permitted, which is to say the code in the current buffer (or any other
     code it invokes) may not itself invoke "eval_buffer" while "eval_buffer"
     is running.  If the code in the current buffer messes with itself by
     altering the content of the current buffer, disaster may result; however,
     the code in the current buffer may open new buffers as it likes without
     fear.  The "eval_buffer" function will continue to parse the code in the
     buffer which was current when it was invoked.  The function returns the
     result of evaluating the last expression in the buffer upon success, or 0
     if a recursive invocation is attempted or if the current buffer is empty.
     Any errors encountered during evaluation of the code in the buffer will
     stop evaluation.

   eval_string: (eval_string expr)
   blind_eval_string: (blind_eval_string expr)
     Both the "eval_string" and "blind_eval_string" accept one argument which
     must evaluate to a string, and attempt to execute the string as lisp.
     Any error encountered will stop evaluation of the string, but the inter-
     preter will attempt to carry on interpreting the rest of your program.
     Your program may be in a "messed-up" state from the badly-behaved code
     parsed from the string, which may cause the interpreter to encounter
     another error which stops evaluation when it attempts to continue inter-
     preting your program.  Both functions return the result of evaluating the
     last successfully-evaluated expression parsed from the string.  If no
     expressions are successfully-evaluated, then the original string will be
     returned.

     The difference between the two functions is that with "eval_string" the
     code parsed from the string is evaluated in the current lexical context,
     while with "blind_eval_string" only the global environment is visible to
     the code in the string.  The current lexical environment is invisible to
     the string.

     Care must be taken when specifying recursive invocations of "eval_string"
     literally in program text.  Consider this example:

     (eval_string "(setq foobar (eval_string \"(join \\\":\\\" \\\"b\\\")\"))")

     The string-within-a-string, which is the argument to the recursive invo-
     cation, must have its delimiting quotes escaped with backslashes in order
     for them to be embedded in the toplevel string, and not end it.  Then the
     strings-within-a-string-within-a-string, which are the arguments to the
     recursive invocation's argument string's invocation of "join", must be
     double-escaped with three backslashes.  The backslashes closest to the
     quotes escape the quotes in the toplevel string, while the double back-
     slashes before the escaped quotes, embed backslashes into the toplevel
     string which will be interpreted as escaping the quotes during the recur-
     sive invocation of the lisp reader.

     Invoking "eval_string" is similar to invoking "load" except the code is
     extracted from a string instead of from a file.  If an expression is not
     complete within the string, it will be discarded.

   eval: (eval expr)
     Intrinsic "eval" returns the result of evaluating its lone argument
     twice, which is to say, the argument is evaluated as usual, and the
     result of this evaluation is evaluated again.  Note "eval" does not con-
     tain the lisp reader.  Calling "eval" with a string argument will only
     cause the original string to be returned, since strings are constants in
     Munger.

     > (set 'a (quote (set 'b 'booger)))
     (set (quote b) (quote (booger)))
     > b
     evaluate: b has no value.
     > (eval a)
     booger
     > b
     booger

   quote: (quote expr) or 'expr
     Intrinsic "quote" returns its argument unevaluated.  It is used so fre-
     quently it has an abbreviated form of a single apostrophe.

     > (quote (a b c))
     (a b c)
     > '(a b c)
     a

   protect: (protect expr expr ...)
     The "protect" intrinsic is analogous to unwind-protect in other lisp
     dialects.  The function accepts one or more arguments and evaluates them
     in sequence, but returns the value of evaluating the first argument.  The
     arguments subsequent to the first are evaluated EVEN IF THE EVALUATION OF
     THE FIRST IS INTERRUPTED by the interpreter encountering an error.

     > (catch
     >> (protect (throw 0)
     >>> (print 'booger)
     >>> (newline)))
     booger
     0
     >

   qquote: (qquote expr)
     The "qquote" (quasiquote) macro accepts a list and returns it unchanged
     except where sub-expressions have been "escaped" with comma characters.
     Those escaped sub-expressions are evaluated and the result of the evalua-
     tion inserted into the template expression.  "qquote" aids in the compo-
     sition of macros.

     Some lisps define a read macro "`" as a short form for "qquote", but
     Munger does not support this.  The commas escaping sub-expressions are
     separate tokens in Munger, unlike in other lisps.  For example ,token is
     actually parsed by Munger as two tokens, "," and "token".  This means
     ',token parses to "(quote ,) token" and not "(quote ,token)".

   if: (if expr1 expr2 [exp3...])
     Intrinsic "if" is a conditional.  It accepts two or three arguments, the
     first being the test condition.  The test condition is evaluated, and if
     the result is a true value (anything except 0 (fixnum), the empty string,
     or the empty list), the second argument is evaluated and the result of
     that evaluation is returned.  Otherwise, if the test condition evaluated
     to a false value, and further expressions are present after the second,
     those expressions are evaluated in order and the result of the last
     expression evaluated is returned.  If only two expressions are present in
     the original form, and the test condition evaluates to a false value, the
     result of evaluating the test expression is returned.

     > (if (> 3 4) 'yes 'no)
     no
     > (if (> 3 4) 'yes)
     0

   and: (and expr1 [expr2 ...])
     Intrinsic "and" accepts one or more  number of arguments, and evaluates
     them from left to right until an argument evaluates to a "false" value
     (0, the empty string, or the empty list), or the end of the arguments is
     reached. The value of the last evaluation is returned.

     > (and 1 'a 0)
     0
     > (and 1 'a "string")
     1

   or: (or expr1 [expr2 ...])
     Intrinsic "or" accepts one or more arguments, and evaluates them from
     left to right until an argument evaluates to a true value (anything other
     than 0, the empty string, or the empty list), or the end of the arguments
     is reached.  The value of the last evaluation is returned.

     > (or 1 0)
     1
     > (or 0 0)
     0

   list: (list expr1 [expr2 ...])
     Intrinsic "list" accepts one or more arguments, evaluates them in order,
     and returns a newly-constructed list containing of the result of each
     evaluation, also in order.

     > (list 'a 'b 'c) ; is equivalent to (cons 'a (cons 'b (cons 'c ())))
     (a b c)
     > (list '(a b c) 4 "hello")
     ((a b c) 4 "hello")

   progn: (progn expr...)
     Intrinsic "progn" accepts one or more arguments, and evaluates them in
     order, returning the result of evaluating the last argument.  If no argu-
     ments are passed to "progn" an error is generated which will stop evalua-
     tion.

     > (progn
     >> (set 'f (lambda (n) (+ n 1)))
     >> (set 'x 1)
     >> (f x))
     2

   prog1: (prog1 ...)
     Library macro "prog1" accepts zero or more arguments, and evaluates them
     in order, returning the result of evaluating the first argument.  If no
     arguments are passed to the macro, it returns the empty list.

     > (prog1
     >> (+ 2 2)
     >> (+ 3 3))
     4

   not: (not expr)
     Intrinsic "not" returns 1 if its argument is the empty list, the empty
     string, or zero, otherwise it returns 0.

     > (not 0)
     1
     > (not "hello")
     0

   nullp: (nullp expr)
     Library function "nullp" returns 1 if its argument is the empty list,
     otherwise it returns 0.

     > (nullp ())
     1
     > (nullp 'a)
     0

   pairp: (pairp expr)
     Library function "pairp" returns 1 if its argument is a non-empty list,
     otherwise it returns 0.

     > (pairp '(a b c))
     1
     (pairp ())
     0
     (pairp 'a)
     0

   warn: (warn expr [expr...])
     The "warn" intrinsic evaluates its arguments then writes the value of
     each evaluation, and one final newline character to the standard error
     stream.  The "warn" intrinsic always returns 1.

   setenv: (setenv expr1 expr2)
     The "setenv" intrinsic sets the value of a named environment variable.
     The function accepts two arguments, which must both evaluate to strings.
     The first argument is the environment variable to set, and the second is
     the new value to bind to the variable.  Any errors encountered will stop
     evaluation.  Upon success, "setenv" returns 1.

   unsetenv: (unsetenv expr)
     The "unsetenv" intrinsic accepts one argument which must evaluate to a
     string and removes any environment variable named by the string from the
     environment.  The function always returns 1.

   getenv: (getenv expr)
     The "getenv" intrinsic looks up the value of an environment variable.  It
     accepts one argument which must evaluate to a string.  If the environment
     variable specified exists, a string is returned representing the vari-
     able's value.  If the variable does not exist, 0 is returned.

     > (getenv "HOME")
     "/usr/home/jbailie"
     > (getenv "foobar")
     0

   directory: (directory expr)
     The "directory" intrinsic returns a list of strings representing the
     filenames of the entries in a specified directory, or a string represent-
     ing the error encountered by the opendir() system call.  The function
     does not return the ".." and "." directory entries, in its result set.
     "directory" accepts one argument, which must evaluate to a string, speci-
     fying the directory to list.

     > (directory "/usr/local")
     ("man" "bin" "share" "include" "lib" "etc" "info" "libexec" "sbin" "libdata")
     > (directory "/foobar")
     "No such file or directory"

   chomp: (chomp expr)
     The "chomp" intrinsic removes all contiguous terminating carriage return
     and newline characters from a string.  The function accepts one argument
     which must evaluate to a string, and ALWAYS returns a new string, regard-
     less of whether any terminators were removed from its argument or not.

     > (chomp (getline))
     hello[return]
     "hello"

     > (getline)
     hello[return]
     "hello
     "
     >

   chop: (chop expr)
     The "chop" intrinsic accepts one argument which must evaluate to a
     string, and returns a new string with the same characters as the original
     string but with the last character removed.  If the argument string is
     empty "chop" does nothing.

     > (chop "hello")
     "hell"
     > (chop "")
     ""

   beep: (beep)
     The "beep" intrinsic accepts no arguments and will cause the device con-
     nected to standard output to beep, if it is capable of doing so.  1 is
     returned on success.  Any error encountered stop evaluation.

   suspend: (suspend)
     The "suspend" intrinsic accepts no arguments and causes the interpreter
     to send a SIGSTOP to itself, suspending the interpreter process.  See
     your shell's documentation on how to resume stopped jobs.

   stderr2stdout: (stderr2stdout)
   stdout2stderr: (stdout2stderr)
     The "stderr2stdout" intrinsic connects the stderr stream to the stdout
     stream.  The "stdout2stderr" intrinsic connects the stdout stream to the
     stderr stream.  Both functions accept no arguments, and always return 1.
     The standard steam redirected may be reconnected to the stream it was
     previously connected to, with the "resume" intrinsic.

     After successful invocation, the stream whose name occurs first in the
     name of the intrinsic is connected to the same descriptor as the stream
     whose name occurs second in the name of the intrinsic.  So, if no previ-
     ous redirections have been made, invoking "stderr2stdout" will cause
     stderr and stdout to both write to descriptor 1, while invoking "std-
     out2stderr" will cause both stdout and stderr to write to descriptor 2.

   pipe: (pipe expr1 expr2)
     NOTE there are separate shortcut intrinsics to send or receive buffer
     lines, to or from, child processes, or filter them through child pro-
     cesses.  see the entries for the "input", "output", and "filter" intrin-
     sics for more details.

     the "pipe" intrinsic forks a specified process, piping one of the inter-
     preter's standard descriptors to the standard input or standard output of
     the new process.  The function accepts two arguments, the first of which
     must evaluate to 0, 1, or 2, and specifies the interpreter descriptor to
     be redirected.  0 is the interpreter's standard input, 1 is the inter-
     preter's standard output, while 2 is the interpreter's standard error. if
     the user wishes to read from the new process, 0 should be passed as the
     first argument, but if the user wishes to write to the new process then 1
     or 2 should be passed as the first argument.  The second argument must
     evaluate to a string specifying a command line to run.  The command is
     passed to the shell (/bin/sh) for execution, and may contain any expres-
     sion that program understands.  All errors will stop evaluation.  Upon
     success "pipe" returns 1.

     Note that if the specified command cannot be found, or there is some
     other error in the command line, the call to "pipe" will succeed, but the
     new shell process will immediately exit.  If interpreter descriptor 0
     were redirected, then the next call to "getline" will return 0, indicat-
     ing EOF, but if descriptors 1 or 2 were redirected, the next "print" to
     the pipe will silently fail.

     Redirection is undone by the "resume" intrinsic.  It is not necessary to
     undo a redirection, to perform another redirection.  Successive invoca-
     tions of "pipe" on the same descriptor may be made to create a pipeline.
     If interpretation returns to the toplevel, all redirections are undone
     automatically.  See the entries for the "with_input_process" and
     "with_output_process" macros, for a simple means of performing temporary
     redirections.

     The following example is equivalent to entering:
     "jot 100 1 | sort -n | fmt"
     at the shell:

     >(progn
     >> (pipe 1 "fmt")
     >> (pipe 1 "sort -n")
     >> (for (a 100 1)
     >>>   (print a)
     >>>>  (newline)))
     1
     > 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
     26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
     48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
     70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91
     92 93 94 95 96 97 98 99 100

     Note the last line of output from the pipeline is a short line.  This
     means that after all the data was written to the pipeline, the "fmt"
     utility blocked, reading on its stdin, waiting for enough subsequent data
     to fill another entire line.  It is only when the "progn" returned to
     toplevel and the interpreter did an implicit "resume" on descriptor 1,
     that the pipeline processes read EOF on the pipe, and "fmt" in turn, spit
     out the last line.  The output of the pipeline and the interpreter
     process are mixed up because they both have their standard outputs con-
     nected to the terminal.  The 1 after the lisp, is the return value of the
     lisp expression.  This is followed by a the lisp prompt >, which is then
     followed by the output from the pipeline.  It is necessary to wrap the
     whole example in a "progn" to prevent the interpreter from returning to
     toplevel in-between subexpressions, and undoing the redirections.  The
     child process spawned by the second invocation of "pipe" inherited the
     redirection of stdout by the first invocation of "pipe" which results in
     the creation of the pipeline.  Since the command argument to "pipe" is
     passed to the shell, we could have used (pipe 1 "sort -n | fmt") instead
     and let the shell create the pipeline for us.  Note that we must create
     the subprocesses of the pipeline in reverse order if we are going to
     write to the pipeline, but in order if we are going to read from the
     pipeline.

     >(progn
     >> (pipe 0 "jot 1 100")
     >> (pipe 0 "fmt")
     >> (while (set 'l (getline))
     >>>   (print l)))
     1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
     26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
     48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
     70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91
     92 93 94 95 96 97 98 99 100
     0
     >

   redirect: (redirect expr1 expr2 [expr3 [expr 4]])
     The "redirect" intrinsic redirects one of the three standard file
     descriptors to a file.  The function accepts two, three or four argu-
     ments, the first of which must evaluate to one of 0, 1, or 2, and speci-
     fies the descriptor to be redirected.  The three possible values corre-
     spond to standard input, standard output, and standard error, respec-
     tively.  The second argument must evaluate to a string specifying the
     filename to be opened.  The third and fourth arguments are boolean flags
     which indicate whether the file specified by the second argument should
     be opened in append mode, and whether an attempt should be made to obtain
     a lock on the file, respectively.  The third optional argument is ignored
     unless argument 1 evaluates to 1 or 2, and itself must evaluate to a
     fixnum.  The fourth optional argument must also evaluate to a fixnum.

     If argument 3 evaluates to a non-zero value, it indicates the contents of
     the file should be appended to.  If the third argument is not present or
     evaluates to 0, and the first argument evaluates to 1 or 2, then the file
     will be created if it does not exist, or overwritten if it does.  If the
     third argument is present and evaluates to a non-zero fixnum, and the
     first argument evaluates to 1 or 2, the file will be created if it does
     not exist, or it will be appended to, if it already exists.  The third
     argument is ignored if the first argument evaluates to 0.

     If the fourth argument evaluates to non-zero value, and the first argu-
     ment evaluates to 0, an attempt will be made to acquire a shared lock on
     the file.  If the fourth argument evaluates to a non-zero value, and the
     first argument evaluates to 1 or 2, then an attempt will be made to
     acquire an exclusive lock on the file.

     If the function is successful, the specified file descriptor will be
     redirected onto the specified file, and 1 will be returned.  If an
     attempt is made to redirect descriptor 0 to a non-existent file, -1 is
     returned.  If an attempt is made to redirect any descriptor to a file to
     which the user lacks the necessary permissions, -2 is returned.  If a
     lock cannot be acquired, -3 is returned. If the function encounters any
     other error from the open() system call, it will return a string describ-
     ing the error.  Errors from other sources will stop the interpreter.

     Redirection is undone by the "resume" intrinsic.  It is not necessary to
     undo a redirection, to perform another redirection.  Successive invoca-
     tions of "redirect" may be made, and each redirection may be undone by
     calling "resume" to reconnect the specified descriptor to the stream it
     was connected to previously.  In other words, to undo all redirections,
     it is necessary to call "resume" on a descriptor the same number of times
     one has called "redirect" on the same descriptor.

     If the thread of execution returns to the toplevel read-eval-print loop
     while one or more streams are redirected, all redirections will be undone
     by the interpreter, with all three standard streams being reconnected to
     the descriptors to which they were reconnected when the interpreted was
     started.

   temporary: (temporary)
     The "temporary" intrinsic creates a temporary file in /tmp opened for
     writing, and redirects stdout onto it.  The function accepts no arguments
     and returns the filename of the temporary file.  The programmer should
     invoke (resume 1) when finished writing to the file, to reconnect stdout
     the stream it was previously connected to, and "unlink" the file when
     completely finished with it.

   with_temporary_output_file: (with_temporary_output_file expr...)
     The "with_temporary_output_file" invokes "temporary" to redirect stdout
     onto a temporary file, evaluates a sequence of expressions, then invokes
     "resume" to undo the redirection to the temporary file.  The macro
     accepts one or more arguments to be evaluated when the redirection is in
     place, and returns the name of the temporary file, so that further code
     in your program may access the temporary file.  One should "unlink" the
     filename when one is completely finished with the file.

   resume: (resume expr)
     The "resume" intrinsic causes a redirected descriptor to be reconnected
     to the device it was connected to before the last call to "redirect" or
     "pipe".  The function accepts one argument which must evaluate to one of
     0, 1, or 2, corresponding to the descriptor to be affected.  If the spec-
     ified descriptor were not redirected, "resume" returns 0, otherwise it
     returns 1.

   with_input_file: (with_input_file expr1 expr2 ...)
     The "with_input_file" macro temporarily redirects standard input onto a
     file.  The macro accepts two or more arguments, the first of which must
     evaluate to a string specifying the file to read from, while the rest are
     expressions to be evaluated while standard input is redirected.  The re-
     direction is undone after all the arguments have been evaluated.  No
     arguments are evaluated until after the macro expands, in the calling
     scope.  The arguments following the first argument will not be evaluated
     unless redirection has been successful.  The macro returns the value of
     evaluating the last argument upon success, otherwise it returns return
     value of the failed invocation of the "redirect" intrinsic.

     The "resume" intrinsic is called by the macro to reconnect standard input
     to the device it was connected to before the macro was invoked, after all
     the body expressions have been evaluated.

     > (with_input_file "library.munger"
     >> (print (getline)))
     ; This file contains the lisp library code for the Munger interpreter.
     1

     Note that calls to "with_input_file" may be nested.

     > (with_input_file "library.munger"
     >> (print (getline))
     >> (with_input_file "INSTALL"
     >>> (print (getline)))
     >> (print (getline)))
     ; This file contains the lisp library code for the Munger interpreter.
     Munger Installation
     ; Copyright (c) 2001, 2002, 2003, James Bailie <jimmy@mammothcheese.ca>.
     1
     >

   with_output_file: (with_output_file expr1 expr2 ...)
     The "with_output_file" macro behaves similarly to the "with_input_file"
     macro except that "with_output_file" redirects standard output instead of
     standard input.  The specified file will be overwritten, if it already
     exists.

     > (with_output_file "tmp" (print "hello") (newline))
     1
     > (with_input_file "tmp" (print (getline)))
     hello
     1

   with_output_file_appending: (with_output_file_appending expr1 expr2 ...)
     The "with_output_file_appending" macro behaves similarly to the
     "with_output_file" macro, except that the specified file will be opened
     for appending.

   with_error_file: (with_error_file expr1 expr2 ...)
     The "with_error_file" macro behaves similarly to the "with_output_file"
     macro except that "with_error_file" redirects standard error instead of
     standard output.  The specified file will be overwritten, if it already
     exists.

   with_error_file_appending: (with_error_file_appending expr1 expr2 ...)
     The "with_error_file_appending" macro behaves similarly to the
     "with_error_file" macro, except that the specified file will be opened
     for appending.

   with_input_process:
   with_output_process:
     These two macros behave similarly to the "with_input_file" and "with_out-
     put_file" macros, the only difference being the first argument specifies
     a program for the appropriate descriptor to be piped to or from, instead
     of a file.  The first argument is passed to /bin/sh for processing and
     may therefore contain any commands that program understands.  Read the
     entries for with_input_file and with_output_file for more information.

     > (with_input_process "ls"
        (while (set 'l (getline))
           (print l)))
     INSTALL
     LICENSE
     Makefile
     README
     cat.munger
     cgi.munger
     cgi.munger
     echo.cgi
     err.munger
     grep.munger
     intrinsics.c
     library.munger
     lisp.c
     lisp.h
     munger.man
     transform.munger

   foreach_line: (foreach_line expr)
     The "foreach_line" library macro is used to create filter-like programs.
     The function accepts one argument, which must evaluate to a monadic func-
     tion.  The monadic function is called repeatedly with each line of input.
     The input lines are taken from the files specified on the command line,
     or if no files are specified, from the standard input.  Note the function
     passed to the macro can be an intrinsic which accepts variable length
     argument lists, but is happy with just one argument, such as the "print"
     intrinsic.

     The argument pointer must be positioned so that the next call to (next)
     will return the first of the command line arguments the user wishes pro-
     cessed, if any.  A script would normally process any option arguments,
     advancing the argument pointer as it did so, and then call foreach_line.
     The invocation of foreach_line returns when it has processed all the
     specified files, or when it encounters EOF on standard input.

     ; Skip over the interpreter name, so that the argument pointer is now
     ; pointing to the script name.  The next invocation of (next) will
     ; either return the next argument, or 0.

     (next)
     (foreach_line (lambda (line) [do something with line] ))
     (exit 0)

   foreach_line_callback: (foreach_line_callback expr1 expr2 (expr3))
     The "foreach_line_callback" macro functions similarly to the "fore-
     ach_line" macro, but is intended for use by filters which need to reset
     state variables when the input source changes, and/or which wish to out-
     put the results of processing the just-completed input source.  The macro
     accepts one or two more arguments than "foreach_line".  The second argu-
     ment must evaluate to a function, which itself accepts no arguments,
     which will be called at the end of processing each input source.  The
     third argument is optional, and if present, is treated as a logical flag
     which specifies whether the callback should be invoked before or after
     the argument pointer is advanced.  In Munger, zero (fixnum), the empty
     list, and the empty string are all logical "false" values; all other
     objects are considered "true".  A "true" third argument causes the call-
     back to be invoked after the argument pointer has been advanced.  Omit-
     ting the third argument, or setting it to one of the three "false" val-
     ues, causes the callback to be invoked before the argument pointer is
     advanced.  Within the callback function, invoking (current) will return
     the command-line argument the argument pointer is currently pointing at.

     This means if you wish to access the name of the file which has just been
     processed in the callback, no third argument, or a "false" third argument
     should be passed to the macro, but if you wish to access the name of the
     new input source about to be processed, a "true" third value should be
     passed as the third argument.  If the currently-running script has not
     been presented with any command-line arguments, then "foreach_line_call-
     back" will read data from the standard input, and then invoke the call-
     back function once after all data has been processed.  The callback func-
     tion should be crafted with this possibility in mind.

     The "grep.munger" example program in (libdir) demonstrates using the
     third argument.  The following script does not supply a third argument,
     and simulates wc -l:

     (next)
     (set 'script (current))
     (set 'count 0)
     (set 'total 0)

     (set 'callback
        (lambda ()

           (let ((name (if (eq script (current)) "stdin" (current))))

              (print count " " name)
              (newline)
              (set 'total (+ total count))
              (set 'count 0))))

     (foreach_line_callback (lambda (x) (inc count)) callback)
     (print total  " total")
     (newline)
     (exit 0)

   unlink: (unlink expr)
     The "unlink" intrinsic removes a file from a directory.  It accepts one
     argument which must evaluate to a string specifying the filename to
     remove.  The function returns 1 upon success, or a string specifying the
     error encountered upon failure.

   realpath: (realpath expr)
     The "realpath" intrinsic resolves all symbolic links, extra / characters,
     and references to . and .. in a specified pathname.  If the filename
     begins with a tilde (~), the function will attempt to expand the tilde as
     csh or bash does to reference a home directory.  The Function accepts one
     argument, which must evaluate to a string, and returns a string.  If a
     directory component of the specified path does not exist, the empty
     string is returned.

     > (realpath ".")
     "/usr/home/jbailie/src/munger-4.81"

     > (realpath "~/foobar")
     "/usr/home/jbailie/foobar"

     > (realpath "/foobar/foobar")
     ""

     ; Tilde-expansion does not occur if the tilde-expression does not reference
     ; a valid, readable, home directory.  Here the tilde is considered to be
     ; the first character of a relative filename, because there is no
     ; ~nobody home directory on my system.

     > (realpath "~nobody/foobar")
     "/usr/home/jbailie/src/munger-4.81/~nobody/foobar"

   access: (access expr1 expr2)
     The "access" intrinsic determines whether or not the real user id the
     interpreter is running as, has access to a specified file.  The function
     accepts two arguments, the first of which must evaluate to a string and
     specifies the filename to check access to, while the second argument must
     evaluate to a number and be one of 0, 1, or 2.  A second argument of 0
     instructs the function to check for read access to the specified file.  A
     second argument of 1 instructs the function to check for write access to
     the file, and a second argument of 2 instructs the function to check for
     executable access to the file.  The function will return 1 to indicate
     access is allowed, or 0 otherwise.

   mkdir: (mkdir expr)
     The "mkdir" intrinsic accepts one argument, which must evaluate to a
     string, and attempts to create a directory with the same name as the
     string.  Upon success, "mkdir" returns 1; otherwise it returns a string
     describing the error encountered.  If successful, the newly-created
     directory will have permissions 755 (possibly modified by the current
     umask).

   rmdir: (unlink expr)
     The "rmdir" intrinsic removes a directory from the filesystem.  It
     accepts one argument which must evaluate to a string specifying the
     directory name, and returns 1 upon success, or a string specifying the
     error encountered upon failure.

   words: (words)
     The "words" intrinsic accepts no arguments and returns the number of
     words in the buffer.

   time: (time)
     The "time" intrinsic accepts no arguments and returns a string represent-
     ing an integer representing the number of seconds since 00:00 Jan 1, 1970
     (the UNIX epoch).  It was not possible to return the integer value
     directly when Munger's fixnums were 1 bit less in size than the word-size
     the interpreter was running on, as time values would overflow the 31 bits
     of a fixnum on 32-bit machines.  This limitation has been lifted and
     fixnums are now the full 32 bits on a 32 bit machine, but the time
     intrinsic remains unchanged for backward compatibility.  Note that one
     may use the "digitize" intrinsic to convert the time value to a fixnum.

   timediff: (timediff expr1 expr2)
     The "timediff" intrinsic accepts two arguments which both must evaluate
     to strings specifying a time value expressed in seconds from the UNIX
     epoch (00:00 Jan 1, 1970), such as returned by the "time" intrinsic, and
     returns the difference in seconds between the two times, as a number.  If
     the time difference cannot be expressed within the word-size of the
     machine, minus 1-bit, then fixnum wrap-around will occur and the returned
     value will not be accurate.  The "unsigned" intrinsic will return a
     string representing the correct time value.

   timethen: (timethen expr)
     The "timethen" intrinsic accepts one argument which must evaluate to a
     fixnum and returns a string representing the current time in seconds from
     the UNIX epoch (00:00 Jan 1, 1970), offset by that many seconds.  This
     function can be used to determine the UNIX time value for a time in the
     future or the past.  For example, the following code returns the UNIX
     time value for a time 1 hour in the past:

     > (timethen -3600)
     "1124553616"

   date2days: (date2days expr1 expr2 expr3)
     The "date2days" intrinsic accepts three arguments, each of which must
     evaluate to a fixnum, specifying a year, month, and a day of the month,
     and returns a fixnum representing the number of days this date is removed
     from March 1st, 1 BCE.  This value can be useful in performing calendar
     arithmetic.  The first number indicates the year and must be greater than
     or equal to 0, (1 BCE).  The second number indicates the month and must
     be in the range 1-12.  The third number indicates the day of the month
     and must be in the range 1-31, or 1-30, depending on the month specified.

   days2date: (days2date expr)
     The "days2date" intrinsic accepts a day number fixnum returned by
     "date2days" and converts it into a list of three fixnums representing
     that date.  The first number indicates the year and will be greater than
     or equal to 0, (1 BCE).  The second number indicates the month and will
     be in the range 1-12.  The third number indicates the day of the month
     and will be in the range 1-31.

   week: (week expr)
     The "week" intrinsic accepts one argument which must evaluate to a
     fixnum, representing a day number as returned by "date2days", and returns
     a two-element list of fixnums representing the year and the week number
     in that year, respectively, in which the specified day occurs.

   weekday: (weekday expr)
     The "weekday" accepts one argument which must evaluate to a day number,
     such as returned by "date2days", and returns a two-element list describ-
     ing the day of the week of the specified day.  The first returned element
     is a fixnum in the range 0-6, each value of which corresponds to a week-
     day in the range Sunday-Saturday, respectively.  The second element is a
     string representing the name of the weekday, in English.

   month: (month expr)
     The "month" intrinsic accepts a fixnum argument specifying the numerical
     value of a month (1-12), as used by the "date2days", "days2date", and
     "localtime" intrinsics, and returns a string representing the name of the
     month in English.

   localtime: (localtime expr)
     The "localtime" intrinsic accepts a string representing a UNIX time
     value, such as returned by the "time" intrinsic, and returns a six-ele-
     ment list of fixnums representing the date of the specified time in the
     local timezone.  The first returned element is the year.  The second is
     the month.  The third is the day of the month.  The fourth is the hour.
     The fifth is the minutes.  The sixth is the seconds.

   utctime: (utctime expr)
     The "utctime" intrinsic accepts a string representing a UNIX time value,
     such as returned by the "time" intrinsic, and returns a six-element list
     of fixnums representing the date of the specified time in terms of coor-
     dinated universal time.  The first returned element is the year.  The
     second is the month.  The third is the day of the month.  The fourth is
     the hour.  The fifth is the minutes.  The sixth is the seconds.

   date2time: (date2time expr1 expr2 expr3...)
     The "date2time" intrinsic converts a list of fixnums representing a date
     on or after midnight January 1st, 1970, and returns a fixnum representing
     the number of seconds from the UNIX epoch (midnight, January 1st, 1970).
     See the entry for the "time" intrinsic for more information on UNIX time
     values.  The function accepts three, four, five, or six arguments.  The
     first three arguments must be present, and represent the year (1970-),
     the month (1-12), and the day of the month (1-31), respectively.  The
     fourth, fifth, and sixth optional arguments represent the hour, minute,
     and seconds values of the date, respectively.  Omitted optional arguments
     default to 0.  The presence of an optional argument implies the presence
     of all preceding optional arguments.  This means if you include a value
     for minutes, you must include a value for hours as well, and if you
     include a value for seconds, you must include values for hours and min-
     utes as well.

   random: (random expr)
     The "random" intrinsic accepts one argument which must evaluate to a pos-
     itive number, and returns a random integer where 0 < returned-value <
     evaluated-argument.  The interpreter calls srandomdev() at startup to
     initialize the random number generator, and random() to generate random
     numbers.  Random numbers are then scaled to be within the requested range
     by computing:  evaluated-argument * random-number / RAND_MAX.

   date: (date [expr [expr ]])
     The "date" intrinsic accepts two optional arguments and returns a string
     representing the current date and time.  The two optional arguments, if
     present, must evaluate to fixnums.  Invoking "date" with no arguments is
     the same as invoking it with an first argument of 0.  The second argument
     is only significant when the first argument is non-zero.  When invoked
     with no arguments, or one argument of 0, the function returns a represen-
     tation of the time and date expressed in terms of the local timezone.
     When invoked with a non-zero first argument, the function returns a rep-
     resentation of the time and date expressed as universal coordinated time.

     If you are running FreeBSD 4.x, then the timezone in this case will be
     represented by the three-letter abbreviation GMT (Greenwich Mean Time),
     but on FreeBSD 5.x and later versions the timezone will be represented by
     the three-letter abbreviation UTC (Universal Coordinated Time, in
     French).  The "date" intrinsic was designed to return a properly format-
     ted date string per HTTP/1.1 if invoked with a non-zero first argument,
     but this standard specifies GMT must be used for the timezone indicator
     and not UTC, therefore the second optional argument may be present, and
     if non-zero changes the UTC abbreviation to GMT.

     > (date)
     "Fri, 04 Oct 2002 12:06:11 EDT"
     > (date 1)
     "Fri, 04 Oct 2002 16:06:13 UTC"
     > (date 1 1)
     "Fri, 04 Oct 2002 16:06:16 GMT"

   datethen: (datethen expr1 [expr2 [expr3 ]])
     The "datethen" intrinsic may be used to produce human-readable date
     strings from UNIX time values.  The function accepts one to three argu-
     ments.  The first must evaluate to a string specifying a UNIX time value,
     such as those generated by the the "time" and "timethen" intrinsics.  The
     optional second and third arguments must be one of either fixnum 0 or
     fixnum 1.  The function returns a string describing the time argument in
     human readable form, formatted identically to the strings produced by the
     "date" intrinsic.  If the second argument is present and is 1, the
     returned time string will be expressed in UTC, otherwise the time string
     will be expressed relative to the local time zone.  If the third argument
     is present and evaluates to 1, then the timzone abbreviation will be GMT
     instead of UTC.

     Invoking (datethen (time)) is equivalent to invoking (date), while invok-
     ing (datethen (time) 1) is equivalent to invoking (date 1).

   print: (print expr...)
   println: (println expr...)
     Intrinsic "print" accepts one or more arguments, evaluates them, and
     prints the each evaluated argument, in order,  to the standard output
     stream.  If any of the arguments evaluate to strings, the contents of the
     strings are printed without the surrounding quotes.  If any of the argu-
     ments evaluate to lists, then any strings in those lists will be printed
     with their surrounding quotes.  The "print" intrinsic always returns 1.

     Intrinsic "println" functions similarly to "print" but it outputs a sin-
     gle newline character after printing its arguments.

     > (print "hello there")
     hello there
     1

     > (set 'f '(a b c))
     (a b c)
     1
     > (print f)
     (a b c)

     > (print 'hello)
     hello1

     > (progn
     >> (print 'hello)
     >> (newline))
     hello
     1

     The "newline" intrinsic outputs a newline character (ASCII 10) to the
     standard output.

   load: (load expr)
     Intrinsic "load" reads lisp from the file specified by its lone argument,
     which must evaluate to a string.  The function returns the value result-
     ing from evaluating the last expression in the file.  Any errors encoun-
     tered opening the file, or evaluating its content will stop evaluation.

   getline_ub: (getline_ub [expr])
     The "getline_ub" (getline unbuffered) is intended for use when the user
     wants to read lines of text from stdin, but subsequently "fork" or
     "forkpipe" the interpreter and "exec" or "shexec" a new program to con-
     tinue reading lines from stdin.  The "getline" intrinsic does its own
     input buffering, and if used in such a situation, would result in
     buffered data in the parent being lost to the child.  Note that if the
     child does not call "exec" or "shexec" this is not true, as the child
     will have its own copy of the buffered data.

     The "getline_ub" intrinsic reads a line from standard input and returns
     it as a string, including the terminating newline.  If it does not
     encounter a newline after having read 2048 characters, the 2048 charac-
     ters will be returned without a terminating newline.  If EOF is encoun-
     tered before a newline is read, the returned string will contain all the
     remaining data in the input stream without a terminating newline.  If no
     characters remain in the input stream the function returns 0.  If the
     read() system call fails the function also returns 0.  The function
     accepts two optional arguments, which if present, must both evaluate to
     fixnums.

     The lone optional argument is a timeout value, useful when stdin is con-
     nected to a socket.  "getline_ub" reads data a character at a time from
     stdin until it reads a newline.  If any invocation of the read() system
     call blocks for a longer number of seconds than that specified by the
     timeout value, it will be interrupted and "getline_ub" will return any
     characters successfully read before the timeout, not terminated by a new-
     line character.  If no characters were read before the timeout, then the
     empty string will be returned.  This is the only circumstance in which
     the empty string will be returned.  If invoked without a timeout value,
     "getline_ub" will block until at least one character can be read from
     stdin or EOF is encountered, and return either a non-empty string, or 0
     on EOF.  Therefore, if stdin has been connected to a socket via "accept",
     a return value of "" from (getline_ub 5) indicates a timeout, while a
     return value of 0 indicates EOF.  The timeout argument may be omitted or
     it may be set to 0, to allow read() to block indefinitely.

     When reading from a terminal device in canonical mode, carriage returns
     will be converted into newlines by the terminal driver, and be returned
     as newlines to "getline_ub".  When reading from other sources, or from a
     terminal in non-canonical mode, the carriage returns will be passed
     through untranslated.  Note that if reading from a terminal device in
     canonical mode with a timeout, the empty string will always be returned
     when a timeout occurs, as the terminal driver will not return any charac-
     ters to the interpreter until a carriage return or newline is input.

   getline: (getline [expr1 [expr2]])
     Intrinsic "getline" reads a line from standard input and returns it as a
     string, including the terminating newline.  If it does not encounter a
     newline before reading 2048 characters, it will return the 2048 charac-
     ters without a terminating newline.  If the end of stdin is reached while
     searching for the next newline, all the remaining characters in the
     stream, if any, will be returned as a string without a terminating new-
     line.  If no characters remain in the stream, "getline" returns fixnum 0.
     Any subsequent invocations of "getline" on the same input source will
     continue to return fixnum 0.  The function also returns 0 when it encoun-
     ters any error condition.

     "getline" does its own input buffering to make line-by-line reading of
     data more efficient, using  a 100K buffer.  The function should not be
     used when the user wishes to read some lines, then fork and exec another
     program to continue reading from the inherited stdin, as the data already
     read into the parent's buffer will not be available to the child process
     after an "exec", so data will be lost.  In this situation, the unbuffered
     version, "getline_ub" must be used instead, or the unbuffered "getchars"
     intrinsic.

     IF THE STANDARD INPUT IS NOT A TERMINAL DEVICE, BOTH ARGUMENTS ARE
     IGNORED AND THE BEHAVIOR IN THE REST OF THIS DESCRIPTION DOES NOT OCCUR.

     If standard input is a terminal device, then the terminal is put into
     "raw" mode, with the interpreter simulating the standard UNIX terminal
     line discipline (ctrl-h => backspace; ctrl-w => werase; ctrl-u => kill).
     If ctrl-d (EOF) is encountered as the first character of input, "getline"
     returns the fixnum zero, otherwise EOF is ignored, and getline continues
     to accumulate characters until either a carriage-return or a newline is
     input.  Carriage returns are converted into newlines, so the strings
     returned by "getline" when reading from a terminal device are always new-
     line-terminated.  The function drops the cursor to the last line of the
     terminal device and echoes input there.  The function will also automati-
     cally perform horizontal scrolling if the input line grows to the width
     of the terminal device, scrolling in increments of the terminal width - 1
     character.  The last column of the last line of the screen is not used
     because some terminals will automatically scroll up a line if a character
     is printed there.

     The function accepts two optional arguments, the first of which, if
     present, must evaluate to a string, and is printed as a prompt to the
     user.  If the second optional argument is also present, it must evaluate
     to a fixnum and specifies the location of tabstops in the onscreen echoed
     string.  For example a value of 4, will cause tabstops to appear to the
     user to be set every four characters.  If the second argument is not
     present, tabstops default to every 8 characters.  Pass the empty string
     as the first argument if you wish to submit a second argument to the
     function, but do not wish it to print a prompt.

     If the second argument is 0, then the input of a tab character will trig-
     ger filename completion.  if the second argument is -1, then tab will
     trigger command and/or filename completion, depending upon the state of
     the input line when the tab is received.  If the second argument is -2,
     then tab will trigger filename completion, but the filename completion
     mechanism will not work recursively.  If the second argument is -3, then
     tab will trigger command and/or filename completion, but the filename
     completion mechanism will not work recursively.  Note that in these
     cases, tabs cannot be entered by the user.  For the cases where the file-
     name completion mechanism does not work recursively (second argument of
     -2 -3), it will attempt to complete one level of the path provided to it.
     If completion is invoked again at this point, it will complete another
     level, and so on.  For the cases where the filename completion works
     recursively, it will complete as much of the path given to it, as is pos-
     sible.

     When command and filename completion have been requested, and the text
     entered so far consists of only non-whitespace characters, then command
     completion will be attempted, otherwise filename completion will be
     attempted upon the last contiguous segment of non-whitespace characters.
     There are two exceptions to this rule.  If the first character input is
     either '/' or '.' then filename completion will be attempted in the ini-
     tial position instead of command completion.

     Completion will work with commands or filenames which contain whitespace
     only if the portion before the cursor does not contain whitespace.  Quot-
     ing mechanisms, such as those provided by shell programs, are not avail-
     able.  The "getline" function will append a single space character to the
     input string after a completion has been successfully completed and the
     completion was unambiguous.

     When completions are requested, each string created with "getline" is
     placed onto a 500-line history list and may be recalled, edited and re-
     entered.  Pressing Contol-P or Control-N, while inputting text via "get-
     line" will cause the current text to be replaced with the previous or the
     next item on the history list, respectively.  While in the history list
     one may quickly move back to the input line by invoking Control-X.  The
     history list may be read from or written to a file with the "load_his-
     tory" and "save_history" intrinsics.

     When completions are requested, pressing Control-R or Control-S causes
     the interpreter to enter history search mode.  Square brackets appear
     above the input line.  Text typed by the user appears inside the brackets
     and causes the interpreter to search forward (C-s) or backward (C-r) in
     the history list for a line containing the bracketed text.  Pressing C-s
     or C-r again causes the interpreter to search forward or backward for
     another matching line.  Both Control-R and Control-S wraparound the ends
     of the history list.  Control-H and Backspace erase the last type charac-
     ter inside the brackets.

     The history can be cleared with the "reset_history" intrinsic.

     When completions are requested, these command-line editing commands are
     recognized by getline, in addition to C-h, C-w, and C-u:

     M-f - Moves the cursor to the beginning of the next word in the line.
     M-b - Moves the cursor to the beginning of the previous word in the line.
     C-k - Deletes the text from the cursor location to the end of the line.
     C-d - Deletes the character the cursor is on.
     M-d - Deletes the word or word-portion the cursor is before.
     C-a - Moves the cursor to the beginning of the line.
     C-e - Moves the cursor to the end of the line.
     C-y - pastes the last deletion into the line before the cursor.


     Additionally, will C-u not delete the entire line, when completions are
     requested, but only the portion before the cursor.

   reset_history (reset_history)
     The "reset_history" intrinsic clears the items on the history list the
     interpreter maintains for the "getline" intrinsic.  The function accepts
     no arguments and always returns 1.

   load_history (load_history expr)
   save_history (save_history expr)
     The "load_history" and "save_history" intrinsics read and write the his-
     tory list maintained by the "getline" intrinsic to and from files.  Both
     functions accept a single argument that must evaluate to a string speci-
     fying the filename.  In both functions, if the open() system call encoun-
     ters an error, a string will be returned.  In the "save_history" intrin-
     sic, if the read() system call encounters an error a string will be
     returned.  Otherwise, both functions return the number of lines read or
     written.

   rescan_path: (rescan_path)
     The "rescan_path" intrinsic causes the interpreter to re-build its inter-
     nal list of executable files from the directories defined by the PATH
     environment variable.  This list is used by "getline" and by "com-
     mand_lookup".  If the programmer wishes those two intrinsics to continue
     to find all executables, it is necessary to invoke "rescan_path" if the
     PATH environment variable has changed, or if new executables have been
     added to the directories specified by that environment variable, since
     the last invocation of either "getline" or "command_lookup".  The func-
     tion always returns 1.

   stringp: (stringp expr)
     Intrinsic "stringp" returns 1 if its lone argument evaluates to a string,
     otherwise it returns 0.

     > (stringp "0")
     1
     > (stringp 0)
     0

   fixnump: (fixnump expr)
     Intrinsic "fixnump" returns 1 if its lone argument evaluates to a number,
     otherwise, it returns 0.

     > (fixnump 0)
     1
     > (fixnump "0")
     0

   symbolp: (symbolp expr)
     Intrinsic "symbolp" returns 1 if its lone argument evaluates to a symbol,
     otherwise, it returns 0.

   regexpp: (regexpp expr)
     Intrinsic "regexpp" returns 1 if its lone argument evaluates to a com-
     piled regular expression object, otherwise, it returns 0.

   tablep: (tablep expr)
     Intrinsic "tablep" returns 1 if its lone argument evaluates to a table,
     otherwise, it returns 0.

   stackp: (stackp expr)
     Intrinsic "stackp" returns 1 if its lone argument evaluates to a stack,
     otherwise, it returns 0.

   intrinsicp: (intrinsicp expr)
     Intrinsic "intrinsicp" returns 1 if its lone argument evaluates to an
     intrinsic function, otherwise, it returns 0.

   closurep: (closurep expr)
     Intrinsic "closurep" returns 1 if its lone argument evaluates to a clo-
     sure, otherwise, it returns 0.

   macrop: (macrop expr)
     Intrinsic "macrop" returns 1 if its lone argument evaluates to a macro
     closure, otherwise, it returns 0.

   recordp: (recordp expr)
     Intrinsic "recordp" returns 1 if its lone argument evaluates to a record,
     otherwise it returns 0.

   sqlitep: (sqlitep expr)
     Intrinsic "sqlitep" returns 1 if its lone argument evaluates to a sqlite
     database object, otherwise, it returns 0.

   regcomp: (regcomp expr1 [expr2 [expr 3]])
     The "regcomp" intrinsic accepts one, two, or three arguments, the first
     of which must evaluate to a string, and which is interpreted as a regular
     expression to be compiled into a compiled regular expression object.  The
     function returns the compiled regular expression object if the compila-
     tion is successful, or a string containing an error message, otherwise.
     Regular expression objects are constants which evaluate to themselves.

     The "regcomp" intrinsic also accepts two optional arguments after the
     first.  If the second optional argument is present, it must evaluate to a
     fixnum, and is interpreted as a boolean.  If non-zero, it causes "reg-
     comp" to produce a compiled regular expression which will match text
     case-insensitively.  Without the second argument, "regcomp" defaults to
     case-sensitive matching.  If the third optional argument is present, it
     must evaluate to a fixnum, and is interpreted as a boolean.  If non-zero,
     it prevents "regcomp" from recognizing regular expression operators in
     the first argument.  The resulting compiled expression will match the
     literal string value of the first argument.

     The "regcomp" intrinsic interprets the two-character escape-sequences \t,
     and \b, to represent the tab and space characters respectively, allowing
     one to specify regular expressions containing whitespace, without using
     whitespace.  This can sometimes be convenient.  The carriage return and
     newline characters can also be specified with escape sequences: \r, and
     \n, respectively.  The zero width assertions \< and \> match the null
     string at the beginning and end of a word, respectively.  All the regu-
     lar-expression operators may be escaped with a backslash to include the
     operator as a literal literal character in the expression.  Unrecognized
     escape sequences will be replaced with the escaped character.  The back-
     slash will be consumed.  All escape sequences are ignored and left
     unchanged in the expression if a non-zero third argument has been passed
     to "regcomp".

   substitute: (substitute expr1 expr2 expr3 [expr4])
     Intrinsic "substitute" performs search and replace operations on strings
     using regular expressions to specify the matches.  The function uses a
     template string to specify the replacement text, in a manner similar to
     that of the substitute commands of ed and sed, where the template may
     refer to the text of the match, and the text matched by parenthesized
     subexpressions.  There is also a "replace" library function available,
     described elsewhere in this document, which allows the replacement
     expression to be a snippet of lisp, which is evaluated upon each match to
     dynamically generate the replacement text.

     The "substitute" function takes three or four arguments, and returns a
     new string, incorporating the appropriate replacements.  The first argu-
     ment must evaluate to a compiled regular expression.  See the "regcomp"
     intrinsic for more information on compiling regular expressions.  The
     second and third arguments must evaluate to strings, and are interpreted
     as the replacement string, and the string to search for matches in,
     respectively.  The fourth optional argument, if present, must evaluate to
     a number, which indicates the number of matches which should be replaced.
     A value of 0 indicates the substitution should replace all the matches of
     the pattern in the text of the third argument.  The absence of the fourth
     argument is the same as having a fourth argument of 1, which is to say,
     only the first match will be replaced.

     The text matched by the first ten subexpressions in the regular expres-
     sion may be inserted into the replacement string by including an escape
     sequence of the form \[0-9] in the replacement text where one wishes the
     matched text to appear. The first subexpression is referred to by \1 and
     the tenth subexpression is referred to by \0.  The text matched by the
     entire regular expression may be inserted into the replacement text by
     inserting \& into the replacement string at the desired location.  In the
     replacement string unrecognized escape sequences are replaced with the
     unescaped character.  To escape the backslash, to cause a literal back-
     slash to appear in the substitution, a total of four backslashes are nec-
     essary in the replacement string.  One level of escaping will be removed
     by the lisp string parser, leaving two backslashes for "substitute" to
     see, the first one escaping the second.  Note that Munger's string parser
     will not remove unrecognized escape sequences, so that this double level
     of escaping is only necessary when the backslash itself is being escaped.

     > (substitute (regcomp "string") "booger" "string string string string" 2)
     "booger booger string string"

     > (substitute (regcomp "[a-z]+") "{\&}"  "one two three" 0)
     "{one} {two} {three}"

     > (substitute (regcomp "([a-zA-Z]+) ([a-zA-Z]+)") "\2 \1"
     >> "is This sentence a."  0)
     "This is a sentence."

     The "substitute" intrinsic interprets the two-character escape-sequences
     \t, and \b, to represent the tab and space characters respectively,
     allowing one to specify whitespace in the replacement string, without
     using whitespace.  This can sometimes be convenient.  Five other escape
     sequences may be embedded in the replacement string to control the case
     of portions of the returned string.  These escape sequences work for
     strings of ASCII alphanumeric characters, only:

     \U Turns on conversion to uppercase.
     \u Turns on conversion to uppercase for the next character only.
     \L Turns on conversion to lowercase.
     \l Turns on conversion to lowercase for the next character only.
     \e Turns off \U or \L.

     > (substitute (regcomp "foo") "\U\&\e" "foobar")
     "FOObar"

     The effects of \U and \L extend beyond the replacement string if they are
     not terminated:

     > (substitute (regcomp "foo") "\U\&"  "foobar")
     "FOOBAR"

     \U and \L override each other:

     > (substitute (regcomp "foo") "\U\&\L" "foobar FUNBAG")
     "FOObar funbag"

   match: (match expr1 expr2)
     The "match" intrinsic matches a regular expression against a string, and
     returns a two element list if the regular expression finds a match within
     the string, or the empty list otherwise.  The function accepts two argu-
     ments, the first of which must evaluate to a compiled regular expression
     object, while the second must evaluate to the string to match the regular
     expression against.  The two-element list returned upon success, consists
     of the character indices of the starting and ending locations of the
     matched text.  The second index is the start of the text following the
     match.  These two indices may be used in conjunction with the "substring"
     intrinsic, to extract the text before, after, or containing the match:

     > (set 'rx (regcomp "foobar"))
     <REGEXP#3>
     > (set 's "---foobar---")
     "---foobar---"
     > (match rx s)
     (3 9)
     > (substring s 0 3) ; text before the match
     "---"
     > (substring s 3 (- 9 3)) ; text of the match
     "foobar"
     > (substring s 9 0) ; text after the match
     "---"

     Note that if the first returned index were 0, the first invocation of
     "substring" above would have returned the whole string, because passing a
     third length argument of 0 to "substring" means "to the end of the
     string."  This should not be a problem, since a first returned index of 0
     indicates there is no text before the match.  The programmer can check
     for this situation before invoking "substring".

     The "matches" intrinsic, described directly below, can be used to extract
     the text of a match and any matching parenthesized subexpressions; while
     "match" itself, is intended to be used in situations where it is only
     necessary to know whether a match occurred or not, or if the text not
     matched needs to be accessed, or if the location of the match is
     required.

   matches: (matches expr1 expr2)
     The "matches" intrinsic accepts the same arguments as the "match" intrin-
     sic, but returns a list, which if non-empty, describes the text matched.

     If no match were found, the list will be empty.  Otherwise, a list of
     twenty strings will be returned.  The first string of the list will be
     the text matched by the entire regular expression, while the subsequent
     elements of the list will be the text matched by the first nineteen
     parenthesized subexpressions in the regular expression.  If nineteen
     subexpressions are not present in the regular expression, empty strings
     will be returned for the missing subexpressions.  If a subexpression
     fails to match, an empty string will be returned in the corresponding
     position of the list.

     > (matches (regcomp "[0-9]+") "I have 22 figurines.")
     ("22" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "")
     > (matches (regcomp "([0-9])+") "12345")
     ("12345"  "5" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "")
     > (matches (regcomp "([0-9]+)") "12345")
     ("12345"  "12345" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" ")

     If one is using a regular expression with a lot of parenthesized subex-
     pressions, it may be more convenient to assign the results of invoking
     "matches" to a stack.  The final zero in the example below is the return
     value of the "print" intrinsic.

     > (set 'rx (regcomp "(.)(.)(.)(.)(.*)"))
     <REGEX1>
     > (when (used (set 's (assign (stack) (matches rx "fooobar"))))
     >> (for (a 0 19)
     >>> (print (index s a) ":")))
     foobar:f:o:o:o:bar:::::::::::::::1

   split: (split expr1 expr2 [expr3])
     The "split" intrinsic is used to break up a string into substrings at
     delimiter characters.  It accepts either two or three arguments.  Both of
     the first two arguments must evaluate to strings.  The first is inter-
     preted as a set of delimiter characters which specify where the second
     argument should be split.  Where a character from the delimiter string
     occurs in the second argument, it is consumed, breaking up the second
     argument into pieces.  The pieces are returned as a list of strings.  The
     optional third argument must evaluate to a number, and specifies a limit
     on the number of pieces the second argument is to be split into.  If the
     first argument is the empty string, then the second argument is split up
     character-by-character.  The original string is unchanged.  The "split"
     intrinsic will return empty strings for empty fields in the original
     string.  Delimiter characters occurring adjacent to each other, or at the
     very start or very end of the second argument, will be recognized as
     empty fields.  If none of the delimiter characters can be found in the
     string, then the returned list will contain only the original string.

     > (split " "  "Lisp is an applicative language.")
     ("Lisp" "is" "an" "applicative" "language.")
     > (split " "  "Lisp is an applicative language.", 3)
     ("Lisp" "is" "an applicative language.")
     > (split "" "Lisp is an applicative language", 3)
     ("L" "i" "sp is an applicative language")
     > (split ":" ":a:b:c:")
     ("" "a" "b" "c" "")

   split_rx: (split_rx expr1 expr2 [expr3])
     The "split_rx" library function is used to break up a string into sub-
     strings using a regular expression to specify delimiter substrings.  It
     works analogously to the "split" intrinsic, except the first argument
     must evaluate to a compiled regular expression object.  As with "split",
     the second argument must evaluate to a string, and the third argument, if
     present limits the number pieces the second argument will be broken into.
     The supplied regular expression is matched against the second argument,
     then the text of matches is consumed to split the second argument into
     pieces, which are gathered into a list and returned.  The function
     returns a list containing only the original second argument, if no match
     on the regular expression can be found.  Empty fields cannot be detected
     by split_rx.

     > (setq rx (regcomp "[\b\t]+"))
     <REGEXP#34>
     > (split_rx rx "foobar    tooley marzipan  loopy    ")
     ("foobar" "tooley" "marzipan" "loopy")

   rootname: (rootname expr)
     The "rootname" library function accepts one argument which must evaluate
     to a string, and returns the portion of that string, without the last
     trailing filename suffix.  If the argument does not have a suffix the
     original string is returned.

     > (rootname "foobar.tar.gz")
     "foobar.tar"
     > (rootname (rootname "foobar.tar.gz"))
     "foobar"

   suffix: (suffix expr)
     The "suffix" library function accepts one argument which must evaluate to
     a string and returns the last filename suffix contained in the string.
     If the string does not end with a filename suffix, the original string is
     returned.

     > (suffix "foobar.tar.gz")
     ".gz"
     > (suffix (rootname "foobar.tar.gz"))
     ".tar"

   tokenize: (tokenize expr)
     The "tokenize" library function accepts one argument which must evaluate
     to a string, and returns a list consisting of all the tokens embedded in
     the string composed of contiguous non-whitespace characters.  The func-
     tion returns a list containing only the original argument string if it
     contains no whitespace.

     > (tokenize "  foobar tooley   hot-cha-cha!")
     ("foobar" "tooley" "hot-cha-cha!")

   replace: (replace expr1 expr2 expr3 [expr4])
     The "replace" library macro behaves similarly to the "substitute" intrin-
     sic, except that the replacement expression will be executed once for
     every match in the string.  This allows the replacement string to be
     dynamically created for each match.  The function accepts three or four
     arguments.  The first argument must evaluate to a compiled regular
     expression object.  The second argument is the expression to create the
     replacement string and is evaluated in a lexical context where the sym-
     bols m0...m19 are bound to the text of the full match, and the text
     matched by the first nineteen parenthesized subexpressions, respectively.
     Note that the resulting string this argument produces when evaluated will
     undergo some escape-processing, because it is ultimately used as the
     replacement pattern for a call to the "substitute" intrinsic.  See the
     entry describing that function, elsewhere in this document, for details
     on the escape sequences recognized.  Note also, one can simply pass a
     string as the second argument, but in that case it is much more efficient
     to use "substitute" directly.  The third argument must evaluate to the
     string the regular expression is to be matched against.  The fourth
     optional argument, if present is a repeat count, and can be used to limit
     the number of replacements made in the string.  Unlike the "substitute"
     intrinsic, "replace" interprets a repeat count of 0 as a request to
     inhibit any substitutions from being performed.  If the repeat count is
     not present, all matches in the string will undergo replacement.  If no
     match is found, the function returns the original string, otherwise it
     returns a new string containing the specified substitutions.

     The following example uses "replace" to decode x-www-form-url-encoded
     characters in a specified string.

     > (setq str "foobar+tooley%7Efunbag%24%25%26")
     "foobar+tooley%7Efunbag%24%25%26"

     > (setq r0 (regcomp "%([0-9A-Fa-f][0-9A-Fa-f])"))
     <REGEXP#10>
     > (setq r1 (regcomp "\+"))
     <REGEXP#11>

     ; Decode encoded spaces.

     > (setq str (substitute r1 " " str 0))
     "foobar tooley%7Efunbag%24%25%26"

     ; Decoded hex encodings.

     >(setq str
     >> (replace r0
     >>>        (char (hex2dec m1))
     >>>        str))
     "foobar tooley~funbag$%&"

   concat: (concat expr ...)
     The "concat" macro is used to concatenate strings.  The macro accepts one
     or more arguments which must all evaluate to strings, or to arbitrarily
     nested lists containing only strings, and returns a single string con-
     sisting of all the argument strings concatenated.

     > (concat "foo" "bar")
     "foobar"
     > (concat '("foo" "bar"))
     "foobar"

   explode: (explode expr)
     The "explode" macro accepts one argument which must evaluate to a string
     and returns a list of one-character strings, corresponding to each char-
     acter in the original string.

     > (explode "foobar")
     ("f" "o" "o" "b" "a" "r")

   join: (join expr1 expr2 expr3...)
     The "join" intrinsic is used to concatenate strings with delimiters.  It
     accepts three or more arguments, which must all evaluate to strings, or
     to arbitrarily-nested lists containing only strings.  The first argument
     is sandwiched between the strings of the remaining arguments to make a
     new string, which is returned.

     > (join " "  "This" "will" "be" "a" "sentence.")
     "This will be a sentence."
     > (join ""  "this" "will" "be" "run" "together")
     "thiswillberuntogether"
     > (join ":" '("a" ("b" ("c") "d") "e"))
     "a:b:c:d:e"

   length: (length expr)
     The "length" intrinsic accepts one argument which must evaluate to a
     string, a record, a stack, a table, or a list, and returns the number of
     characters in the string, the number of key/value pairs in the table, or
     the number of elements in the list.

     > (length "fiver")
     5
     > (length '(a b c))
     3

   sort: (sort [expr...])
     The "sort" intrinsic accepts any number of arguments and sorts them in
     ascending order if they all evaluate to either strings or numbers.
     Invoking "sort" without arguments returns the empty list.  When sorting
     strings, case is ignored.

     > (sort "D" "c" "B" "a")
     ("a" "B" "c" "D")
     > (sort 3 2 1)
     (3 2 1)

   sortlist: (sort expr)
     The "sortlist" intrinsic accepts one argument which must evaluate to a
     list whose elements must be either all numbers or all strings.  The func-
     tion returns a new list whose members are the members of the original
     list sorted into ascending order.  When sorting strings, case is ignored.

     > (sortlist '("c" "b" "a"))
     ("a" "b" "c")
     > (sortlist '(0 -23 1))
     (-23 0 1)

   sortcar: (sortcar expr)
     The "sortcar" intrinsic accepts one argument which must evaluate to a
     list and whose elements must all be lists themselves, whose first ele-
     ments must be either all strings or all numbers.  The function returns a
     new list containing the elements of the original list, sorted using the
     first elements of the sublists as the sort key.  An example will make the
     meaning of this convoluted description clear:

     > (sortcar '(("Z" f f) ("B" f f) ("C" f f)))
     (("B" f f)("C" f f)("Z" f f))

     "sortcar" is useful for sorting aggregate types.  The following example
     sorts a stack-of-stacks, using the second element of each substack as the
     sort key.  Perl users may recognize this as an example of an idiom that
     community has come to call "The Schwartzian Transform," but of course,
     this sort of thing is pure lisp.

     > (set 's (stack 3))
     <STACK1>
     > (store s 0 (assign (stack) '(f 2 f)))
     <STACK2>
     > (store s 1 (assign (stack) '(f 1 f)))
     <STACK3>
     > (store s 2 (assign (stack) '(f 0 f)))
     <STACK4>
     > (flatten s)
     (<STACK2> <STACK3> <STACK4>)
     > (assign s (mapcar (lambda (x) (cadr x))
                         (sortcar (mapcar (lambda (x) (list (index x 1) x))
                                          (flatten s)))))
     <STACK1>
     > (flatten s)
     (<STACK4> <STACK3> <STACK2>)

   until: (until expr1 [expr2 ...])
   while: (while expr1 [expr2 ...])
     The "while" intrinsic is a looping construct.  It accepts one or more
     arguments, the first of which is the test condition.  If it evaluates to
     a true value (anything other than 0 (fixnum), the empty string, or the
     empty list), the rest of the arguments are evaluated in order.  This
     process is repeated until the first argument no longer evaluates to a
     true value, when the loop stops without evaluation of the other argu-
     ments.  Therefore a while-loop will execute zero or more times.  The
     "while" intrinsic returns the value of the failed test expression.

     The "until" intrinsic has similar behavior to the "while" intrinsic,
     except the logic of the test is inverted, which is to say the body of an
     "until" loop is executed as long as the test condition evaluates to a
     false value, or, phrased another way, until the test condition evaluates
     to a true value.

     > (setq n 10)
     10
     > (while n
     >>> (print n)
     >>> (newline)
     >>> (setq n (- n 1)))
     10 9 8 7 6 5 4 3 2 1
     1
     > (setq n 0)
     0
     > (setq l ())
     ()
     > (until (eq n 10)
     >> (setq l (cons (inc n) l)))
     1
     > l
     (10 9 8 7 6 5 4 3 2 1)

     The final 1 here is the return value of the "while" expression.

   do: (do expr1 [expr2 ...])
     The "do" intrinsic introduces a looping construct.  It accepts one or
     more arguments.  All the arguments are evaluated in order.  If the last
     expression evaluates to a true value (anything other than 0, the empty
     string, or the empty list), then all the argument expressions are evalu-
     ated again.  This process repeats until the last expression evaluates to
     a "false" value, when the loop exits without further evaluation.  A do-
     loop will therefore evaluate its argument expressions one or more times.
     The "do" intrinsic returns the value of the failed test expression.

     > (set 'n 0)
     0
     > (do
     >> (print n)
     >> (newline)
     >> (set 'n (+ n 1)))
     > (< n 10))
     0 1 2 3 4 5 6 7 8 9
     1
     >

     The final 1 here is the return value of the "do" expression.

   fatal: (fatal)
   nofatal: (nofatal)
     The "fatal" and "nofatal" intrinsics, accept no arguments, and determine
     if errors encountered during evaluation will cause the interpreter to
     exit.  When the interpreter starts it is in the "nofatal" state.  If an
     error is encountered in the "nofatal" state, the stack will unwind back
     to the toplevel interpreter prompt.  After "fatal" has been invoked, all
     errors which stop evaluation will additionally cause the interpreter to
     exit.  Invoking "die" when in the "fatal" state, will also cause the
     interpreter to exit up return to toplevel.

   die: (die [expr...])
     Intrinsic "die" forces the interpreter to stop evaluating any lisp it may
     be evaluating and return to the toplevel.  The optional arguments are
     passed to the "warn" intrinsic.  Invoking "die" when "fatal" has been
     invoked will cause the interpreter to exit, upon return to toplevel.

   throw: (throw expr)
   catch: (catch [expr1]...)
     The "catch" intrinsic together with the "throw" intrinsic provide a means
     of performing non-local exits.  The arguments to catch are evaluated in
     an implicit "progn" and the result of the evaluation of the last expres-
     sion is returned.  If, however, a "throw" expression is encountered while
     evaluating any of the arguments to "catch" then the thread of execution
     returns to the catch expression.  The "catch" form immediately returns,
     with the result of evaluating the argument to the "throw" expression
     becoming the return value of the "catch" expression.  A "throw" is caught
     by its enclosing "catch" expression, if there is one, or if there is no
     enclosing "catch" expression, the interpreter returns to the toplevel,
     just as if the "die" intrinsic has been invoked.  If the "fatal" intrin-
     sic has been previously invoked, an uncaught "throw" will cause the
     interpreter to exit.

     > (catch
     >> (print (catch 0 (throw 'hello) 2 3 4))
     >> (newline)
     >> (throw 'goodbye)
     >> (print 'not_reached))
     hello
     goodbye
     >

   stringify: (stringify expr...)
     The "stringify" intrinsic accepts one or more arguments which must all
     evaluate to some sort of atom, and converts each atom's print syntax into
     a string.  Then all the strings are concatenated into one string, which
     is returned.

     > (stringify 12 ","  43)
     "12,43"
     > (stringify 'hello " "  'there)
     "hello there"

   digitize: (digitize expr)
     Intrinsic "digitize" accepts one argument which must evaluate to an atom
     and converts it to a number, if possible.  Attempting to apply digitize
     to a non-number will cause it to return 0.

     > (digitize '42)
     42
     > (digitize "-3")
     -3

   mapcar: (mapcar expr1 expr2)
     The "mapcar" library function accepts two arguments, the first of which
     must evaluate to a monadic closure or a monadic intrinsic function or an
     intrinsic which may accept one or more arguments, such as the "print"
     intrinsic, while the second argument must evaluate to a list.  The macro
     applies the function to each element of the list, returning a new list
     containing the results of each evaluation.

     > (set 'l '(a b c))
     (a b c)
     > (set 'f (lambda (n) (list n n n)))
     <CLOSURE#23>
     > (mapcar f l)
     ((a a a) (b b b) (c c c))

   map: (map expr1 expr2 ...)
     The "map" library function is a generalized version of "mapcar".  The
     function accepts two or more arguments, the first of which must evaluate
     to a closure or an intrinsic function, while the remaining arguments must
     all evaluate to lists of the same length.  The function passed as the
     first argument must accept as many arguments as there are list arguments.
     A new list is returned consisting of the result of successively applying
     the function to a grouping of elements from each list.  The elements of
     the lists are successively grouped according to position.

     > (map (lambda (x y z) (+ x y z)) '(1 2 3) '(4 5 6) '(7 8 9))
     (12 15 18)

   remove: (remove expr1 expr2)
     Library function "remove" accepts two arguments, an expression of any
     type, and a list, respectively, and returns a new list which is a copy of
     the argument list, with all occurrences of the first argument removed.
     The function uses library function "equal" to test for equivalency.

     > (remove 'a '(a a a b))
     (b)

     > (remove '(a b) '((a b) c (a b) (a b) d e f g))
     (c d e f g)

   nthcdr: (nthcdr expr1 expr2)
     The "nthcdr" intrinsic returns the "nth" cdr of a list.  The function
     accepts two arguments.  The first must evaluate to a list.  The second
     must evaluate to a positive fixnum.  The function returns the list which
     would be created if "cdr" were applied to the list the number of times
     specified by the second argument.  If the list has insufficient elements
     to complete the request, the empty list is returned.

     > (nthcdr '(a b c) 1)
     (b c)
     > (nthcdr '(a b c) 2)
     (c)
     > (nthcdr '(a b c) 3)
     ()

   nth: (nth expr1 expr2)
     The "nth" intrinsic returns the "nth" element of a list.  elements are
     numbered starting from zero.  The function accepts two arguments.  The
     first must evaluate to a list, while the second must evaluate to a posi-
     tive fixnum specifying the index position of the desired element.  The
     function returns the specified element, if it can.  If the list has
     insufficient elements to satisfy the request, then the function returns
     the empty list.

     > (setq l '(a b c))
     (a b c)
     > (for (n (length l) 0)
     >>  (println (nth l n)))
     ()
     c
     b
     a
     0 ; This is the return value of "while"

   member: (member expr1 expr2)
     Library function "member" accepts two arguments, the first of which can
     evaluate to any lisp object, while the second must evaluate to a list.
     If the first argument is "equal" to any element of the list 1 is
     returned, else 0 is returned.

     > (member 'a '(a b c))
     1

   reverse: (reverse expr1)
     Library function "reverse" accepts one argument, which must evaluate to a
     list or a string.  If a list the function creates a new list containing
     the same elements as the original list, in reverse order.  If the argu-
     ment is a string the function creates a new string consisting of the same
     characters as the original, but in reverse order.

     > (reverse '(a b c))
     (c b a)
     > (reverse "hello")
     "olleh"

   append: (append expr1 ...)
     The "append" intrinsic accepts one or more arguments which all must eval-
     uate to lists, and returns a new list consisting of the elements of the
     argument lists.

   loop: (loop expr1 ...)
     The "loop" intrinsic implements an infinite loop.  The function accepts
     one or more arguments, and evaluates them in order, repeatedly.  The
     return value of each body expression is discarded.  The only way to exit
     a "loop" loop is to wrap it in a "catch" and invoke "throw" in the body:

     > (catch
     >> (loop
     >>> (if (setq line (getline))
     >>>> (print line)
     >>>> (throw line))))

   iterate: (iterate expr1 ...)
     The "iterate" intrinsic executes expressions a specified number of times.
     Unlike the "for" intrinsic it does not make an index variable visible to
     the expressions in its body.  The function accepts one or more arguments,
     the first of which must evaluate to a number and specifies the number of
     times the loop will execute.  A negative repeat count will be converted
     into a positive value by converting it to its absolute value.  The subse-
     quent expressions, if any, are optional.  If present, each subsequent
     expression will be executed in order on each iteration of the loop.  The
     result of evaluating the last body expression in the loop, on the last
     iteration, will be returned, or if no further arguments were provided
     beyond the repeat count, the repeat count will be returned.  The "iter-
     ate" intrinsic is the fastest means of iteration available in the Munger
     interpreter.

     > (iterate 10 (print "A"))
     AAAAAAAAAA1

     The 1 is the return value of the "print" intrinsic, which is in turn the
     return value of "iterate".

   for: (for (symbol expr1 expr2 [expr3]) expr ...)
   for: (for (([expr...]) (expr [...]) ([expr...])) expr ...)
     The "for" intrinsic provides a looping facility similar to the C "for"
     keyword.  There are two forms of this intrinsic:

     The first form of the "for" intrinsic executes loops with an index vari-
     able set to each of a range of specified fixnum values upon each itera-
     tion.  It is the most efficient means of iterating a fixed number of
     times, if the loop body needs a visible index variable.  Two or more
     arguments must be provided.  The first is expected to be a three or four
     element list consisting of a symbol to be used for the loop index vari-
     able, an expression evaluating to the initial number value for the index
     variable, an expression evaluating to the number value the index variable
     should have on the last iteration of the loop, and an optional increment
     value.  If the start value is less than or equal to the stop value, the
     index variable will be incremented on each iteration, otherwise it will
     be decremented on each iteration.  Each of the remaining arguments from
     the second argument on, will be evaluated during each iteration of the
     loop.  The "for" function always returns the value of the last body
     expression evaluated on the last iteration.

     An optional fourth element may be present in the first argument list, and
     if present, it must evaluate to a fixnum specifying the increment or
     decrement value.  The absolute value of the argument will be added or
     subtracted from the index, depending upon whether the first element is
     lesser-than-or-equal-to, or greater than the second element, respec-
     tively.  If the fourth element is not present, the increment value
     defaults to 1.  If incrementing or decrementing of the index results val-
     ues that do not ever become the stop value, then the index value on the
     last iteration of the loop will be the last index value which was within
     the range specified by the start and stop values, inclusive.

     A "for" loop introduces a new environment for the loop's index variable.
     If a closure is formed in the body of a "for" loop, it will close over
     the new environment.  Any invocations of "extend" or "dynamic_extent"
     directly inside of a "for" loop body will affect the environment of the
     loop and not the environment in which the loop is embedded.

     > (for (n 0 10 2)
     >> (println n))
     0
     2
     4
     6
     8
     10
     1 ; return value of "println"

     > (set 'a 5)
     5
     > (for (a a 1)
     >> (for (a a (+ a a))
     >>> (print a " "))
     >> (newline))
     5 6 7 8 9 10
     4 5 6 7 8
     3 4 5 6
     2 3 4
     1 2
     1 ; return value of inner "newline"
     >

     It is possible to invoke "continue" inside a for loop such that no return
     value is ever generated by any of the contained expressions.  In that case,
     "for" returns 0.

     The second form of the "for" intrinsic provides a more generic looping
     facility.  With this form, the first argument must also be a three-ele-
     ment list, and the subsequent arguments are the loop's body expressions,
     but with this form, each sublist of the first argument list, must also be
     a list.  The first sublist is a list of expressions to be evaluated once,
     in order, before any other part of the loop is evaluated, and may be
     empty.  The second sublist consists of one or more expressions, the first
     of which is the test condition, and will be evaluated before every entry
     into the loop body, while the remaining elements are the final expres-
     sions which are evaluated as the last act of the "for" intrinsic.  The
     elements after the test expression may be omitted.  The third sublist
     contains the update expressions to be evaluated after evaluation of the
     loop body expressions, and may be empty.

     Execution of the loop proceeds as follows.  The initialization expres-
     sions are evaluated, then the actions described in the next paragraph are
     repeated until the test expression evaluates to a false value:

   REPEAT
     The test condition is evaluated.  If the evaluation of the test condition
     results in a false value, the remaining elements of the second sublist,
     after the test condition, if present, are evaluated in order, and the
     result of the last evaluation becomes the return value of the "for" loop.
     If there are no expressions after the test expression, then the result of
     the failed test expression becomes the return value of the loop.  The
     loop is finished.  Otherwise, if the evaluation of the test condition
     results in a true value, each of the body expressions are evaluated in
     order, and then each of the elements of the update sublist are evaluated,
     in order.  Goto REPEAT.

     One might write a factorial function with this version of "for" like
     this:

     (defun fact (n)
        (for (((extend 'a 1)) ((> n 1) a) ((dec n)))
           (setq a (* n a))))

   downcase: (downcase expr1 expr2)
   upcase: (upcase expr1 expr2)
     The "upcase" library function accepts two arguments, the first of which
     must evaluate to a string, and the second of which is treated as a logi-
     cal true or false value after evaluation.  If the second argument evalu-
     ates to a true value, then "upcase" will return a new string consisting
     of all the characters of the first argument string, but with any lower-
     case alphabetic characters replaced with their corresponding uppercase
     characters.  If the second argument evaluates to a false value, then only
     the first lowercase alphabetic character encountered in the first argu-
     ment will be so converted.  In either case, if no lowercase alphabetic
     characters are present in the first argument, the returned string will be
     an exact copy of the first argument.

     The "downcase" library function behaves similarly to "upcase", except it
     converts lowercase alphabetic characters to uppercase alphabetic charac-
     ters.

   alist_lookup: (alist_lookup expr1 expr2)
     The "alist_lookup" library function accepts two arguments.  The second
     must evaluate to an alist, while the result of evaluating the first argu-
     ment is treated as a key of the alist.  The function returns the cdr of
     the first sublist of the alist whose car is equal to the key.

     > (set 'y '((a b) (b c)))
     ((a b) (b c))
     > (alist_lookup 'b y)
     (c)
     >

   alist_remove: (alist_remove expr1 expr2)
     The "alist_remove" library function accepts two arguments.  The second
     must evaluate to an alist, while the result of evaluating the first argu-
     ment is treated as a key of the alist.  The function returns a copy of
     the alist with the first sublist whose car is the key, removed.

     > (set 'y '((a b) (b c)))
     ((a b) (b c))
     > (alist_remove 'b y)
     ((a b))
     > y
     ((a b) (b c))
     >

   alist_replace: (alist_replace expr1 expr2 expr3)
     The "alist_replace" library function accepts three arguments.  The second
     must evaluate to an alist, while the result of evaluating the first is
     treated as a key of the alist.  The third argument must evaluate to a
     list.  The function returns a copy of the alist with the first sublist
     whose car is the key, removed, if such a sublist exists, and containing a
     new sublist consisting of the key and the elements of the third list.
     The new sublist is added to the front of the alist copy.

     > (set 'y '((a b) (b c)))
     ((a b) (b c))
     > (alist_replace 'b y '(d e f))
     ((b d e f) (a b))

     > (set 'y ())
     ()
     > (alist_replace 'b y '(d e f))
     ((b d e f))
     >

   when: (when expr1 expr2...)
     The "when" intrinsic is a conditional.  It accepts one or more arguments,
     the first being the test condition.  If the test condition evaluates to a
     true value (anything but 0 (fixnum), the empty string, or the empty
     list), then the succeeding arguments are evaluated in order, and the
     result of evaluating the last argument is returned.  Otherwise, if the
     test condition evaluated to a false value, that value is returned.

     > (when (eq 1 1)
     >> (print 'hello)
     >> (newline))
     hello
     1
     >

   unless: (unless expr1 expr2...)
     The "unless" intrinsic is a conditional, which operates logically oppo-
     site to the "when" intrinsic.  The function accepts one or more argu-
     ments, the first of which is the test condition.  If the first argument
     evaluates to a false value (0 (fixnum), the empty list, or the empty
     string), the succeeding arguments are evaluated in order, and the result
     of evaluating the last argument is returned.  Otherwise, if the first
     argument evaluated to a true value, that value is returned.

     > (unless (eq 1 1)
     >> (print 'hello)
     >> (newline))
     1
     >

   apply: (apply expr1 expr2)
     The "apply" macro accepts two arguments, the first of which must evaluate
     to a function and the second of which must evaluate to a list.  the func-
     tion is called with all the elements of the second argument as arguments.
     All "apply" does is cons its first element onto its second and evaluate
     the result.

     > (apply 'set '('q 2))
     2

   inc: (inc symbol [expr])
   dec: (dec symbol [expr])
     The "inc" and "dec" intrinsics increment and decrement a numerical value
     bound to a symbol, and rebind the symbol to the resultant value.  Both
     functions accept either one or two arguments.  The first argument is not
     evaluated, and must be a symbol currently bound to a number.  The second
     optional argument, if present, must evaluate to a number.  The value
     bound to the symbol is incremented or decremented by the value specified
     by the second argument, or if the function were not presented with a sec-
     ond argument, by 1, and this new value is then bound to the symbol.  The
     new value is returned.

     > (set 'a 1)
     1
     > (inc a)
     2
     > (dec a)
     1
     > (inc a 10)
     11

   test: (test expr1)
     The "test" intrinsic is used to test macro expansion.  Its lone argument
     is NOT evaluated, and must be a list consisting of a macro application,
     just as one would enter it at the interpreter prompt.  The function
     returns the result of expanding the macro.

     > (test (let ((f "foobar")) f))
     ((lambda (f) f) "foobar")

     > (test (setq a 2))
     (set (quote a) 2)

   continue: (continue)
     The "continue" intrinsic, when invoked from inside a "while", "do",
     "for", "iterate", or "loop" loop will cause the loop to skip any subse-
     quent expressions in the loop and jump to the top of the loop to continue
     with the next iteration.  Note, that invoking "continue" inside of a do
     loop will prevent the evaluation of the test condition.  An infinite loop
     may result in certain situations.

     If "continue" is invoked outside of the body of a loop, then the stack
     will unwind until the interpreter returns to the toplevel prompt.

     > (set 'n 10)
     10
     > (while n
     >> (print n)
     >> (newline)
     >> (set 'n (- n 1))
     >> (continue)
     >> (set 'n 0))
     10
     9
     8
     7
     6
     5
     4
     3
     2
     1
     0
     >
     The last 0 is the return value of the "while" intrinsic.

   block: (block)
   unblock: (unblock)
     The "block" and "unblock" intrinsics accept no arguments, and determine
     whether SIGINT, SIGQUIT, and SIGHUP will kill the interpreter, and
     whether SIGTSTP, SIGTTIN, and SIGTTOU are ignored by the interpreter.
     The interpreter starts out with an implicit call to "unblock."  When in
     the unblocked state, the interpreter will be killed upon receipt of SIG-
     INT, SIGQUIT, and SIGHUP, and it will be stopped upon receipt of SIGTSTP,
     SIGTTIN, or SIGTTOU.  It will additionally generate a core dump upon
     receipt of SIGQUIT.  Invoking "block" renders all of these signals impo-
     tent.  Both of these functions always return 1.

     SIGTERM is caught by the interprepter.  The "sigtermp" intrinsic can be
     used to detect the occurrence of SIGTERM.

   sigtermp: (sigtermp)
     The "sigtermp" intrinsic accepts no arguments and returns either 0 or 1
     indicating whether the interpreter has received a SIGTERM since the last
     invocation of "sigtermp".

   exists: (exists expr)
     The "exists" intrinsic accepts one argument which must evaluate to a
     string, and attempts to stat() a file system entity with the name speci-
     fied by the string.  If the call to stat() succeeds "exists" returns a
     value in the range of 1 to 8, otherwise, it returns 0 if the entity does
     not exist, or -1 if the interpreter lacks permission to search one of the
     directories in the specified path.  Note the interpreter does not need
     permission to read the file itself in order to stat() it.  Possible suc-
     cessful return values are:

     1 == regular file
     2 == directory
     3 == character device
     4 == block device
     5 == fifo
     6 == symbolic link
     7 == socket
     8 == unknown type

   stat: (stat expr)
     The "stat" intrinsic accepts one argument, which must evaluate to a
     string.  The argument is interpreted as a filename to be passed to the
     stat() system call.  The function returns a list.  If the specified
     entity does not exist, or the interpreter does not have search permission
     for one of the directories in the specified path, the returned list will
     be empty.  Any other error condition will cause the function return a
     string describing the error.  Upon successful return of stat(), a five-
     element list will be returned, containing, in order, a string containing
     the user name associated with the uid of the file, or if the uid does not
     map to a user on the system, the uid itself expressed as an integer, a
     string containing the group name associated with the gid of the file, or
     if the gid does not map to a group on the system, the gid itself
     expressed as an integer, the time of the last access of the file, the
     time of the last modification of the file, and the size of the file.  The
     time values are expressed in seconds elapsed since the UNIX Epoch
     (00:00:00 January 1, 1970 UTC).

     > (stat (current))
     ("root" "wheel" 1097210850 1097210836 417214)

   rename: (rename expr1 expr2)
     The "rename" intrinsic is used to rename entries in the filesystem.  Its
     semantics are the same as those of the system call of the same name, for
     which is a wrapper.  The function accepts two arguments, both of which
     must evaluate to strings.  The first specifies the current name of the
     filesystem entity, and the second is the new name it will have if the
     function succeeds.  1 is returned upon success, or in the case of system
     call failure, a string describing the error is returned.  All other
     errors will stop evaluation.

   current: (current)
     The interpreter maintains a pointer to an element of the argument list it
     was started with.  The "current" intrinsic accepts no arguments, and
     returns a string representing the current argument the argument pointer
     points to.  At startup "current" will return the name the interpreter was
     invoked by, which is always the first argument passed to programs running
     under UNIX.  See the "prev" "next" and "rewind" intrinsics for accessing
     the other command line arguments.

   prev: (prev)
     The "prev" intrinsic steps the argument pointer back to the previous com-
     mand line argument, if one exists.  If no previous argument exists,
     "prev" returns zero, otherwise the previous argument is made the current
     argument and is returned as a string.

   next: (next)
     The "next" intrinsic steps the argument pointer forward to the next com-
     mand line argument, if one exists.  If no further arguments exists,
     "next" returns zero, otherwise the next argument is made the current
     argument, and is returned as a string.

   rewind: (rewind)
     The "rewind" intrinsic accepts no arguments, and sets the interpreter's
     command-line argument pointer to point to the first argument, and returns
     it as a string.  The first argument is always the name by which the
     interpreter program was invoked.

   interact: (interact)
     The "interact" intrinsic causes the interpreter to stop running the cur-
     rent program and work interactively with the user.  It is intended for
     use in programs which need to make the interpreter toplevel temporarily
     available to the user.  The function accepts no arguments, and causes the
     interpreter to enter a new read-eval-print loop.

     To exit the loop and allow the program which invoked "interact" to con-
     tinue, the Control-D may be inputted by itself on a line, or the symbol
     "_" may be input at toplevel.  The function always returns 1.  Recursive
     invocations will cause a string to be returned with an error message, but
     evalution at the prompt of the original invocation will continue nor-
     mally.  Note that the "fatal" intrinisic has no effect when lisp errors
     are generated inside "interact".  This means the interpreter will not
     exit when a lisp error is generated by the user working at the "interact"
     prompt.

     The current local environment is hidden from code run via "interact".  If
     the user wishes to hide the global environment of the program which has
     invoked "interact" from the user, then he or she should wrap the program
     in a giant "let" closure, defining initial bindings for all globals so
     that "defun", "defmac" "set" and "setq" will modify these locally-visible
     bindings and not create global bindings.  An example of this technique
     can be seen in the msh.munger example program.

   pwd: (pwd)
     The "pwd" intrinsic accepts no arguments, and returns the current working
     directory of the interpreter as a string.

   let: (let [list] expr2 ...)
     The "let" intrinsic introduces new local lexical bindings and evaluates a
     list of expressions with those new bindings in place.  The bindings are
     removed when the "let" expression returns.  The first argument is not
     evaluated and must be a parameter list of the form: ((symbol1 expr1)
     (symbol2 expr2)...).  The result of evaluating each exprN in the current
     scope gets bound to its paired symbolN in the new scope.  The remaining
     arguments, if any, are evaluated in the new scope.  The result of the
     last evaluation performed is returned.

     > (let ((a 1) (b 2))
     >> (print "a: "  a "  b: "  b)
     >> (newline))
     a: 1
     b: 2
     1 ; This is the return value of (newline)
     > (set 'a 2)
     2
     > (let ((a (* a a)))
     >> (while a
     >>>> (print "a: "  a)
     >>>> (newline)
     >>>> (set 'a (- a 1))))
     a: 4
     a: 3
     a: 2
     a: 1
     0
     > a
     2

   letn: (letn [list] expr2 ...)
     Intrinsic "letn" introduces new local lexical bindings and evaluates a
     list of expressions with those new bindings in place.  The bindings are
     removed when the "letn" expression returns.  The first argument is not
     evaluated and must be a parameter list of the form: ((symbol1 expr1)
     (symbol2 expr2)...).  The result of evaluating each exprN in the current
     scope gets bound to its paired symbolN in the new scope.  The remaining
     arguments are evaluated in the new scope.  The value of the last evalua-
     tion performed is returned.  Intrinsic "letn" is different from intrinsic
     "let" in that each binding made to symbolN is visible in exprN+1,
     exprN+2, etc.  This form is called "let*" in Scheme and Common Lisp.

     > (letn ((a 1)
     >>>      (b (+ a 1)))
     >> (print "b: "  b)
     >> (newline))
     b: 2
     1
     >

   letf: (letf [list] expr2 ...)
     Macro "letf" is the equivalent to a named let in Scheme.  It provides a
     means of creating and applying a temporary function capable of recursing
     on its name.  The macro accepts two or more arguments, the first of which
     must be a symbol, while the second must be a list of the form: ((symbol1
     expr1) (symbol2 expr2) ...).  The result of evaluating each exprN in the
     current scope gets bound to its paired symbolN in a new local lexical
     environment.  The symbol passed as the first argument is visible in the
     new environment to enable recursion by name.  The remaining arguments are
     then evaluated in the new environment, with the value of the last evalua-
     tion performed being returned.

     > (setq a 10)
     10
     > (letf fact ((n a))
     >> (if (< n 2)
     >>>    n
     >>>    (* n (fact (- n 1)))))
     3628800
     >

   tailcall: (tailcall expr1 ...)
     The "tailcall" intrinsic accepts one or more arguments, the first of
     which must evaluate to a closure or 0, while the remaining arguments, if
     any, are the arguments to the closure being tail-called, and must be of
     the correct number and type for the particular closure being invoked.  A
     first argument of 0 indicates the tail-call is a directly recursive call
     of the currently-executing function.  This allows anonymous functions to
     call themselves tail-recursively.  Using tail-calls to implement itera-
     tion is inefficient in Munger, and should be avoided.  See the entries
     for the "for" and "iterate" intrinsics for how to iterate efficiently.

     Tail-calls are used to prevent the control stack from growing unnecessar-
     ily during recursive function calls.  Use "tailcall" whenever you are
     invoking a function from a tail position in another function.

     Some tail-recursive functions do all their computation during the
     "descent" stage of recursion, and only return the final computed value
     during the "ascent" stage when they "unwind".  This means the recursive
     call is in tail position because nothing happens after it has returned.
     Each invocation simply returns to its caller.  Invoking the recursive
     calls with "tailcall" will cause each recursive invocation to replace the
     current context on the call stack with its own context, so that when the
     final recursive invocation returns, it returns to the caller of the first
     invocation.  No "unwinding" occurs.  Each invocation of the function
     therefore has a constant continuation, and the whole computation is
     effectively turned into a loop, inhibiting potentially explosive growth
     of the control stack.

     Other tail-recursive functions pass closures to each recursive invocation
     of themselves to capture state as they descend, with each new closure
     closing over the binding for the previous one.  When these functions bot-
     tom-out, the current closure is invoked as the continuation of the func-
     tion.  It, in turn, performs part of a computation, then invokes the con-
     tinuation from the previous invocation, in tail position, to continue the
     computation, and so on, until the primordial continuation given to the
     toplevel invocation receives the final value of the computation.  Since
     all invocations of the recursive function, and all invocations of the
     dynamically-constructed continuations are in tail position, there is no
     need to save their contexts on the call stack.  Every one can be invoked
     with "tailcall", so that the primordial continuation simply returns to
     the original caller of the first invocation of the recursive function.
     Note that in this case, the savings in growth of the call stack, is lost
     due to the growth of the heap from the creation of a new continuation at
     each invocation.

     Note that invoking "tailcall" from a non-tail position, results in that
     position becoming a tail position.  Any pending computation in the func-
     tion is abandoned.

   labels: (labels [list] expr2 ...)
     The "labels" intrinsic temporarily binds a set of functions to a set of
     symbols, such that each binding is visible in each function, allowing
     recursive and mutually-recursive local functions to be defined in a new
     environment.  The function accepts one or more arguments, the first of
     which must be a list of lists where each sublist consists of a symbol
     paired with a lambda or macro expression.  The remaining arguments are
     evaluated in the new environment, with the value of the last evaluation
     being returned.  An example will make this clear:

     > (labels ((even (lambda (n) (or (eq n 0) (tailcall odd (- n 1)))))
     >>>        (odd  (lambda (n) (and (not (eq n 0)) (tailcall even (- n 1))))))
     >> (print (even 11))
     >> (newline))
     0
     1 ; This is the return value of the "newline".

     Note that it may not be necessary to use "labels" to extend the current
     lexical environment, depending on whether or not the programmer wishes to
     limit the visibility of the functions created to the body of the "labels"
     expression, and whether or not there are any closures formed in the body
     which need to see the new bindings after the "labels" has returned.  If
     both of those behaviors are simultaneously needed, or if the interpreter
     is at toplevel, "labels" must be used.  Otherwise, the current lexical
     environment can be extended with the "extend" intrinsic.  One can achieve
     the same effect as the above example inside a function body with:

     > (defun f ()
     >> (extend 'even (lambda (n) (or (eq n 0) (tailcall odd (- n 1)))))
     >> (extend 'odd (lambda (n) (and (not (eq n 0)) (tailcall even (- n 1)))))
     >> (print (even 11))
     >> (newline))
     > (f)
     0
     1

     The bindings created by "extend" have unlimited extent, so if closures
     were formed in the body of "f" they would close over the new bindings,
     even if the closures were closed before the invocations of "extend".  See
     the entries for the "extend" and "dynamic_extent" intrinsics for more
     details on extending the current lexical environment.

   extract: (extract expr)
     The "extract" intrinsic extracts the lambda-expression from a function
     closure.  It accepts one argument which must evaluate to a closure, and
     returns the closure's lambda-expression.

     > mapcar
     <CLOSURE#17>
     > (extract mapcar)
     (lambda (f l) (if (pairp l) (cons (f (car l)) (mapcar f (cdr l))) ()))

   cond: (cond [list] ...)
     Intrinsic "cond" is a multiple choice conditional.  The function accepts
     one or more lists as arguments, which must consist of at least two ele-
     ments, and attempts to evaluate the first element of each argument list,
     in order, until an evaluation returns a true value (anything but zero,
     the empty string, or the empty list), when it attempts to evaluate the
     remaining elements of the corresponding sublist.  The value of the last
     evaluation performed in the sublist is returned.  If none of the first
     elements of any of the argument lists evaluate to a true value, then the
     false value returned by the first element of the last argument list will
     be returned.  By placing a first element of 1 in the final sublist, a
     catch-all else clause may be created.

     > (set 'a 10)
     10
     > (cond ((eq a 12) 'no)
     >>      ((eq a 10) 'yes))
     yes
     >

   case: (case expr expr2 ...)
     The "case" macro is a multiple choice conditional.  It accepts two or
     more arguments.  The first argument may be any expression.  The succeed-
     ing elements must be lists.  The first argument is evaluated, and then
     the resulting value is compared against the result of evaluating the
     first elements of each of the succeeding lists, using "eq".  If "eq"
     returns 1, then the succeeding elements of the list with the "eq" first
     element, are evaluated, and the value of evaluating the last element is
     the return value of the invocation of "case".  No other argument lists
     are processed.

     If the first element of any of the argument lists is the question mark,
     ?, then the elements of that list succeeding the question mark will
     always be executed, if none of the preceding list arguments are executed.
     This can be used to create an "else" clause, which will be executed if
     none of the others match.

     > (setq n 3)
     3
     > (case n
     >> (1 'one)
     >> (2 'two)
     >> (3 'three)
     >> (4 'four)
     >> (5 'five))
     three
     > (case n
     >> (6 'six)
     >> (7 'seven)
     >> (8 'eight)
     >> (9 'nine)
     >> (10 'ten)
     >> (? "no match"))
     "no match"

   foreach: (foreach expr1 expr2)
     The "foreach" library function applies a monadic function to every item
     in a list.  Unlike "mapcar", this function does not return a list of the
     return values.  The results of each function application are discarded.
     "foreach" always returns the empty list.

     > (set 'print_each
     >> (lambda (x) (print x) (newline)))
     <CLOSURE#34>
     > (foreach print_each '(a b c d))
     a
     b
     c
     d
     ()
     >

   +: (+ expr...)
     Intrinsic "+"  accepts any number of arguments, evaluates them, and if
     all have evaluated to numbers, adds the numbers together and returns the
     total.

     > (+ 1 1 1 1)
     4
     > (+ 1 "hello")
     +: argument 2 did not evaluate to a number.

   -: (- expr1 expr2)
     Intrinsic "-"  accepts two arguments, both of which must evaluate to num-
     bers, and subtracts the second value from the first and returns the
     result.

     > (- 1 2)
     -1
     > (- (+ 1 1) 2)
     0

   *: (* expr...)
     Intrinsic "*"  accepts one or more arguments which must all evaluate to
     numbers, and multiplies all the values together and returns the result.

     > (* 1 12 2)
     24
     > (* (+ 23 3) 4)
     104

   /: (/ expr1 expr2)
     Intrinsic "/" accepts two arguments both of which must evaluate to num-
     bers, and divides the second value into the first and returns the integer
     part of the quotient.

     > (/ 4 3)
     1

   %: (% expr1 expr2)
     Intrinsic "%" accepts two arguments, both of which must evaluate to num-
     bers, and divides the second value into the first, and returns the the
     remainder.

     > (% 4 3)
     1

   >: (> expr1 expr2)
     Intrinsic ">" accepts two arguments, which both must evaluate to numbers,
     and returns 1 if the first value is larger than the second, or 0 other-
     wise.

     > (> 4 3)
     1
     > (> -4 3)
     0

   >=: (>= expr1 expr2)
     Intrinsic ">=" accepts two arguments which both must evaluate to numbers,
     and returns 1 if the first value is greater than or equal to the second
     value, or 0 otherwise.

     > (>= 4 3)
     1

   <: (< expr1 expr2)
     Intrinsic "<" accepts two arguments, both of which must evaluate to num-
     bers, and returns 1 if the first value is less than the second, or 0 oth-
     erwise.

     > (< 4 3)
     0

   <=: (<= expr1 expr2)
     Intrinsic "<=" accepts two arguments, both of which must evaluate to num-
     bers, and returns 1 if the first value is less than or equal to the sec-
     ond, or 0 otherwise.

     > (<= 3 4)
     0

   negate: (negate expr)
     The "negate" intrinsic accepts one argument which must evaluate to a
     fixnum, and returns that fixnum negated.

     > (negate 3)
     -3
     > (negate -3)
     3

   abs: (abs expr)
     Intrinsic "abs" evaluates its lone argument, and if it evaluates to a
     number, returns the absolute value of the number.  Passing a non-number
     to "abs" will stop evaluation with an error.

   intern: (intern expr1)
     The "intern" intrinsic accepts one argument, which must evaluate to a
     string, and converts it into a symbol token consisting of the same
     sequence of characters, without the enclosing quotation marks.  Passing a
     non-string to "intern" will generate an error which stops evaluation.

     > (set 'hello 4)
     4 (eval (intern "hello"))
     4

   char: (char expr1)
     The "char" intrinsic accepts one argument, which must evaluate to a num-
     ber between 1 and 255, and creates a one-character string consisting of
     the character corresponding to the character code specified by that num-
     ber.

   code: (code expr1)
     The "code" intrinsic accepts one argument which must evaluate to a string
     and returns a number representing the character code of the first charac-
     ter of the string.

   open: (open)
     The "open" intrinsic creates a new text buffer and makes the new buffer
     the active buffer.  The buffer number of the new text buffer is returned
     on success.  Errors stop evaluation.  Buffer numbers are whole numbers,
     and can be used by the "switch" intrinsic to change the active buffer.

   close: (close)
     The "close" intrinsic closes the active text buffer, and makes the most-
     recently opened buffer that has not been closed the active buffer.  1 is
     returned on success.  Errors stop evaluation.

   insert: (insert expr1 expr2 expr3)
     The "insert" intrinsic inserts a line into the active buffer.  It accepts
     three arguments.  The first argument must evaluate to a positive number
     and represents an index position in the buffer.  The second argument,
     which must evaluate to a string, is the data to be inserted.  The third
     argument, which must evaluate to a number, specifies whether the data
     should be inserted before the specified index position, inserted after
     the specified index position, or should overwrite the contents of the
     specified index position.  A value of 0 indicates the index position
     should be overwritten.  A positive value indicates the data should be
     inserted after the specified index.  A negative value indicates the data
     should be inserted before the specified index.  If the specified index
     position does not exist it will be created, and all the index positions
     preceding it in the buffer will also be created and initialized to be
     empty.  1 is returned on success, 0 on failure.

     > (open)
     1
     > (insert 1 "This is the first line." 0)
     1

   delete: (remove expr1)
     The "delete" intrinsic removes a line from the active buffer.  The func-
     tion accepts one argument which must evaluate to a positive integer spec-
     ifying the index of the line in the buffer to be deleted.  1 is returned
     on success, 0 on failure.

   retrieve: (retrieve expr1)
     The "retrieve" intrinsic returns the contents of a specified index posi-
     tion in the active buffer, as a string.  The function accepts one argu-
     ment which must evaluate to a positive integer representing the index of
     the desired line.  An error is generated if the specified index does not
     exist.

   lastline: (lastline)
     The "lastline" intrinsic accepts no arguments, and returns the index
     value of the last line in the active buffer.  Any error encountered will
     stop the interpreter.

   filter: (filter expr1 expr2 expr3)
     The "filter" intrinsic sends a range of lines from the active buffer to
     an external filter program, and replaces the lines in the buffer with the
     output from the filter program.  The function accepts three arguments.
     The first two arguments must evaluate to numbers and inclusively specify
     the range of lines to be sent to the filter program.  The first index
     does not have to be less than the second index.  The lines, however are
     always processed in ascending order, regardless of how the range was
     specified.  An error is generated if any of the lines in the specified
     range do not exist.  The third argument must evaluate to a string, repre-
     senting the command line used to launch the filter.  It is passed to
     /bin/sh for interpretation, and so may contain any expression that pro-
     gram understands.

     Upon success, "filter" returns the number of lines read from the stdout
     of the child process.

   filter_server: (filter_server expr1 expr2 expr3 expr4)
     The "filter_server" library function sends a range of lines in the active
     buffer to a TCP or UNIX domain server and replaces the lines in the
     buffer with the server's response.  This function can be useful in
     retrieving data from http servers.  It accepts four arguments.  The fist
     two arguments must evaluate to fixnums specifying the range of buffer
     lines, inclusive, to be sent to the server.  If the first argument is
     greater than the second, then the lines will be sent to the server in
     reverse order.  The third and fourth arguments are passed to the
     "child_open" intrinsic.  See the entry in this manual for that function
     for details on what these two arguments can be.  The function returns the
     number of lines read back from the server.

     > (open)
     0
     > (insert 1 "GET / HTTP/1.0" 0)
     1
     > (insert 2 "" 0)
     1
     > (for (n 1 2) (insert n (concat (retrieve n) (char 13) (char 10)) 0))
     1
     > (filter_server 1 2 "www.mammothcheese.ca" 80)
     306

     The data returned will not be processed in any way, so the HTTP response
     header will be present, as well as any chunk headers in the response
     body.  The "remove_http_stuff" library function can be used to remove
     these items.

   remove_http_stuff: (remove_http_stuff)
     The "remove_http_stuff" library function accepts no arguments, and if
     invoked after an invocation of "filter_server", will remove the http
     header and merge the response body if it has been "chunked" as per
     HTTP/1.1, from the data in the current buffer.  After invocation, the
     current buffer will contain only the data of the requested resource.

   write: (write expr1 expr2 expr3 expr4 [expr5])
     The "write" intrinsic writes content from the active buffer to a file.
     The function accepts four or five arguments.  The first two arguments
     must evaluate to positive integers, and specify a range of lines, inclu-
     sively, to be written out.  The third argument must evaluate to a string
     representing the filename to be written to.  The fourth argument must
     evaluate to a number, and indicates whether the interpreter should
     attempt to get an exclusive lock on the file before writing to it.  A
     non-zero value means to lock the file, while a value of 0 means to not
     lock the file.  The optional fifth argument, if present, must evaluate to
     a number, and specifies whether the lines from the buffer should be
     appended to an already-existing file, or if a new file should be created,
     overwriting any existing file of the same name.  A non-zero value means
     to append, while a value of 0 results in a new file being created.  If
     the fifth argument is not present, an implicit fifth argument of 0 is
     assumed.  Empty files can be created by passing 0 for both the first and
     second arguments.  "write" creates files with both read and write permis-
     sions enabled for the owner, and read permission enabled for everyone
     else (mode 644).

     The first index argument does not have to be less than the second index
     argument, but the lines in the region so specified will be written to the
     file in ascending order, regardless of how the region was specified.

     Whitespace in the filename can either be present literally, or repre-
     sented with the \t and \b escapes to represent the tab and the space
     character, respectively.  This means if you wish to use a literal \b or
     \t in the filename, you must escape the backslash itself and use \\\\b or
     \\\\t instead.  Remember to embed a single backslash into a string we
     must escape it with another backslash, so to embed two backslashes, we
     need to escape each of them with another backslash, totaling four back-
     slashes.  If this confuses you, try rereading the section on strings at
     the top of this document.

     The number of lines written is returned on success.  If an error is
     encountered opening the file, a string describing the error is returned.
     All other errors stop evaluation.

   read: (read expr1 expr2)
     The "read" intrinsic inserts all the lines from a file into the active
     buffer, inserting the lines after a specified line.  The function accepts
     two arguments.  The first argument must evaluate to a number representing
     the index value of the line after which to insert the newly-read lines.
     If the buffer is empty, the first argument must be 0, or an error is gen-
     erated.  Similarly, to insert lines at the beginning of the buffer, the
     first argument should be 0.  The function returns the number of lines
     read on success, -1 if the file to be read doesn't exist, and -2 if per-
     mission to access the file is denied.  Any other failure of the read()
     system call will return a string describing the error.  Other errors will
     stop evaluation.

     Whitespace in the filename can either be present literally, or repre-
     sented with the \t and \b escapes to represent the tab and the space
     character, respectively.  This means if you wish to use a literal \b or
     \t in the filename, you must escape the backslash itself and use \\\\b or
     \\\\t instead.  Remember to embed a single backslash into a string we
     must escape it with another backslash, so to embed two backslashes, we
     need to escape each of them with another backslash, totaling four back-
     slashes.  If this confuses you, try rereading the section on strings at
     the top of this document.

   empty: (empty)
     The "empty" intrinsic accepts no arguments, and removes all data from the
     active buffer.  All data in the active buffer are permanently lost.

   slice: (slice expr1 expr2 expr3 expr4 expr5)
     The "slice" intrinsic returns part of a line in the active buffer or a
     description of part of a line in the buffer.  The function accepts five
     arguments, which must all evaluate to numbers.  The first argument speci-
     fies the index value of the line to be sliced in the buffer.  The second
     argument specifies the character index where the slice starts.  The third
     argument specifies the length of the slice in characters.  If the length
     argument is zero, this is interpreted as meaning, "to the end of the
     line."  The fourth argument specifies where tabstops occur.  Tabs are
     expanded before the slice is taken, so argument 2 refers to the "screen"
     x-coordinate, which may be different from the actual character located at
     that index position in the buffer, due to tab expansion.  For example, a
     fourth argument of 3 indicates that tabstops are considered to occur
     every three columns.

     The fifth argument specifies what the function returns.  A value of 0
     indicates the caller wishes to receive the specified slice as a string.
     A value of 1 indicates the caller wishes to receive a two-element list
     describing the specified slice.  The first element of this list is the
     length of the slice, in characters, which may be less than the specified
     length, if the specified length extended past the end of the line.  This
     is the actual length of the slice in the buffer before tab expansion.
     The second element is the number of extra characters which would be added
     to the line during tab expansion from the beginning of the line to the
     end of the specified slice.

   find: (find expr1 expr2 expr3 expr4 expr5)
     The "find" intrinsic searches a specified range of lines in the active
     buffer for a match on a specified regular expression.  The function
     accepts five arguments.

     The first three arguments, and the fifth argument, must all evaluate to
     numbers, while the fourth argument must evaluate to a compiled regular
     expression object.  The first argument specifies the direction of the
     search: a positive value causes the search to proceed forward in the
     buffer, while a negative value causes the search to proceed backwards in
     the buffer.  The second argument is interpreted as the line number at
     which to start the search.  The third argument is interpreted as the
     character within the line at which to start the search.  Remember that
     lines in the buffer are indexed from 1, while characters in lines are
     indexed from 0.  The fifth argument specifies whether the search should
     "wraparound" if it fails.  A non-zero value enables wraparound, while 0
     disables wraparound.

     For example, if a search were in the forward direction and failed, a
     fifth argument of 1 would cause the search to begin again at the begin-
     ning of the buffer, looking for matches before the specified starting
     position.  The fourth argument is the compiled regular expression object
     to search for matches with.  A match starting exactly at the specified
     starting place of the search will be ignored, and the position of the
     next non-overlapping match, if any, will be sought.  Newlines are tempo-
     rarily removed from the end of buffer lines before a match is attempted.
     This means ^$ will match empty lines.

     The function returns a list of three numbers.  If a match were found, the
     first element will be the index of the line containing the match, while
     the second element will be the character index in the line of the start
     of the text that matched, and the third element will be the length, in
     characters, of the match.  If no match occurred, all three values will be
     zero.

     The three returned values can be used to pluck out the text of a match
     from the buffer:

     > (open)
     0
     > (insert 1 "this is the first line in the buffer." 0)
     1
     > (set 'f (find 1 1 0 (regcomp "buffer") 0)
     (1 30 7)
     > (substring (retrieve (car f)) (cadr f) (car (cddr f)))
     "buffer"

     The following function will count the number of blank lines in the
     buffer, assuming the buffer has been opened and loaded with text.  New-
     lines are removed from the end of lines before the regular expression is
     applied, so the regular expression will match blank lines.

     (set 'blank
     (lambda ()

        (let ((idx 1)
              (regexp (regcomp "^[\b\t]*$"))
              (count 0))

            (while (set 'idx (car (find 1 idx 0 regexp 0)))
              (inc count))

            count)))

   buffer: (buffer)
     The "buffer" intrinsic accepts no arguments, and returns the buffer num-
     ber of the active text buffer, or -1 if no buffers have been opened.

   buffers: (buffers)
     The "buffers" intrinsic accepts no arguments, and returns a list of whole
     numbers representing the buffer numbers of all currently open buffers.
     If no buffers have been open, the function returns the empty list.

   switch: (switch expr)
     The "switch" intrinsic makes a specified buffer the active buffer.  The
     function accepts one argument which must evaluate to the buffer number of
     an open buffer, and makes that buffer the active buffer.  Errors stop
     evaluation.

   setmark: (setmark expr1 expr2)
     The "setmark" intrinsic is used to mark a line in the buffer for later
     reference.  The function accepts two arguments, the first of which must
     evaluate to an atom of any type, which names the bookmark.  The second
     argument must evaluate to a valid line number of a line in the active
     buffer.  Upon success 1 is returned.  The mark will be adjusted accord-
     ingly after buffer insertions and deletions in order to track the marked
     line.  If the line is subsequently deleted with "delete" then any book-
     marks pointing to that line will be set to -1.  Invoking "getmark" on a
     subsequent occasion will return the marked line's current line number.

     Bookmarks are local to the active buffer, and each buffer may have an
     unlimited number of bookmarked lines.  The active set of bookmarks is
     switched when the "switch" intrinsic changes the active buffer.  Only the
     bookmarks for the active buffer can be altered or examined.

   getmark: (getmark expr1)
     The "getmark" intrinsic is used to retrieve the line number of a marked
     line in the active buffer.  The function accepts one argument which must
     evaluate to an atom of any type, which names the desired bookmark.  The
     current line number of the marked line will be returned if the line has
     not been deleted from the buffer.  If the desired mark has not been set,
     "getmark" returns 0.  If the marked line has been deleted, "getmark"
     returns -1.

   transfer: (transfer b1 f1 t1 b2 t2)
     The "transfer" intrinsic copies a contiguous range of lines from one
     buffer into another already-opened buffer.  The function accepts five
     arguments which must all evaluate to numbers.  The first argument is the
     buffer number of the source buffer.  The second and third arguments spec-
     ify the starting and ending lines, inclusive, of the range to be copied
     from the source buffer.  If the second argument is greater than the
     third, then the lines will be copied in reversed order into the destina-
     tion buffer.  The fourth argument is the buffer number of the destination
     buffer, while the fifth argument is the index in the destination buffer,
     after which the copied lines will be inserted.  To copy lines to the
     front of the destination buffer, a fifth value of 0 is used.  Whatever
     buffer was active when "transfer" was invoked will be active when trans-
     fer returns.  The function returns 1 on success.  Any error will stop
     evaluation.

   with_buffer: (with_buffer expr1 expr2 ...)
     The "with_buffer" macro temporarily changes the active buffer.  The macro
     accepts two or more arguments, the first of which must evaluate to the
     buffer number of an open buffer.  This buffer is made the active buffer,
     and then the arguments subsequent to the first are evaluated.  When the
     last argument has been evaluated the buffer which was active previous to
     the invocation of macro is made the active buffer once again.  The result
     of evaluating the last argument is returned.

   version: (version)
     The "version" intrinsic accepts no arguments and returns a list of two
     numbers: the first being the major version number of the lisp inter-
     preter, and the second being the minor version number.

   gensym: (gensym)
     The "gensym" intrinsic creates and returns a unique anonymous symbol,
     called a gensym.  Gensyms cannot be named in your code, because the lisp
     reader does not recognize the print syntax for a gensym.  Gensyms are
     useful when it is necessary for a macro to create a working variable in
     its returned expression, which must not conflict with other variables
     used in the program invoking the macro.  The customary way to manipulate
     gensyms is to bind them to other symbols, and evaluate these symbols in
     macro templates.

     The definition of the "with_buffer" macro from library.munger is pre-
     sented below as an example.

     (let ((buff (gensym)))

        (set 'with_buffer
           (macro (x (y))

              (qquote
                 (let ((,buff (buffer)))
                    (switch ,x)
                    (protect ,(cons 'progn y)
                       (switch ,buff)))))))

     A gensym is bound to the symbol "buff" in a lexical closure surrounding
     the macro definition.  This symbol's value, the gensym itself, is
     inserted into the macro template at appropriate places to act as a tempo-
     rary to store the buffer current at the time the macro is invoked.
     Because the gensym is anonymous, we can be sure we are not shadowing a
     binding used by the program in which the macro is invoked, which the code
     passed to the macro as its second argument might modify.  Furthermore,
     every invocation of the macro uses the same gensym, because it is created
     in the outer "let" lexical closure enclosing the macro definition, but
     because we insert the gensym into another "let" in the macro expansion,
     we can be sure that nested invocations of "with_buffer" will only see
     their own lexical binding.

   libdir: (libdir)
     The "libdir" intrinsic accepts no arguments and returns a string specify-
     ing the location of the interpreter's library files as a fully-qualified
     directory name, without the trailing virgule.

     > (libdir)
     "/usr/local/share/munger"
     >

   strcmp: (strcmp expr1 expr2)
     The "strcmp" intrinsic lexigraphically compares two strings.  The func-
     tion accepts two arguments which must evaluate to strings, and returns an
     integer greater than, equal to, or lesser than zero, indicating that the
     first string is either "greater than" (would sort after), "equal to"
     (identical), or "less than" (would sort before) the second string.

     > (strcmp "a" "b")
     -1
     > (strcmp "b" "a")
     1
     > (strcmp "a" "a")
     0
     > (strcmp "A" "a")
     -32

   substring: (substring expr1 expr2 expr3)
     The "substring" intrinsic is provided for extracting substrings from
     strings, using character indices.  The function accepts three arguments.
     The first must evaluate to a string, while the second and third must
     evaluate to whole numbers.  The second argument specifies the character
     index (indices start at 0) where the desired substring begins.  The third
     argument is the number of characters to include in the substring.  The
     "substring" intrinsic returns the specified substring as a new string.
     The second index may be zero, which is interpreted to mean "to the end of
     the string."

     > (substring "foobar" 0 0)
     "foobar"
     > (substring "foobar" 3 0)
     "bar"
     > (substring "foobar" 0 3)
     "foo"
     > (substring "foobar" 0 10)
     "foobar"

   expand: (expand expr1 expr2)
     The "expand" intrinsic performs tab expansion on arbitrary strings.  The
     function accepts two arguments, the first of which must evaluate to a
     positive integer, while the second must evaluate to a string.  The first
     value is interpreted as the location of tabstops (ie., every expr1 char-
     acters).  A new string is returned, which has the same content as the
     original second argument, but with any tab characters expanded into an
     appropriate number of spaces.  The number of spaces resulting from each
     expansion depends upon the position of the specific tab character in its
     enclosing line.  An expansion will always contain at least one space
     character, but may contain up to expr1 space characters.  As well, the
     expansion of tabs occurring earlier in expr2 will influence the expansion
     of tabs occurring later in expr2.

   lines: (line)
     The "lines" intrinsic returns the number of lines on the terminal device
     on which the interpreter is running.  If the interpreter is not running
     on a terminal device, the returned value cannot be predicted.

   cols: (cols)
     The "cols" intrinsic returns the number of columns on the terminal device
     on which the interpreter is running.  If the interpreter is not running
     on a terminal device, then the returned value cannot be predicted.

   exit: (exit)
     The "exit" interpreter accepts one argument, which must evaluate to a
     number, and causes the interpreter to exit with that number as the exit
     value returned to the system.

   complete: (complete expr)
     The "complete" intrinsic performs filename completion.  The function
     accepts one argument which must evaluate to a string and is the partial
     file or directory name to be completed.  The function returns a list of
     one or more strings.  The first element of the list is always the result
     of applying the completion algorithm to the argument, and will be the
     same as the initial argument if the completion algorithm could not add
     more characters to it.  If more than one element is present in the list,
     more characters may have been added to the initial argument, but it still
     did not unambiguously name a file.  The subsequent list elements will be
     preformatted lines of text containing all the possible completions for
     the first element organized into a table the width of the terminal
     device, and may be printed as is.

     > (complete "/usr/share/pe")
     ("/usr/share/perl/man/" "./     ../    man3/  whatis cat3/
                             ")

     A leading ~ in the argument to "complete" will trigger home directory
     abbreviation expansion, similarly to csh.  Home directory abbreviations
     are expanded, but not completed.  For example, if the argument to "com-
     plete" is either "~" or begins with "~/", these characters will be
     replaced with the path to the current user's home directory, but argu-
     ments starting with text matching this pattern: ~[^/]+ will have those
     characters replaced with the path to the specified user's home directory,
     only if such a user exists.  The function will not attempt to complete an
     incomplete home directory abbreviation.

   input: (input expr1 expr2)
     The "input" intrinsic reads data from a process into the active buffer.
     The function accepts two arguments.  The first argument must evaluate to
     a whole number and specifies the line number to insert the new data
     after, while second argument must evaluate to a string specifying the
     command-line to pass to the shell (/bin/sh) to launch the source process,
     and so may be any expression that program understands.  The number of
     lines read is returned on success.  If the child shell cannot find the
     specified program or the process exits prematurely for any reason,
     "input" returns 0.  Any other errors encountered will stop evaluation.

     Whitespace in the filename can either be present literally, or repre-
     sented with the \t and \b escapes the "substitute" and "match" intrinsics
     recognize to represent the tab and the space character, respectively.
     This means if you wish to use a literal \b or \t in the filename, you
     must escape the backslash itself and use \\b or \\t instead.

   output: (output expr1 expr2 expr3)
     The "output" intrinsic writes content from the active buffer to a
     process.  The function accepts three arguments.  The first two arguments
     must evaluate to positive integers and specify the range of lines, inclu-
     sively, to be written to the process.  The first index does not have to
     be less than the second index, but the range of lines so specified will
     be written to the child process in ascending order, regardless of how the
     range was specified.  The third argument must evaluate to a string, and
     specifies the command-line to be passed to the shell to launch the
     process, and so may be any expression that program understands.  The num-
     ber of lines written to the process is returned upon success.  If the
     child shell cannot find the specified program or the process exits prema-
     turely for some other reason, "output" will return 0.  All other errors
     will stop evaluation.

     Whitespace in the filename can either be present literally, or repre-
     sented with the \t and \b escapes the "substitute" and "match" intrinsics
     recognize to represent the tab and the space character, respectively.
     This means if you wish to use a literal \b or \t in the filename, you
     must escape the backslash itself and use \\b or \\t instead.

   system: (system expr1)
     The "system" intrinsic is an interface to the "system" system call.  The
     function accepts one argument which must evaluate to a string, and passes
     it to the shell for execution.  The function returns the exit status of
     the shell; 127 if execution of the shell failed; -1 if fork() or wait-
     pid() fails.

   maxidx: (maxidx)
     The "maxidx" intrinsic accepts on arguments, and returns the highest pos-
     sible index in the buffer that the interpreter will recognize.

   chdir: (chdir expr1)
     The "chdir" intrinsic changes the current directory.  The function
     accepts one argument which must evaluate to a string, specifying the new
     current working directory.  The function returns 1 on success or a string
     describing the error condition on failure.

   table: (table)
     The "table" intrinsic returns a new associative array table, which may be
     used to store lisp objects indexed by atomic keys.  Table objects are
     constants which evaluate to themselves.  See the "hash", "unhash",
     "keys", and "values" intrinsics for the details on using tables.

   hash: (hash expr1 expr2 expr3)
     The "hash" intrinsic is used to store data into a table.  The program
     accepts three arguments, the first of which must evaluate to the table to
     be modified.  The second argument must evaluate to any atom, while the
     third argument can evaluate to an object of any type.  The second argu-
     ment becomes the "key" associated with the third argument "value."  The
     "hash" intrinsic always returns the result of evaluating the third argu-
     ment.  Note that "lookup" returns the empty list if a key has no associa-
     tion, so there is no way to differentiate between a key associated with
     the empty list and a key with no association.

     > (set 't (table))
     <TABLE#0>
     > (hash 'zero "zero")
     "zero"

     If you are going to insert a large number of objects (> 1000000) into a
     table at once, you might consider using "gc_freq" to turn off garbage
     collection before the insertions, and then turn it back on after.

     > (setq t (table))
     <TABLE#1>
     > (for (n 0 999999) (hash t n n))
     999999

   keys: (keys expr1)
     The "keys" intrinsic accepts one argument, which must evaluate to a ta-
     ble, and returns a list of all the objects used as hash keys in in no
     particular order.  If the specified table is empty, the empty list is
     returned.

     > (set 't (table))
     <TABLE#0>
     > (hash t "0" "zero")
     "zero"
     > (hash t "1" "one")
     "one"
     > (keys t)
     ("1" "0")

   values: (values expr1)
     The "values" intrinsic accepts one argument, which must evaluate to a ta-
     ble, and returns a list of all of the values stored in the table object
     in no particular order.  If the specified table is empty, the empty list
     is returned.

     > (set 't (table))
     <TABLE#0>
     > (hash t "0" "zero")
     "zero"
     > (hash t "1" "one")
     "one"
     > (hash t "2" "two")
     "two"
     > (values t)
     ("two" "zero" "one")

   unhash: (unhash expr1 expr2)
     The "unhash" intrinsic removes a key/value pair from a table.  It accepts
     two arguments, the first of which must evaluate to the table to be modi-
     fied, while the second of which must evaluate to the key of the key/value
     pair to be removed.  The "unhash" intrinsic always returns the result of
     evaluating the second argument.

     > (set 't (table))
     <TABLE#0>
     > (hash t "0" "zero")
     "zero"
     > (unhash t "0")
     0
     > (keys t)
     ()

   lookup: (lookup expr1 expr2)
     The "lookup" intrinsic is used to retrieve an object associated with an
     atom in a table.  The function accepts two arguments.  The first argument
     must evaluate to the table to be searched, while the second argument must
     evaluate to an atom.  If another lisp object is associated with the sec-
     ond argument in the specified table, the associated object is returned,
     otherwise the empty list is returned.  Note that there is no way to tell
     the difference between a key with no association and a key associated
     with the empty list.

     > (set 't (table))
     <TABLE#0>
     > (hash t "1" "one")
     "one"
     > (hash t "0" "zero")
     "zero"
     > (lookup t "1")
     "one"
     > (lookup t "0")
     "zero"
     > (lookup t "2")
     ()

   sqlite_open: (sqlite_open expr)
     The "sqlite_open" intrinsic opens a SQLite database file.  The function
     accepts one argument which must evaluate to a string specifying the file-
     name for the database.  It will be created if it does not exist.  The
     opened database object is returned upon success.  Upon failure, a string
     describing the error encountered is returned.  Database objects are con-
     stants which evaluate to themselves.

   sqlite_close: (sqlite_close expr)
     The "sqlite_close" intrinsic closes an open SQLite database file.  The
     function accepts one argument which must evaluate to the opened database
     object to close.  If the database is currently open the function closes
     it and returns 1, otherwise, it returns 0.

   sqlite_exec: (sqlite_exec expr1 expr2)
     The "sqlite_exec" function executes SQL commands on an opened SQLite
     database file.  The function accepts two arguments, the first of which
     must evaluate to the opened database object to query, and the second of
     which must evaluate to a string specifying the SQL command to execute.
     If the command is successfully executed, a list is returned.  If the com-
     mand would not normally return any data, or the command returns the empty
     set, an empty list is returned; otherwise, a list of lists is returned.
     The first sublist will contain the column keys, while each subsequent
     sublist will contain one row of returned table data.  If a null entry in
     a row is encounted, an empty string will be returned for that field in
     its associated list.  If an error is encountered during execution of the
     SQL query, a string is returned describing the error.

     Data returned by the SQLite interface is expressed as strings.  Numbers
     are returned as the string representation of the appropriate value, and
     may be converted back to a number with the "digitize" intrinsic.

     "sqlite_exec" provides the simplest interface to the SQLite library, but
     another row-by-row interface is provided, which may be more convenient
     when working with rows containing large chunks of data, and which is also
     more efficient when the user wishes to invoke the a SQL statement multi-
     ple times on the same database.  The row-oriented interface is provided
     by the "sqlite_prepare", "sqlite_bind", "sqlite_step", "sqlite_row",
     "sqlite_reset", and "sqlite_finalize" intrinsics, detailed below.  See
     http://www.sqlite.org for further details.

   sqlite_prepare: (sqlite_prepare db sql)
     The "sqlite_prepare" intrinsic is used to compile a SQL statement for
     multiple uses with the alternative SQLite interface.  The function
     accepts two arguments, the first of which must evaluate to an opened
     SQLite database object, while the second must evaluate to a string con-
     taining the SQL to be compiled against that database.  The function
     returns a compiled SQL object upon success, or a string describing an
     error condition, upon failure.  The compiled sql object is an opaque con-
     stant atom and may be passed as argument to "sqlite_bind", "sqlite_step",
     "sqlite_row", "sqlite_reset", or "sqlite_finalize".

     The SQL statement passed to this function may contain parameters of the
     form ?, ?NNN, or :AAA, where NNN is a number and AAA is an alphanumeric
     identifier.  By using "sqlite_bind" values may be inserted in place of
     these parameters.  This is documented in the entry for "sqlite_bind".

     > (setq db (sqlite_open "document.db"))
     <db#1>
     > (setq sql (sqlite_prepare "SELECT path FROM document WHERE parent = 0"))
     <sql#1>

   sqlite_bind: (sqlite_bind sql index text)
     Statements given to "sqlite_prepare" may contain parameter references in
     place of SQL literals, of the forms ?, ?NNN, or :AAA where NNN is a num-
     ber, and AAA is an alphanumeric identifier.  The "sqlite_bind" intrinsic
     is used to set or change the values bound to these parameters.  Unfortu-
     nately, only SQL literal values may be parameterized, that is strings and
     numbers, and not column or table names.  The function accepts three argu-
     ments.  The first argument must evaluate to a compiled SQL statement
     returned by "sqlite_prepare".  The second argument must evaluate to the
     index position of the parameter to be substituted.  Parameter indices
     start at 1.  The third argument must evaluate to a string containing the
     replacement text.  Upon success, the function returns 1.  Otherwise a
     string will be returned describing an error condition.

     Parameters are specified by their ordinal position in the SQL query.
     Note that parameters with the same name all share the same index value,
     that value being the index of the first occurrence of the parameter name
     in the SQL statement.  Using named parameters, the same value may be sub-
     stituted into a SQL statement in different locations.

     Note that "sqlite_bind" must be invoked on a SQL statement after a call
     to "sqlite_prepare" or "sqlite_reset", and before any call to
     "sqlite_step".

     > (setq db (sqlite_open "example.db"))
     <DB#1>
     > (setq sql (sqlite_prepare db "SELECT name FROM employees WHERE job = ?"))
     <SQL#1>
     > (sqlite_bind sql 1 "supervisor")
     1

     > (for (((setq more (sqlite_step sql)))
             (more)
             ((setq more (sqlite_step sql))))
     >> (print (sqlite_row sql))
     >> (newline))

     ("Bob")

     > (sqlite_reset sql)
     1
     > (sqlite_bind sql 1 "technician")
     1

     > (for (((setq more (sqlite_step sql)))
             (more)
             ((setq more (sqlite_step sql))))
     >> (print (sqlite_row))
     >> (newline)

     ("Sally")
     ("Jeffrey")
     ("Boodles the cat")
     ("George")

   sqlite_step: (sqlite_step sql)
     The "sqlite_step" intrinsic is used to apply a compiled SQL object to its
     database to generate the returned data for a single row of the result
     set.  The function accepts one argument which must evaluate to a compiled
     SQL object generated by "sqlite_prepare", and returns 1 if a row of data
     has been generated, or 0 if the data in the result set has been
     exhausted, or a string describing an error condition, upon failure.  If
     the function returns 1, then "sqlite_row" may be invoked on the compiled
     SQL object to retrieve the generated data for the current row.  Further
     invocations of "sqlite_step" will generate data for successive rows of
     the result set, until the result set has been exhausted.

   sqlite_row: (sqlite_row sql)
     The "sqlite_row" intrinsic may be called after a successful invocation of
     "sqlite_step" to retrieve a row of data from the result set of a SQL
     query.  The function accepts one argument, which must evaluate to a com-
     piled SQL object returned by "sqlite_prepare" which has had "sqlite_step"
     invoked on it, and returns a list of strings upon success.  Each string
     represents the data for a single column in the current row of the result
     set.  Upon failure, the function returns a string describing an error
     condition.

     > (setq db (sqlite_open "document.db"))
     <db#1>
     > (setq sql (sqlite_prepare "SELECT * FROM table1"))
     <sql#1>
     > (for (((setq more (sqlite_step sql))) (more) ((setq more (sqlite_step sql))))
     >> (print (sqlite_row sql))
     >> (newline))
     ("first column first row" "second_column first row")
     ("first column second row" "second_column second row")

   sqlite_reset: (sqlite_reset sql)
     The "sqlite_reset" intrinsic is used to reset a compiled SQL object after
     "sqlite_step" has returned 0 when invoked on it.  The function accepts
     one argument, which must evaluate to a compiled SQL object.  The function
     returns 1 upon success, or a string describing an error condition, upon
     failure.  After a successful invocation of "sqlite_reset", "sqlite_step"
     and "sqlite_row" may be invoked on the compiled SQL object to re-generate
     the previous result set again.

   sqlite_finalize: (sqlite_finalize sql)
     The "sqlite_finalize" intrinsic frees the resources associated with a
     compiled SQL object.  The function accepts one argument, which must eval-
     uate to a compiled SQL object generated by "sqlite_prepare" and returns 1
     upon success, or a string describing an error condition, upon failure.
     "sqlite_finalize" MUST BE CALLED ON EVERY COMPILED SQL OBJECT ASSOCIATED
     WITH A PARTICULAR DATABASE, BEFORE THAT DATABASE MAY BE CLOSED BY
     "sqlite_close".  Failure to do this may cause incomplete updates to be
     rolled back and transactions to be canceled.  The garbage collector will
     call "sqlite_finalize" on any compiled SQL objects it deallocates, but
     implicit deallocation should not be relied upon, as there is no guarantee
     the database object will not be garbage collected before the SQL state-
     ments, which may result in corruption of the database.

   sqlp: (sqlp expr)
     The "sqlp" intrinsic accepts one argument, which may evaluate to any type
     of object, and returns 1 if that object is a compiled SQL object gener-
     ated by "sqlite_prepare".  Otherwise, it returns 0.

   stack: (stack [expr])
     The "stack" intrinsic creates a new stack object.  The function accepts
     one optional argument, which, if present, must evaluate to a positive
     integer specifying a number of elements to preallocate on the stack.
     Each element will be set to the empty list.  Omitting the optional argu-
     ment is the same as invoking (stack 0).  The newly-created stack object
     is returned.

     > (set 's (stack))
     <STACK1>
     > (used s)
     0
     > (set 's (stack 10))
     <STACK2>
     > (used s)
     10

   push: (push expr1 expr2)
     The "push" intrinsic pushes an object onto the top of a stack.  The func-
     tion accepts two arguments, the first of which must evaluate to the stack
     to be affected, while the second argument may be any lisp object.  The
     function returns the result of evaluating the second argument.

     > (set 's (stack))
     <STACK1>
     > (push s 'foo)
     foo
     > (index s 0)
     foo

   pop: (pop expr)
     The "pop" intrinsic removes an object from the top of a stack.  The func-
     tion accepts one argument, which must evaluate to the stack to be
     affected.  The removed object is returned.  When the stack is empty, the
     empty list is returned.  Note the only way to tell the difference between
     an empty stack and one which has the empty list stored in its top ele-
     ment, is to invoke the "used" intrinsic.

     > (set 's (stack))
     <STACK1>
     > (push s 'foo)
     foo
     > (push s 'bar)
     bar
     > (pop s)
     bar
     > (pop s)
     foo
     > (pop s)
     ()
     > (used s)
     0

   unshift: (unshift expr1 expr2)
     The "unshift" intrinsic adds a new element onto the bottom of a stack.
     The function accepts two arguments, the first of which must evaluate to a
     stack, while the second may evaluate to any lisp object.  The result of
     evaluating the second argument is prepended to the stack, and also
     returned by the function.

     > (set 's (assign (stack) '(1 2 3 4)))
     <STACK1>
     > (flatten s)
     (1 2 3 4)
     > (unshift s 0)
     0
     > (flatten s)
     (0 1 2 3 4)

   shift: (shift expr)
     The "shift" library function removes an element from the bottom of a
     stack.  The function accepts on argument which must evaluate to stack.
     If the stack is empty, the empty list is returned, otherwise the removed
     element is returned.

     > (set 's (assign (stack) '(0 1 2 3 4)))
     <STACK1>
     > (flatten s)
     (0 1 2 3 4)
     > (shift s)
     0
     > (shift s)
     1
     > (flatten s)
     (2 3 4)

   index: (index expr1 expr2)]
     The "index" intrinsic fetches the object stored at a specified index in a
     stack.  The function accepts two arguments, the first of which must eval-
     uate to the stack to be accessed, while the second must evaluate to a
     whole number specifying the desired element on the stack.  The bottom
     location on a stack has an index value of zero, and the index value of
     the object on the top of the stack is one less than the number of ele-
     ments on the stack.  Specifying an index value of less than zero, or more
     than the index of the last element on the stack, generates an error which
     stops evaluation.

     > (set 's (assign (stack) '(a b c)))
     <STACK1>
     > (index s 0)
     a
     > (index s 2)
     c
     > (index s 3)
     <INDEX>: index 3 out of range.
     >

   topidx: (topidx expr)
     The "topidx" intrinsic accepts one argument which must evaluate to a
     stack, and returns the index value of the top element on the stack, or -1
     if the stack is empty.

     > (topidx (stack 1))
     0

   used: (used expr)
     The "used" intrinsic obtains the number of elements currently on a speci-
     fied stack.  The function accepts one argument which must evaluate to the
     stack to be queried, and returns a whole number describing the number of
     elements currently on that stack.

     > (used (stack 10))
     10

   store: (store expr1 expr2 expr3)
     The "store" intrinsic stores an object into a specified element of a
     stack.  The function accepts three arguments, the first of which must
     evaluate to the stack to be affected, while the second argument must
     evaluate to a whole number specifying the element of the stack to over-
     write, and the third argument may evaluate to any lisp object.  The
     result of evaluating the third argument is stored in the specified index
     of the specified stack, and the result of evaluating the third argument
     is returned.  Specifying an index value of less than zero, or more than
     the index of the last element on the stack, generates an error which
     stops evaluation.

     > (set 's (stack 3))
     <STACK1>
     > (store s 0 'foo)
     foo
     > (store s 1 'bar)
     bar
     > (store s 2 'wumpus)
     wumpus
     > (flatten s)
     (foo bar wumpus)
     > (store s 3 'error)
     <STORE>: index 3 out of range.
     >

   clear: (clear expr1 expr2)
     The "clear" intrinsic allows the user to remove and discard multiple ele-
     ments from the top of a specified stack.  The function accepts two argu-
     ments, the first of which must evaluate to a stack object, while the sec-
     ond must evaluate to a whole number.  The second argument specifies the
     number of arguments to remove from the top of the stack.  "clear" dis-
     cards the removed elements and always returns 1.

     > (setq s (assign (stack) '(1 2 3 4 5)))
     <STACK#1>
     > (clear s 4)
     1
     > (flatten s)
     (1)
     > (assign s '(1 2 3 4 5))
     <STACK#1>
     > (clear s (used s))
     1
     > (flatten s)
     ()

   assign: (assign expr1 expr2)
     The "assign" library function allows the user to store all the elements
     of a list into a stack at once, starting at index zero.  The previous
     contents of each affected element are overwritten.  If the number of ele-
     ments on the stack is too small to hold all the objects in the list, the
     function pushes new elements onto the stack until it can hold the entire
     list, before performing the assignments.  If the number of elements on
     the stack is greater than the number of items in the list, those elements
     on the stack starting at the index value equal to the length of the list,
     and continuing to the top of stack, inclusive, remain unaffected.  The
     function returns the stack object affected.

     > (set 's (assign (stack) '(a b c d e)))
     <STACK1>
     > (used s)
     5

   flatten: (flatten expr)
     The "flatten" library function returns the elements of a stack in ascend-
     ing order, as a list.  The function accepts one argument which must eval-
     uate to the stack to be queried.

     > (flatten (assign (stack) '(a b c d e)))
     (a b c d e)

   child_open: (child_open expr [expr])
     The "child_open" intrinsic opens a full-duplex connection to another
     process which may be communicated with by the "child_read" and
     "child_write" intrinsics.  Only one child process may be running at any
     one time.  The function accepts one or two arguments.

     With the one-argument form, the lone argument must evaluate to a string
     specifying a command line to pass to the shell (/bin/sh) to run.  The
     function will return 1 if the child can be created, otherwise it will
     return a string describing an error condition.  If the child process can-
     not find the specified program, or is not able to run it, it will exit
     and print an error to stderr.  The user may check for a successful launch
     of the specified program by invoking "child_running" after invoking
     "child_open".

     The two-argument form of the function is used to communicate with another
     process, local or remote, over a TCP socket, or a local process over a
     UNIX domain socket.  To open a local or remote TCP connection, the first
     argument must evaluate to a string specifying the local or remote host-
     name or IP address.  For UNIX domain connections the first argument must
     evaluate to a string representing the pathname in the filesystem to a
     UNIX domain socket.  For TCP connections, the second argument must evalu-
     ate to either a string specifying a service defined in /etc/services,
     such as "http", or a fixnum specifying a port number to attempt to con-
     nect to.  For UNIX domain connections, the second argument must be 0.

     If the interpreter successfully opens a connection to the specified
     entity, then it returns 1, otherwise it will return a string describing
     an error condition.

   child_running: (child_running)
     The "child_running" intrinsic accepts no arguments, and returns 1 if an
     child process is running; otherwise, the function returns 0.

   child_ready: (child_ready)
     The "child_ready" intrinsic accepts no arguments, and returns 1 if data
     is waiting to be read from a child process; otherwise the function
     returns 0.  If a child process has not been started with the "child_open"
     intrinsic, 0 is returned as well.

   child_wait: (child_wait)
     The "child_wait" intrinsic accepts no arguments and blocks until data is
     ready from a child process for "child_read" to consume, when it returns
     1, or if no child process is running, it will immediately return 0.

   child_close: (child_close)
     The "child_close" intrinsic terminates a child process launched by
     "child_open".  The function accepts no arguments, and always returns 1.
     If there is no child process running, the function does nothing.

   child_eof: (child_eof)
     The "child_eof" intrinsic closes the writable half of the connection to
     child process opened with "child_open".  The function accepts no argu-
     ments and returns 1 upon success.  The child process will read EOF on its
     next read from its standard input.  This can be useful when working with
     programs which buffer data.  Any subsequent attempt to write to the child
     with "child_write" will generate an error which will stop evaluation.
     Note that a connection which has had its writable half closed with
     "child_eof" still needs to be fully-closed by invoking "child_close" on
     it, when one is finished with the child.

     For an example of the use of this intrinsic, consider a situation where
     one is sending lines of text to the fmt utility.  This program will
     buffer input text until it has enough to print a full line of output,
     unless it encounters a blank line or EOF, when any buffered text will be
     output to form a short line.  In the situation where one has sent data to
     the utility, and it has formatted all the data except for the tail end
     which is not long enough to form a complete line, the program will block
     forever until it reads more data or EOF from stdin.  By invoking
     "child_eof" we can cause fmt to read EOF on stdin and print the last of
     its buffered output.  If we invoked "child_close" we would close both
     halves of the full-duplex connection, and so be unable to read that last
     short line of data back from the child.

   child_write: (child_write expr1 ...)
     The "child_write" intrinsic writes a list of strings to a child process
     launched by "child_open".  The function accepts one or more arguments,
     which must all evaluate to strings, and writes them to the child process.
     The "child_write" function returns 1 on success.  Any errors encountered
     will stop evaluation.

     > (child_open "/usr/local/bin/munger")
     1
     > (for (a 1 10)
     >> (child_write a (char 10)))
     1 ; this is the return value of the "child_write"
     >> (print (child_read)))
     1
     2
     3
     4
     5
     6
     7
     8
     9
     10

   child_read: (child_read)
     The "child_read" intrinsic reads up to 1024 characters of data emitted by
     a child process, and returns it as a string.  The function accepts no
     arguments.  If "child_read" is invoked when no child process is running,
     an error will be generated which will stop evaluation.  If no data can be
     read after 30 seconds, "child_read" will return the empty string.  Zero
     is returned if EOF is read from the child process.

     > (child_open "munger")
     1
     > (child_write "(set 'foo 'bar)" (char 10))
     1
     > (child_read)
     "bar
     "
     1

   clearscreen: (clearscreen)
     The "clearscreen" intrinsic accepts no arguments, and if stdout is con-
     nected to a terminal device, clears the screen.  1 is returned on suc-
     cess.  Any error encountered will stop evaluation.

   clearline: (clearline expr1 expr2)
     The "clearline" intrinsic accepts two arguments, both of which must eval-
     uate to whole numbers.  If stdout is connected to a cursor-addressable
     terminal device, it will clear the line specified by the first argument,
     starting at the column specified by the second argument, to the end of
     the line.  The coordinates for screen lines and columns start at 0.  The
     position 0,0 is the top leftmost position on the screen.  The maximum
     values for the terminal device can be ascertained with the "lines" and
     "cols" intrinsics.  1 is returned on success.  Any error encountered will
     stop the interpreter.

   goto: (goto expr1 expr2)
     The "goto" intrinsic accepts two arguments, both of which must evaluate
     to whole numbers.  If stdout is connected to a cursor-addressable termi-
     nal device, the function places the cursor at the specified screen coor-
     dinates.  The coordinates for screen lines and columns start at 0.  The
     position 0,0 is the top leftmost position on the screen.  The maximum
     values for the terminal device can be ascertained with the "lines" and
     "cols" intrinsics.  1 is returned on success.  Any error encountered will
     stop the interpreter.

   getchar: (getchar)
     The "getchar" intrinsic accepts no arguments.  It does a blocking read on
     stdin until a character can be read, when it returns a whole number in
     the range of 0-255, representing the character code of the input charac-
     ter.  If stdin is a terminal device, it will be taken out of canonical
     mode, so that unbuffered, uninterpreted data may be read.

     If EOF is encountered, "getchar" returns -1.  If a SIGWINCH is received
     by the interpreter while waiting for data, the function returns -2 imme-
     diately.  Any other error encountered will cause the function to return a
     string describing the error.  The getchar intrinsic "getchar" is intended
     for use in creating interfaces which use character-I/O.  If you just want
     to read a character from stdin, and stdin is redirected onto a file, use
     (getchars 1) instead.

   pushback: (pushback expr1)
     The "pushback" intrinsic accepts one argument which must evaluate to a
     whole number in the range 0-255.  It causes the next subsequent invoca-
     tion of "getchar" to return the number pushed back.  After returning this
     value, subsequent invocations of "getchar" will read from the terminal
     again.  1 is returned on success.  Any error encountered stop evaluation.
     Note that "pushback" does not work with "getchars", only "getchar".

   display: (display expr1 expr2 expr3)
     The "display" intrinsic aids the implementation of interactive buffer
     inspection tools.  The function accepts three arguments, all of which
     must evaluate to whole numbers.  If stdout is connected to a cursor-
     addressable terminal device, the function will print buffer lines, one
     per screenline, starting with the buffer line whose index value corre-
     sponds to the first argument, and continuing with subsequent buffer
     lines, until it has printed one less many buffer lines as there are
     screen lines, or until it runs out of buffer lines, if there are not
     enough.  If it runs out of lines, the function will print single tilde
     characters on each of the remaining screenlines, except for the last.  If
     the first argument is zero, "display" prints a full screen of tildes, and
     returns.

     The second argument specifies a buffer column to start printing with.  If
     non-zero, only the portions of the lines from the specified column onward
     will be printed.  Note the second argument does not specify a screen col-
     umn, but a buffer column, and that tab expansion is performed before the
     slice is taken, according to the value of the third argument, discussed
     below.  Lines will always be printed starting at screen column 0.  Lines
     longer than the terminal width are truncated to the terminal width.

     The third argument specifies the tabstop periodicity.  A value of 4, for
     example, indicates that tabs occur every 4 characters in a line.  Any
     tabs found in the specified lines will be expanded according to this
     value before truncation and printing.  For the details of tab expansion,
     see the description of the "expand" intrinsic, elsewhere in this docu-
     ment.

     1 is returned on success.  Any errors encountered stop evaluation.

   boldface: (boldface)
     The "boldface" intrinsic turns on boldface mode of the terminal connected
     to stdout.  The function accepts no arguments, and always returns 1.

   normal: (normal)
     The "normal" intrinsic turns off boldface mode and resets the colors of
     the terminal connected to stdout to their default values.  The function
     accepts no arguments and always returns 1.

   fg_black:
   fg_red:
   fg_green:
   fg_yellow:
   fg_blue:
   fg_magenta:
   fg_cyan:
   fg_white:
   bg_black:
   bg_red:
   bg_green:
   bg_yellow:
   bg_blue:
   bg_magenta:
   bg_cyan:
   bg_white:
     These sixteen functions set the foreground or background color of the
     terminal connected to stdout to the specified color.  These functions
     accept no arguments and always return 1.

   hide: (hide)
     The "hide" intrinsic accepts no arguments, and if stdout is connected to
     a terminal device capable of having its cursor made invisible, the func-
     tion hides the cursor.

   show: (show)
     The "show" intrinsic accepts no arguments, and if stdout is connected to
     a terminal device capable of having its cursor made invisible, the func-
     tion shows the cursor.

   pause: (pause expr1)
     The "pause" intrinsic accepts one argument which must evaluate to a whole
     number no larger than 999999, specifying a number of microseconds for the
     interpreter to sleep.  The interpreter returns when data is waiting on
     stdin or when the time value has expired.  See the "sleep" intrinsic if
     you need to sleep for longer periods.  "sleep" is also much less proces-
     sor intensive.

   scrollup: (scrollup)
     If the device connected to stdin is cursor-addressable, the "scrollup"
     intrinsic scrolls the screen lines upward by one line.  The line at the
     top of the screen is lost, while the line at the bottom of the screen
     becomes blank.

   scrolldn: (scrolldn)
     If the device connected to stdin is cursor-addressable, the "scrolldn"
     intrinsic scrolls the screen lines downward by one line.  The last line
     is lost, while the first line becomes blank.

   insertln: (insertln)
     If the device connected to stdin in cursor-addressable, the "insertln"
     intrinsic scrolls the lines on the screen from the line the cursor is on,
     to the last line on the screen, inclusive, downward by one line. The line
     the cursor is on is cleared, while the last line on the screen is lost.

   printer: (printer)
     The "printer" intrinsic turns on the lisp printer, if it has been turned
     off with an invocation of the "noprinter" intrinsic.  The result of eval-
     uating an expression at toplevel is discarded unless the printer is
     turned on.  The printer is turned on by default.

   noprinter: (noprinter)
     The "noprinter" intrinsic turns off the lisp printer, if it is turned on.
     The result of evaluating an expression at toplevel is discarded unless
     the printer is turned on.  The printer is turned on by default.

   shexec: (shexec expr)
     The "shexec" intrinsic overlays a new process overtop of the interpreter
     process, similarly to how the command of the same name works in the
     shell.  The function accepts one argument which must evaluate to a
     string, and attempts to use the execv() system call to run the shell
     (/bin/sh -c) with the command-line specified in the argument string.
     Upon success, the Munger interpreter process is abandoned, and the shell
     process starts running with the same process id.  It "replaces" the
     interpreter.  This is useful when a script is finished its work and
     wishes to run another program to do some further processing.  If the new
     process image cannot be exec-ed, then the function returns a string
     describing the error.

   exec: (exec expr ...)
     The "exec" intrinsic behaves similarly to the "shexec" intrinsic.  It
     overlays a new process image overtop of the interpreter process.  The
     function accepts one or more arguments, which must all evaluate to
     strings, and interprets them as a command followed by its command-line
     arguments.  It DOES NOT pass its arguments to the shell for interpreta-
     tion.  Upon success, the Munger interpreter process is abandoned, and the
     new process starts running with the same process id.  It "replaces" the
     interpreter.  This is useful when a script is finished its work and
     wishes to run another program to do some further processing.  If the new
     process image cannot be exec-ed, then the function returns a string
     describing the error.

   truncate: (truncate expr)
     The "truncate" intrinsic alters the length of a file connected to the
     standard output of the interpreter.  The function accepts one argument
     which must evaluate to a an integer specifying the new length of the
     file.  If the specified length is greater than the length of the file,
     the file will be extended and the extended portion filled with zeros.
     The function returns 1 on success, or if an error is encountered, a
     string describing the error.

     > (with_output_file_appending "HOW_TO_EXTEND_IT"
     >> (when (writelock)
     >>> (truncate 100)))
     1
     > (with_input_file "HOW_TO_EXTEND_IT"
     >> (setq line (getchars 1000)))
     "ADDING INTRINSICS TO THE INTERPRETER
     ------------------------------------

     Under the hood, Munger is"
     > (length line)
     100

   dynamic_let: (dynamic_let (symbol expr) expr1 [expr2...])
     Intrinsic "dynamic_let" allows the creation of bindings with dynamic
     scope, which is to say, such a binding is globally visible for the time
     the dynamic_let is executing.  A dynamically-scoped variable in Munger is
     a global which will cease to exist when the "dynamic-let" exits, or if a
     global of the same name existed previously, revert to its former value.
     The bindings created by "dynamic_let" cannot be captured by closures.  A
     lexical binding of the same name as a dynamic binding will shadow the
     dynamic binding.  This means a binding in an exterior "let" expression
     can shadow the binding in an interior "dynamic_let".  The intrinsic
     accepts two or more arguments, the first of which is not evaluated and
     must be a two-element list consisting of a symbol followed by any expres-
     sion.  The expression will be evaluated in the current scope and the
     result bound to the symbol for the duration of the "dynamic_let".  The
     remaining arguments are then evaluated, in order, with the new binding in
     effect.  When the expression terminates the dynamic binding is removed.
     The value of the last expression evaluated is returned by "dynamic_let".

     The purpose of "dynamic_let" is to allow one to make temporary changes to
     global variables without having to save the previous value and restore it
     afterwards.  By definition, a global is a variable one wishes to be glob-
     ally visible.  One would only knowingly mask it with a local binding if
     one wished to have some local code find a different value bound to the
     same symbol.  A "let" is sufficient for this purpose, but if one wishes
     to have other functions which the local code may invoke to also see the
     changed value, then "dynamic_let" must be used.

     > (defun f () a)
     <CLOSURE#57>

     > (dynamic_let (a 10)
     >> (f))
     10

     > (f)
     evaluate: symbol a not bound.
     f: error evaluating body expression 1.

     > (defun a (x) 'foobar)
     <CLOSURE#58>

     > (defun g (x) (a x))
     <CLOSURE#59>

     > (dynamic_let (a (lambda (x) x))
     >> (g 23))
     23

     > (g 23)
     foobar

     > (dynamic_let (a 10)
     >> (defun h () a))
     <CLOSURE#60>
     > (h)
     evaluate: symbol a not bound.
     h: error evaluating body expression 1.

     ; Exterior "let" is shadowing interior "dynamic_let":

     > (let ((a 12))
     >> (dynamic_let (a 10)
     >>> (print a)
     >>> (newline)))
     12
     1 ; return value of "newline"

   basename: (basename expr)
     The "basename" intrinsic returns just the filename portion of a specified
     path.  The function accepts one argument which must evaluate to a string
     and returns a string.  If the argument string does not have a filename
     component, "basename" returns the empty string.  NOTE, the path specified
     by the argument string does not have to exist in the filesystem.  This is
     a string manipulation function only.

   dirname: (dirname expr)
     The "dirname" intrinsic returns just the directory portion of a specified
     path.  The function accepts one argument which must evaluate to a string
     and returns a string.  If the argument does not have a directory compo-
     nent "." is returned.  NOTE, the path specified by the argument string
     does not have to exists in the filesystem.  This is a string manipulation
     function only.

   chmod: (chmod expr1 expr2)
     The "chmod" intrinsic may be used to change the permissions associated
     with a specified file.  The function accepts two arguments, both of which
     must evaluate to strings.  The first argument must be a new mode specifi-
     cation of the form accepted by chmod(1), in either symbolic or octal
     form.  The second argument must evaluate to the filename of the file to
     be affected.  "chmod" returns 1 on success; otherwise it returns a string
     describing an error condition.

   chown: (chown expr1 expr2 expr3)
     The "chown" intrinsic may be used to change the owner (if the euid of the
     interpreter is the superuser's), and/or the group associated with a spec-
     ified file.  The function accepts three arguments, which all must evalu-
     ate to strings.  The first argument must be the name of the new owner, or
     the empty string if the owner is not to be changed.  The second argument
     must be name of the new group, or the empty string if the group is not to
     be changed.  The third argument must be the filename of the file to be
     affected.  "chown" returns 1 upon success; otherwise, it returns a string
     describing an error condition.  Only the superuser may change the owner-
     ship of files.

   crypt: (crypt expr)
     The "crypt" intrinsic is a frontend to the crypt(3) library function.  It
     accepts one argument which must evaluate to a string and encrypts it
     using the default scheme used to encrypt passwords in the user database.
     The encrypted string is returned.  Any error encountered by crypt(3) will
     stop evaluation.

   checkpass: (checkpass expr1 expr2)
     The "checkpass" intrinsic verifies a user and password pair are correct
     for the system on which it is running.  The function accepts two argu-
     ments which must both evaluate to strings, the first of which specifies
     the user name, and the second of which specifies the password of that
     user.  The function will always return 0 unless the euid of the inter-
     preter is 0 (the superuser), when it will return 1 if the user name and
     password are correct, or 0, if they are not.

   setuid: (setuid expr)
     The "setuid" intrinsic is used to change the uid and euid of the inter-
     preter process.  It accepts one argument which must evaluate to a string
     specifying the user to change to.  The function will return a string
     describing an error condition, unless the euid of the interpreter is 0
     (the superuser) and the requested user exists, when it will change to the
     specified user and return 1.  It is not possible to switch back to the
     superuser after invoking "setuid" to become a non-privileged user.

   seteuid: (seteuid expr)
     The "seteuid" intrinsic is used to change the euid of the interpreter
     process if it is running set-user-id.  It accepts one argument which must
     evaluate to a string specifying the user to change to, and returns 1 upon
     success or a string describing an error condition upon failure.  The euid
     may be switched between the real uid and the set-user-id, of a set-user-
     id interpreter.  If the interpreter is not running setuid, then the uid,
     the euid, and the saved set-user-id will all be the same and therefore it
     will not be possible to change the euid.

   getuid: (getuid)
     The "getuid" intrinsic accepts no arguments and returns a two element
     list consisting of the name of the real user the interpreter is running
     as, followed by the numerical uid of that user.  If an unforeseen error
     occurs which prevents the interpreter from determining its own uid, the
     function returns the empty list.

   setgid: (setgid expr)
     The "setgid" intrinsic is used to change the gid of the interpreter
     process.  It accepts one argument which must evaluate to a string speci-
     fying the group to change to.  The function returns 1 upon success, or a
     string describing an error condition upon failure.

   setegid: (setgid expr)
     The "setegid" intrinsic is used to change the effective gid of the inter-
     preter process.  It accepts one argument which must evaluate to a string
     specifying the group to change to.  The function returns 1 upon success,
     or a string describing an error condition upon failure.  The egid may be
     switched between the real gid and the saved set-group-id, of a set-group-
     id interpreter.  If the interpreter is not running set-group-id, the both
     the saved set-group-id and the real gid will be the same.

   geteuid: (geteuid)
     The "geteuid" intrinsic accepts no arguments and returns a two element
     list consisting of the name of the effective user the interpreter is run-
     ning as, followed by the numerical uid of that user.  If an unforeseen
     error occurs which prevents the interpreter from determining its own
     euid, the function returns the empty list.

   getgid: (getgid)
     The "getgid" intrinsic accepts no arguments, and returns a two element
     list consisting of the name of the primary group of the user the inter-
     preter is running as, followed by the numerical gid of that group.  If an
     unforeseen error occurs which prevents the interpreter from determining
     its gid, then the function returns the empty list.

   seek: (seek expr1 expr2 expr3)
     The "seek" intrinsic is used to move the file pointer of a file connected
     to one of the standard descriptors.  The function accepts three argu-
     ments, the first of which must evaluate to 0, 1, or 2, and specifies
     whether the seek operation should affect the file pointer of stdin, std-
     out, or stderr, respectively.  The second argument must evaluate to a
     integer specifying the number of characters by which the file pointer
     should be adjusted, and the third argument must evaluate to one of the
     following three strings: "SEEK_SET", "SEEK_CUR", or "SEEK_END", and spec-
     ifies the position which the adjustment is relative to.  "SEEK_SET" indi-
     cates the seek operation should seek from the beginning of the file.
     "SEEK_CUR" indicates the seek operation should seek from the current
     position of the file pointer.  "SEEK_END" indicates the seek operation
     should seek from the end of the file.  Upon success the function returns
     the number of characters from the beginning of the file corresponding to
     the new location of the file pointer.  Further reads or writes to the
     stream will happen relative to the new position of the file pointer.  Any
     errors encountered will stop evaluation.  Seeking past the end of a file
     connected to stdout will cause the file to be automatically extended,
     with the new portion filled with zeroes.

     NOTE: calling "getline" on stdin will cause subsequent invocations of
     "seek" to return unexpected values, as "getline" does its own buffering.
     If the user wishes to intersperse the reading of data from stdin and
     calls to "seek" on stdin, the "getchars" intrinsic must be used to per-
     form the read operations.

   getchars: (getchars expr [expr])
     The "getchars" intrinsic is used to read a specific number of characters
     from the stream connected to stdin.  It accepts one or two arguments
     which both must evaluate to fixnums.  The first must evaluate to a whole
     number specifying the number of characters to read, while the second, if
     present, must evaluate to a positive value specifying a number of seconds
     after which a timeout will occur.  Upon success, the characters read are
     returned as a string.  Any errors encountered will stop evaluation.  If
     "getchars" encounters EOF while reading, or a timeout occurs, less than
     the desired amount of characters may be returned.  If EOF was encoun-
     tered, any successive invocation of the "getchars" will return fixnum 0.
     Note that invoking "getchars" with a first argument of 0, always causes
     it to immediately return the empty string without even attempting to read
     from stdin.

     Mixing calls to "getline" and "getchars" will result in unexpected
     results, as "getline" performs its own input buffering.  You MAY mix
     calls to "getchars" with calls to "getline_ub", however.

     The presence of a timeout value causes "getchars" to operate as follows.
     The function calls the read() system call until it has either read the
     desired number of characters, or it encounters EOF on the input stream.
     This is useful when stdin is connected to a socket.  If any invocation of
     read() takes longer than the number of seconds specified by the timeout
     value, it will be interrupted, and "getchars" will return all the charac-
     ters read so far.  If no characters have been read, then "getchars" will
     return the empty string.  This is the only other circumstance in which it
     will return the empty string.  When invoked without a timeout value, but
     with a positive first argument, the function will block indefinitely
     until it can read at least one character or EOF, and either return a non-
     empty string, or 0 on EOF.  This means, that after stdin has been con-
     nected to a socket with "accept", a return value of "" from (getchars 100
     5) means a timeout occured before any data was read from the socket,
     while a return value of 0 indicates EOF.

     When reading from a terminal device in canonical mode, when a timeout
     value has been specified, the empty string may be returned even though
     the user has typed some characters, because the terminal driver will not
     return any character data to the interpreter in canonical mode until a
     carriage return or a newline are input.

   readlock: (readlock)
     The "readlock" intrinsic is used to obtain a shared lock on a file con-
     nected to stdin.  The function accepts no arguments and returns 1 upon
     success, or 0 if the file is already locked by another process. If the
     lock cannot be obtained for any other reason, the function returns a
     string describing the error.

   writelock: (writelock)
     The "writelock" intrinsic is used to obtain an exclusive lock on a file
     connected to stdout.  The function accepts no arguments and returns 1
     upon success, or 0 if the file is already locked by another process.  If
     the lock cannot be obtained for any other reason, the function returns a
     string describing the error.

   unlock: (unlock expr)
     The "unlock" intrinsic is used to release a lock obtained by the "read-
     lock" or "writelock" intrinsics.  The function accepts one argument which
     must evaluate to either 0 or 1, specifying whether a lock on stdin or
     stdout is to be released, respectively.

   hostname: (hostname)
     The "hostname" intrinsic accepts no arguments and returns the name of
     host it is running on, or a string describing an error condition it
     encountered while attempting to retrieve the hostname.

   symlink: (symlink expr1 expr2)
     The "symlink" intrinsic creates a symbolic link to a pre-existing
     filesystem entity.  The function accepts two arguments, both of which
     must evaluate to strings.  The first argument specifies the pre-existing
     filesystem entity, while the second argument names the symbolic link.
     "symlink" returns 1 upon success, or a string describing an error condi-
     tion, if the symlink() system call failed.

   gecos: (gecos expr)
     The "gecos" intrinsic queries the user database for the value of the
     gecos field for a specified account.  The function accepts one argument
     which must be a string specifying the user name associated with the
     account.  If such a user exists, the value of the gecos field is returned
     as a string, otherwise the empty string is returned.  The gecos field is
     used to store personal information about the user.  Traditionally, it
     held 4 comma-separated fields containing the user's full name, office
     location, work phone number, and home phone number, but the system does
     not care what goes into the gecos field.  Most administrators nowadays
     simply place the user's full name there.

   record: (record expr)
     The "record" intrinsic creates a fixed-size unidimensional array.
     Records are a more space-efficient means of representing fixed-size
     aggregate types.  The one argument must evaluate to a positive integer
     specifying the size of the array.  The items of the record are all preset
     to the empty list upon creation.

   getfield: (getfield expr1 expr2)
     The "getfield" intrinsic is used to retrieve an item from a record.  It
     accepts two arguments, the first of which must evaluate to a record,
     while the second must evaluate to a positive integer specifying the index
     of the desired item in the array.  The object at that index is returned.

   setfield: (setfield expr1 expr2 expr3)
     The "setfield" intrinsic is used to insert an object into a record.  The
     function accepts three arguments.  The first argument must evaluate to
     the record to be affected.  The second argument must evaluate to a posi-
     tive integer specifying the index location to overwrite.  The third argu-
     ment can evaluate to any lisp object and will be inserted into the first
     argument at the location specified by the second argument.  The evaluated
     third argument is returned.

   extend: (extend expr1 expr2)
     The "extend" intrinsic adds a new binding to the currently-active local
     environment.  The function accepts two arguments, the first of which must
     evaluate to a symbol, while the second of which may evaluate to any lisp
     object.  The symbol is added to the local environment and bound to the
     result of evaluating the second argument, replacing any pre-existing
     local binding to that symbol.  Note that if the pre-existing symbol
     occurs free in the current lexical environment, then it is shadowed, not
     replaced.  The result of evaluating the second argument is returned.  The
     intent behind the inclusion of this intrinsic in the interpreter is to
     allow extensions to the current lexical environment without the use of
     "let" and friends, for increased efficiency.

     > (defun fact (n)
     >> (extend 'a 1)
     >> (while (> n 1)
     >>>   (setq a (* n a))
     >>>   (dec n))
     >> a)
     <CLOSURE#23>
     > (fact 10)
     3628800

     Any lambda-expressions closing over the current lexical environment will
     "see" the new binding, because closures do not simply close over the lex-
     ical bindings visible at the time of their creation, but rather the lexi-
     cal environments visible at the time of their creation.  The difference
     between these two notions, is that environments may be dynamically
     extended with "extend" to contain a superset of the bindings visible at
     creation.

     If the closure is applied before an invocation of "extend" it will not
     see the binding created, since it will be created in the future, but if
     that VERY SAME CLOSURE is applied after an invocation of "extend" it will
     see the new binding created.  The new binding suddenly appears in the
     current lexical environment.

     This means a closure bound to a new local via "extend" will "see" its own
     binding when it is applied, and therefore may call itself by name.  The
     extent of bindings created by "extend" is unlimited, but may be limited
     by wrapping the expressions in which they occur with an invocation of
     "dynamic_extent" described elsewhere in this document.

   gc: (gc)
     The "gc" intrinsic sets the garbage collector to run on the next evalua-
     tion.  The garbage collector normally runs once every 65536 evaluations.
     Judicious invocations of this function may allow the user to decrease the
     memory consumption of his or her program.

   dynamic_extent: (dynamic extent ...)
     The "dynamic_extent" intrinsic limits the extent of additions to the cur-
     rent lexical environment made with the "extend" intrinsic.  The intrinsic
     accepts zero or more arguments.  If no arguments are supplied,
     "dynamic_extent" does nothing and returns 1.  If arguments are supplied,
     they are evaluated in order, and the result of evaluating the last
     expression is returned.  If no lexical environment exists at the time of
     invocation, an error will be generated which will stop evaluation.  When
     "dynamic_extent" finishes, any additions made to the current lexical
     environment by the expressions in its body are removed.  Combinations of
     "dynamic_extent" and "extend" can replace occurrences of "let", "letn",
     or "labels" inside functions where the bodies of those expressions do not
     contain closures, or which contain closures which do not need to close
     over the new bindings, which will not persist beyond the extent of
     "dynamic_extent".

     In this example the new bindings introduced for "b" and "a" do not have
     their extent limited, and any closures formed in the body of the "let"
     would continue to "see" these bindings when the "let" returned, even if
     the closures were closed before the invocations of "extend".  The binding
     to "c" however, has its extent limited to the extent of the invocation of
     "dynamic_extent".  If no new bindings are introduced via "extend" inside
     an instance of "dynamic_extent", then it effectively does nothing.

     > (let ((a 10))
     >> (extend 'b (* a a))

     >> (dynamic_extent
     >>> (extend 'c (* b b))
     >>> (print c)
     >>> (newline))

     >> (print (boundp 'c))
     >> (newline))
     10000 ; first "print"
     0     ; second "print"

   gc_freq: (gc_freq expr)
     The "gc_freq" intrinsic allows the programmer to change the rate at which
     garbage collection occurs.  The default is once every 1048576 new objects
     or internal atoms have been allocated.  Internal atoms are not be con-
     fused with lisp atoms.  Each unique syntax has one internal atom repre-
     senting all occurences of that syntax.  So, (+ a a) is a list of three
     objects, but each of the 'a' objects point to the same internal atom.
     You don't need to know this.

     This function accepts one argument, which must evaluate to a whole number
     fixnum specifying a new value for the GC frequency.  Increasing GC fre-
     quency will cause the interpreter to run faster up to a point, but con-
     sume more memory, while decreasing the value of gc_frequency will cause
     the interpreter to run more slowly but consume less memory.

     The function returns the old frequency value.  Setting GC frequency to
     zero will disable garbage collection.  The programmer can manually invoke
     garbage collection with the "gc" intrinsic somewhere else in his or her
     program.

     There is a point, when garbage collection is turned-off or set to happen
     very infrequently, where the size of the object and atom pools will grow
     to be so large that GC itself will become the performance bottleneck of
     your program.  This is because these pools are never returned to the sys-
     tem.  Keep this in mind.

   getpid: (getpid)
   getppid: (getppid)
   getpgrp: (getpgrp)
   tcgetpgrp: (tcgetpgrp)
     The "getpid", "getppid", "getpgrp", "tcgetpgrp" intrinsics accept no
     arguments and each returns a fixnum representing the process id of the
     interpreter, or the process id of the parent process of the interpreter,
     or the process group id of the process group the interpreter belongs to,
     or the process group which is currently the foreground process associated
     with the terminal device the interpreter is running on, respectively.

     The "tcgetpgrp" function will return 0 if the interpreter is not associ-
     ated with a terminal device.  For any other error it will return a string
     describing the error condition.

   setpgid: (setpgid expr1 expr2)
     The "setpgrp" intrinsic accepts two arguments which both must evaluate to
     fixnums.  The first argument must be a process id of a running process,
     while the second must be the process group id of a running process group
     or it must be the same as the first argument.  The function puts the
     process specified by the first argument into the process group specified
     by the second argument.  Upon success, the function returns 1, otherwise
     it returns a string describing an error condition.  There processes which
     may be affected by this intrinsic are described in the manual page for
     the "getpgrp" system call.

     If the first argument is zero, then the pid of the interpreter process is
     used as the first argument.  If the second argument is zero, then the
     first argument will be used for the second argument, as well.  New
     process groups are created by setting both arguments to the same value.
     If the affected process is not already be a process group leader, it will
     become the process group leader of a new process group, and the process
     group id will be the same as its process id.

   tcsetpgrp: (tcsetpgrp expr)
     The "tcsetpgrp" intrinsic accepts one argument which must evaluate to a
     fixnum specifying a process group id and makes that process group the
     foreground process associated with the terminal device the interpreter is
     running on.  If the interpreter has no associated controlling terminal,
     then the function returns 0.  Upon success, it returns 1.  Otherwise it
     returns a string describing an error condition.  The processes which may
     be affected by this intrinsic are described in the manual page for the
     "tcsetpgrp" system call.  Note that although it is not mentioned in the
     manual page, one cannot call "tcsetpgrp" when one is a background
     process, unless one has blocked SIGTTOU, which may be accomplished by
     calling the "block" intrinsic.

   kill: (kill expr1 expr2)
     The "kill" intrinsic accepts two arguments, the first of which must eval-
     uate to a fixnum representing the process id of a running process, while
     the second argument must evaluate to a fixnum representing a signal num-
     ber.  The function sends the signal specified by the second argument to
     the process specified by the first argument.  If successful, the function
     returns 1, otherwise it returns a string describing an error condition.
     The processes which may be affected by this intrinsic are described in
     the "kill" system call (man 2 kill).  A table mapping signal numbers to
     signal names may be found in the "signal" manual page.

   killpg: (killpg expr1 expr2)
     The "killpg" intrinsic accepts two arguments, the first of which must
     evaluate to a fixnum representing the process group id of a running
     process group, while the second argument must evaluate to a fixnum repre-
     senting a signal number.  The function sends the signal specified by the
     second argument to every process in the process group specified by the
     first argument.  If successful, the function returns 1, otherwise it
     returns a string describing an error condition.  The processes which may
     be affected by this intrinsic are described in the manual page for the
     "killpg" system call (man 2 killpg).  A table mapping signal numbers to
     signal names may be found in the "signal" manual page.

   fork: (fork)
     The "fork" intrinsic is a wrapper for the "fork" system call.  The func-
     tion accepts no arguments and generates a new interpreter process which
     is an exact copy of the current process.  The function returns 0 to the
     child interpreter, and the process id of the child interpreter to the
     parent interpreter.  Upon error, -1 is returned.  The interpreter will
     reap any child processes which exit while it is running, unless the "zom-
     bies" intrinsic has been invoked, in which case, the programmer must reap
     them manually using the "wait" intrinsic.

     Read the entries for "child_open", "pipe", "with_input_process", and
     "with_output_process", and determine if they will do what you need a new
     process to do, before using "fork" or "forkpipe", because these other
     intrinsics and macros are more convenient to use.

   forkpipe: (forkpipe expr)
     The "fork" pipe behaves similarly to the "fork" intrinsic, but creates a
     pipe between the two interpreters.  The function accepts one argument,
     which must evaluate to one of 0, 1, or 2, and specifies which of the par-
     ent interpreter's descriptors is attached to the pipe.  These values cor-
     respond to the values of the file descriptors for the standard streams:
     0 is the standard input, 1 is the standard output, and 2 is the standard
     error.  The value specified implies which of the child interpreter's
     descriptors is attached to the pipe.  If parent descriptor 1 or 2 is
     specified, then the child interpreter will have its standard input con-
     nected to the pipe.  If parent descriptor 0 is specified, then the child
     will have its standard output connected to the pipe.  The function
     returns 0 in the child interpreter, the process id of the child process
     in the parent interpreter.  If the fork() system call fails, -1 is
     returned.  Any error encountered while creating the pipe or duping
     descriptors will stop evaluation.

     The interpreter will reap any child processes which exit while it is run-
     ning, unless the "zombies" intrinsic has been invoked, in which case, the
     programmer must reap them manually using the "wait" intrinsic.

     Read the entries for "child_open", "pipe", "with_input_process", and
     "with_output_process", and determine if they will do what you need a new
     process to do, before using "fork" or "forkpipe", because these other
     intrinsics and macros are more convenient to use.

   wait: (wait expr1 [expr2])
     The "wait" intrinsic is used to reap a zombie process.  When a child
     process terminates, its process table entry is preserved so that the
     interpreter may determine how it exited, and what its exit status was.
     When the interpreter starts-up it is in the "nozombies" state, which
     means it will automatically reap any zombies created by terminated child
     processes, discarding their exit statuses.

     If the programmer needs his or her program to wait for a child process to
     complete before proceeding, he or she may invoke the child with the "sys-
     tem" intrinsic, but if the programmer wants to the parent and child to
     proceed asynchronously, but still needs to know how the child process
     exited, or its exit status, then the programmer must invoke the "zombies"
     intrinsic before manually launching the child process with "fork" and
     "exec".  To retrieve the child's termination information, the programmer
     invokes "wait" at some time subsequent to forking the child, to reap the
     child's process table entry.   One should do this even if one subse-
     quently decides one is not interested in the termination information.  If
     the process has not yet terminated, "wait" will block until it does.

     The function accepts one or two arguments, the first of which must evalu-
     ate to a fixnum specifying a process id, 0, -1, or a process group id
     negated.  This argument is passed as the first argument to the waitpid()
     system call.  If the argument is a process id, "wait" will reap that
     process and return its termination information.  If the argument is -1,
     then "wait" will reap any zombie child process waiting to be reaped, and
     return its termination information.  If the argument is 0, then "wait"
     will reap any zombie child which belongs to the interpreter's process
     group.  If the argument is a process group id negated, then "wait" will
     reap any zombie child whose process group id is equal to the absolute
     value of the argument.

     If the second argument is present, it can evaluate to any value.  It is a
     "don't block" boolean flag.  If is not present or if it evaluates to a
     boolean "false" value, AND there are no stopped or zombie processes which
     can satisfy the "wait" request, BUT there is at least one running process
     which can satisfy the "wait" request in the future, THEN "wait" will
     block until it can reap a process.  Otherwise it will return immediately.

     The function returns a two or three element list.

     If "wait" cannot reap a process it returns a list containing the fixnum 0
     or -1, and the symbol ECHILD.  If no second argument was supplied to
     "wait" or if the second argument evaluated to a boolean "false" value,
     then the first element of the returned list will be -1.  This means there
     is no running or zombie process which can satisfy the "wait" now or in
     the future.  If a "true" second argument was supplied to "wait", then the
     first element of the returned list may be either -1 or 0.  A value of 0
     indicates there are processes which can satisfy the "wait" but which are
     still running.

     Otherwise, "wait" returns a list containing a fixnum representing the
     process id of the reaped process, followed by a symbol describing how the
     process exited, which will be one of EXITED, KILLED, or STOPPED.  If the
     second element is EXITED, then the process terminated by calling the
     "exit" or "_exit" system calls, and a third element will be present which
     will be a fixnum representing the child's exit status, which is the argu-
     ment it gave to "exit" or "_exit".  If the second element is KILLED, then
     the process was terminated by a signal, and a third element will be
     present which will be a fixnum representing the signal number of the sig-
     nal which terminated the process.  If the second element is STOPPED, then
     the process was stopped by a signal and may be started again, and a third
     element will be present which will be a fixnum representing the signal
     number which stopped the process.  Processes may be stopped by the job
     control related signals:  SIGSTOP, SIGSTP, SIGTTIN, SIGTTOU.  The manual
     page for "signal" maps signal numbers to constant names.

     If one wishes to simply ensure that all current zombies are reaped, one
     may invoke "wait" with an argument of -1, until it returns (-1 ECHILD).

     > (until (eq -1 (car (wait -1)))

   zombies: (zombies)
     The "zombies" intrinsic accepts no arguments, and when invoked causes the
     interpreter to stop reaping zombie child processes.  They may be manually
     reaped with the "wait" intrinsic.  Note that after invocation of "zom-
     bies", each invocation of "fork", "child_open", "with_input_process",
     "with_output_process", and "pipe" will generate a new process which must
     be manually reaped with the "wait" intrinsic.  Note that "input", "out-
     put", and "filter" will all reap their own zombies, regardless of the
     setting of zombies state.  This is because it is easy for the interpreter
     to reap the processes forked by these three, since they are running only
     while the associated intrinsic function is running.  The function always
     returns 1.

   nozombies: (nozombies)
     The "nozombies" intrinsic accepts no arguments, and when invoked causes
     the interpreter to reap zombie child processes.  The interpreter starts-
     up in the "nozombies" state.  This function always returns 1.

   zombiesp: (zombiesp)
     The "zombiesp" intrinsic accepts no arguments and returns the value of
     the zombies state.  It returns 1 if the interpreter is in the "zombies"
     state, and 0 otherwise.

   glob: (glob)
     The "glob" intrinsic accepts one argument, which must evaluate to a
     string, and calls the library function "glob" upon it, which interprets
     the string as a shell glob pattern and searches for matches in the
     filesystem on the pattern.  Any matches found will be returned as a list
     of strings.  If no matches are found, the empty list is returned.  Any
     errors encountered, will stop evaluation.  It is not an error for a pat-
     tern to have no matches.

   command_lookup: (command_lookup expr)
     The "command_lookup" intrinsic accepts one argument which must evaluate
     to a string, and attempts to find a file executable by the user the
     interpreter is running as, in the directories specified by the PATH envi-
     ronment variable.  If successful, the fully-qualified filename is
     returned.  If not successful, the empty string is returned.

     If the user has changed the value of the PATH environment variable, or
     has added new executables to the directories specified by the environment
     variable, then the "rescan_path" intrinsic must be invoked to get the
     interpreter to update its internal list of executables.

     > (command_lookup "munger")
     "/usr/local/bin/munger"
     > (command_lookup "foobar")
     ""

   getstring: (getstring expr)
     The "getstring" library function returns the output of an external
     process as a string.  The function accepts one argument which must evalu-
     ate to a command line to be passed to the shell (/bin/sh) and gathers up
     the data which appears on the program's standard output into a string,
     which it then returns.  No processing is performed on the program output.
     It is returned unaltered.

     If the interpreter cannot "forkpipe", the function returns -1.  If the
     "forkpipe" is successful but the "shexec" is not, then the function will
     return the empty string.  This means specifying a non-existent program to
     run, or a program to which you do not have read and execute permission,
     will cause the function to return the empty string.

   dec2hex: (dec2hex expr)
     The "dec2hex" intrinsic converts a fixnum representing a whole number
     into a string representing the number in hexadecimal notation.  If the
     programmer passes a negative number to the function, an error will be
     generated.

     > (dec2hex 65535)
     "FFFF"

   hex2dec: (hex2dec expr)
     The "hex2dec" intrinsic converts a string representing a whole number in
     hexadecimal notation to a fixnum.  The letter characters used in hexadec-
     imal notation may be in either lower or upper case forms.

     > (hex2dec "FfFf")
     65535

   listen: (listen expr [expr])
     The "listen" intrinsic is used to start the kernel accepting incoming tcp
     connections for the interpreter process.  Both IPv4 and IPv6 connections
     will be accepted.  The functions accept one or two arguments.  The first
     argument must evaluate to either a fixnum specifying the port number to
     accept incoming connections on, or a string naming a service, as listed
     in /etc/services.  If the port number is 0, then the kernel will choose a
     port from the ephemeral ports.  The second optional argument, if present,
     must evaluate to a string specifying the IP address of the interface to
     use.  It must be expressed in the presentation format for either IPv4 or
     IPv6.  If the second argument is not present, the function will accept
     connections on all interfaces of both protocol families.

     If successful, the function returns the port number the listening socket
     is listening on.  Otherwise, it returns a string describing an error con-
     dition.  The listen() system call is called with backlog argument of
     4096.  This determines the number of connections the kernel will queue,
     awaiting service.  Only one listening socket may be active at any time.
     To accept connections on more than one interface simultaneously, the pro-
     grammer must "fork" the interpreter, and have each instance call "lis-
     ten".  The listening socket can be closed with the "stop_listening"
     intrinsic.  After a successful invocation the kernel will start accepting
     and queuing incoming connections on the specified interface.  To service
     a connection, the programmer invokes the "accept" intrinsic, documented
     below.

   listen_unix: (listen_unix expr)
     The "listen_unix" intrinsic is used to start the kernel accepting incom-
     ing connections over a UNIX domain socket.  The function accepts one
     argument, which must evaluate to a string specifying the desired pathname
     for the listening socket in the filesystem.  If the entity so named
     exists, an attempt will be made to unlink it first.  If the Munger inter-
     preter lacks the necessary permissions to do so, the bind() system call
     will fail and "listen_unix" will return a string containing an error mes-
     sage.  All other errors will also cause an error string to be returned.
     The function returns 1 on success.  The second paragraph of the entry in
     this manual for the "listen" intrinsic applies to "listen_unix" as well.

   stop_listening: (stop_listening)
     The "stop_listening" intrinsic closes a listening socket opened by the
     "listen" or "listen_unix" intrinsics.  The function accepts no arguments
     and returns 1 if a listening socket was active, or 0 otherwise.  After
     calling "stop_listening" no more incoming connections may be accepted
     with "accept" until the programmer calls "listen" again.

   accept: (accept)
     The "accept" intrinsic accepts an incoming tcp connection.  It can only
     be invoked after "listen" or "listen_unix" has been invoked, and is
     invoked repeatedly to accept successive incoming connections.  The func-
     tion accepts no arguments and returns 1 if successful, -1 if the system
     call was interrupted by a SIGTERM, or a string describing an error condi-
     tion otherwise.  The function blocks until an incoming connection has
     been completed and is ready for communication with the client who initi-
     ated it.

     When "accept" returns, the stdin and stdout of the interpreter will have
     been redirected onto the incoming connection.  Any of the intrinsics
     which read and write from those descriptors ("print", "println", "new-
     line", "getchar", getchars", and "getline") may be used to communicate
     with the client.  One must keep in mind "accept" works like "pipe" or
     "redirect" in that the new streams connected to the affected descriptors
     "shadow" the previously connected streams, but the previously-connected
     streams are still open in the interpreter.  This means one should invoke
     both (resume 0) and (resume 1) when one is finished communicating with a
     client, before calling "accept" again, unless one intends to come back to
     the previously-accepted connection in the future.

     To service more than one client at a time, the programmer may "fork" the
     interpreter multiple times and have each child call "accept" for itself
     in a loop to accept incoming connections, or the programmer may choose to
     have one process call "accept" and then fork a new process as needed to
     service each client.

     In the example of an echo server below, the parent process "accepts" each
     incoming connection, then forks off a child to service it.  The child
     calls "stop_listening" to close its reference to the listening socket.
     This is because the parent could exit before the child, and if the child
     still had a valid reference to the listening socket, then the kernel
     would still keep queuing incoming connections which would never be
     accepted, because the parent process does the accepting.  Therefore, we
     want incoming connections rejected when the parent exits.  The parent
     calls "resume" on both stdin and stdout to close its references to the
     newly-accepted client.  If it did not do this, the parent's connection to
     the client could remain open until the next time "resume" was invoked in
     the parent, unless the client explicitly closed its end of the connec-
     tion.  Note that this program must be run as "root" to bind to port 7,
     and will never exit unless "listen" or "accept" encounters an error.  It
     must be killed with a signal.

     (fatal)
     (daemonize "echo1.munger")

     (defun service_client ()
        (while (setq line (getline))
           (print line)
           (flush_stdout)))

     (when (fixnump (setq err (listen 7)))
        (setuid "nobody")

        (while (fixnump (setq err (accept)))

           (if (not (fork))
              (progn
                 (stop_listening)
                 (service_client)
                 (exit 0))

              (resume 0)
              (resume 1))))

     (syslog 'CRITICAL err)
     (exit 1)

     Another example of an echo server is below.  In this server, the parent
     calls "listen" then forks off 9 children.  All ten processes then call
     "accept" in an infinite loop to service clients.  All ten accept connec-
     tions from the same listening socket, so all ten need to keep their ref-
     erences to it open.  Since each process calls "accept" separately, none
     of them will have references to each others' accepted connections to
     worry about, but there is another detail related to "accept" we must
     worry about in this example.  In order to ensure we do not keep previ-
     ously accepted connections open, we must explicitly close each tcp con-
     nection when we are finished with it, before calling "accept" again,
     hence the calls to "resume" in the process_clients function below.  Note
     that this program must be run as root to bind to port 7, and will never
     exit unless "listen" or "accept" encounters an error.  It must be killed
     with a signal.

     (fatal)
     (daemonize "echo2.munger")

     (defun service_client ()
        (while (setq line (getline))
           (print line)
           (flush_stdout)))

     (defun process_clients ()
        (while (fixnump (setq err (accept)))
           (service_client)
           (resume 0)
           (resume 1)))

     (when (fixnump (setq err (listen 7)))
        (setuid "nobody")

        (catch
           (iterate 9
              (unless (fork)
                 (throw 0)))))

     (process_clients)
     (syslog 'CRITICAL err)
     (exit 1)

   get_scgi_header: (get_scgi_header)
     The "get_scgi_header" intrinsic parses an SCGI header netstring from
     standard input and returns a list of strings, guaranteed to be a multiple
     of 2 in length, or fixnum 0.  A 0 return value indicates the function
     encountered an error and gave up.  A returned list of strings indicates
     the SCGI header was read successfully, and each pair of strings in the
     returned list will be a name of an SCGI environment variable and its
     value.  For an example of usage see the scgi.munger exampler SCGI server.
     Standard input is positioned at the beginning of the SCGI body, when the
     function returns.

     This function should not be used in conjunction with "getline", as that
     function does its own buffering, and "get_scgi_header" will not see
     already-read data that "getline" has accumulated in its buffer.  Rather
     to read data in a server program, use the unbuffered input functions,
     "getchars", or "getline_ub".

   send_descriptors: (send_descriptors);
     The "send_descriptors" intrinsic can only be invoked after "child_open"
     has been successfully invoked to open a client connection to a server
     process over a UNIX domain socket.  The function accepts no arguments and
     returns 1 on success, or a string describing an error condition, other-
     wise.

     This function in conjunction with "receive_descriptors", is used to cause
     one Munger interpreter to pass its standard input and output to another
     Munger interpreter.  The server interpreter calls "receive_descriptors"
     while the client calls "send_descriptors".  After both intrinsics have
     returned success to their respective interpreters, the server's standard
     input will be connected to the same source the client's standard input is
     connected to, and the server's standard output will be connected to the
     same source the client's standard output is connected to.  The connection
     over the UNIX domain socket is unaffected.  The client may close it with
     "child_close" afterward, if the client has no more communication to
     accomplish with the server.

   receive_descriptors: (receive_descriptors)
     The "receive_descriptors" intrinsic can only be invoked after "lis-
     ten_unix" and "accept" have been successfully invoked to accept a client
     connection over a UNIX domain socket.  The function accepts no arguments
     and returns 1 on success, or a string describing an error condition, oth-
     erwise.

     In conjunction with "send_descriptors", this function is used to cause
     one Munger interpreter to pass its standard input and output to another
     Munger interpreter.  The client invokes "send_descriptors" and the server
     invokes "receive_descriptors".  After both intrinsics have returned suc-
     cess in their respective interpreters, the server's standard input will
     be connected to the same source the client's standard input is connected
     to, and the server's standard output will be connected to the same source
     the client's standard output is connected to.  The "resume" intrinsic can
     be called by the server interpreter to return either or both descriptors
     to the sources they were formerly connected to, which is the connection
     to the client over the UNIX domain socket.  Invoking "resume" again on
     both 0 and 1, will close the connection, and cause the server inter-
     preters standard input and output to be connected to the sources they
     were connected to before the call to "accept".

   busymap: (busymap expr)
     The "busymap" intrinsic is used to create an byte-array of shared memory
     between parent and child server processes.  The function accepts one
     argument which must evaluate to a fixnum specifying the length of the
     array in bytes.  Only one busymap can exist at any time.  If a busymap
     already exists, then the function returns -1.  Upon successfully creating
     a new busymap, the function returns 1.  Otherwise, a string describing an
     error condition is returned.

     There is no locking mechanism provided to arbitrate access to the
     busymap.  The intended usage is for slave processses of multi-process
     servers to write to the busymap with the "busy" and "notbusy" intrinsics,
     and the master process manager to read it with "busyp".  See the
     httpd.munger example web server for usage.

     Master server processes requests their children exit by sending them a
     SIGTERM (signal number 15) with the "kill" intrinsic.  If this signal is
     received by the interpreter, the next invocation of "accept" will cause
     the interpreter to exit.  If the interpreter is blocked in "accept" at
     the time of the arrival of the signal, the interpreter will exit immedi-
     ately.  This allows the slave server process to continue processing any
     established client connection to completion before exiting.

   nobusymap: (nobusymap)
     The "nobusymap" intrinsic frees a busymap which has been created with the
     "busymap" intrinsic.  The function accepts no arguments and returns -1 if
     no busymap exists, 1 if the busymap was successfully unmapped, or a
     string describing an error condition.  Each process which has access to
     the busymap, which is to say all the children of the caller of "busymap"
     who have not invoked "exec", must call "nobusymap", in order to com-
     pletely remove the shared mapping.

   busy: (busy expr)
     The "busy" intrinsic sets a byte in a busymap to 1.  The function accepts
     one argument which must evaluate to a fixnum specifying the index of a
     byte (indices start at 0) in the active busymap to affect.  If no busymap
     exists, the function returns -1.  If successful, the function returns 1.
     If the index is out of range, an error will be generated which will stop
     evaluation.

   notbusy: (notbusy expr)
     The "notbusy" intrinsic sets a byte in a busymap to 0.  The function
     accepts one argument which must evaluate to a fixnum specifying the index
     of a byte (indices start at 0) in the active busymap to affect.  If no
     busymap exists, the function returns -1.  If successful, the function
     returns 1.  If the index is out of range, an error will be generated
     which will stop evaluation.

   busyp: (busyp expr)
     The "busyp" intrinsic returns the value of a byte in the active busymap.
     The function accepts one argument which must evaluate to a fixnum speci-
     fying the index of a byte (indices start at 0) in the active busymap.  If
     no busymap exists, the function returns -1.  If successful, the function
     returns either 0 or 1, 0 indicating the "not busy" state, and 1 indicat-
     ing the "busy" state.  If the index is out of range, an error will be
     generated which will stop evaluation.

   chroot: (chroot expr)
     The "chroot" intrinsic accepts one argument, which must evaluate to a
     string, and calls the chroot(2) system call with that string as argument.
     This system call is used to change the root directory for the inter-
     preter, which must be running as root for the call to succeed.  After a
     successful invocation, the initial slash (/) in all pathnames will refer
     to the specified directory.  See the chroot(2) manual page for more
     details.  Upon success the function returns 1, otherwise it returns a
     string describing an error condition.

     Once a process has been chroot-ed, it, and its children, may no longer
     access any part of the file system above the new root directory.  This
     means a program needing shared libraries existing outside of the visible
     hierarchy will not start in the chroot environment.  For those programs a
     miniature filesystem with appropriate libraries must be set up before
     invoking "chroot".  Processes are allowed to keep their open descriptors
     in the new environment, allowing access to previously opened items out-
     side of the new hierarchy, so programs typically chroot after they have
     done all of their startup tasks, such as opening log files.  For example,
     "daemonize" should be called before "chroot" to open the connection to
     /dev/log, which will not be visible afterward.

   daemonize: (daemonize expr)
     The "daemonize" intrinsic turns the interpreter into a daemon process.
     The function accepts one argument which must evaluate to the name for the
     program to use for itself in the system logfile.  The function returns 1
     upon success, or if it encounters a problem evaluating its arguments, it
     generate an error which will stop evaluation.  If the function encounters
     an error condition after it has closed the standard descriptors, it will
     cause the interpreter to exit with an exit status of 1, and write an
     error message to the system log.

     To become a daemon, "daemonize" undoes all redirections of the standard
     descriptors, and closes and reopens stdin, stdout, and stderr on
     /dev/null, and it closes any open full-duplex connection opened with
     "child_open".  It then calls the "openlog" library function to establish
     a connection with the syslog daemon, so the daemon process may emit mes-
     sages to the system log.  The function then calls the "block" intrinsic
     to block a number of signals.  Consult the entry in this document for the
     "block" intrinsic for details.  It then forks and allows the parent
     process to exit, so that the child cannot be a process group leader.
     This is required so that it may next call setsid() to detach itself from
     its controlling terminal.  This prevents users at the terminal from send-
     ing job-control signals to the daemon process.

   syslog: (syslog expr expr)
     The "syslog" intrinsic is used to send a message to the system logfile.
     It is a wrapper around the syslog() library function.  It can only be
     used after "daemonize" has been successfully invoked.  The function
     accepts two arguments, the first of which must evaluate to one of the
     following set of symbols indicating the priority of the event being
     logged:  ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG.  The sym-
     bols must be in all upper-case letters.  The /etc/syslog.conf that ships
     with FreeBSD at the time this entry in the manual page is being edited,
     prevents any message with priority lower than NOTICE of being logged.
     The second argument must evaluate to a string containing the log message.
     Unlike the syslog() library function, no % processing (a la printf) takes
     place in the message string.  Any % occurring in the message string will
     be escaped with another %.  The "daemonize" intrinsic will have called
     openlog() to set the name of the daemon and its process id to automati-
     cally appear in the logfile before the message text.  It is not necessary
     to include anything in the message text except a description of the event
     being logged.  The function returns 1 upon success, or it uses the sys-
     log() library call to send an error message to the system log, and then
     causes the interpreter to exit.  There is no point in returning to
     toplevel in response to an error event because after "daemonize" has been
     invoked, the interpreter is no longer capable of performing terminal I/O.

   flush_stdout: (flush_stdout)
     The "flush_stdout" intrinsic accepts no arguments and calls fflush() on
     the standard output stream, returning to the caller whatever that func-
     tion returns, either 0 upon success or -1 upon encountering an error.
     Any buffered data which has not yet been written to stdout, is written to
     the stream.  This can be useful when writing to a TCP connection, as the
     network stack will buffer data to avoid propagating many small TCP seg-
     ments over the connection.  Invoking "flush_stdout" after each call-and-
     response interaction with a client, is a good idea, to ensure the client
     gets its response immediately.

   getpeername: (getpeername)
     The "getpeername" intrinsic is a wrapper around the system call of the
     same name.  The function accepts no arguments, and if invoked after "lis-
     ten" and "accept", returns a string representing the IP address of the
     host on the other end of the TCP connection currently connected to stdin
     and stdout.  The function returns 0 upon encountering any error.

   base64_encode (base64_encode expr)
     The "base64_encode" intrinsic accepts one argument which must evaluate to
     a string, and returns a new string representing its argument encoded in
     the base64 encoding scheme used by MIME messages.  It would be impracti-
     cal to read a large binary file into memory as a string and feed it to
     this intrinsic.  One may instead use the "getchars" intrinsic to read
     chunks of the file and feed them to this function.  As long as each chunk
     given to "base64_encode" is a multiple of three bytes in length, except
     for the last chunk, which may be any length, the output strings from each
     invocation may be concatenated together to form the base64 encoding for
     the entire file.

     > (with_input_file "binary.file"
     >> (with_output_file "binary.file.base64"

     >>>  (println "begin-base64 644 binary.file")

     >>>  (while (setq line (getchars 57))
     >>>>   (println (base64_encode line)))

     >>>  (println "====")))

     will produce the same output as the b64encode system utility invoked as:

     b64encode -o binary.file.base64 binary.file binary.file

     Base 64 encoding represents 3 bytes of data as 4 printable characters, so
     using a line size of 57 will cause those lines to expand to 76 characters
     after encoding, which is less than the once-customary 80 character limit
     on line lengths in an email message.

     A more efficient method would read a larger amount of text and cut up the
     lines with "substring":

     > (with_input_file "binary.file"
     >> (with_output_file "binary.file.base64"

     >>> (println "begin-base64 644 binary.file")
     >>> (setq line "")

     >>> (while (setq segment (getchars 100000))
     >>>> (setq line (concat line segment))

     >>>> (while (> (length line) 57)
     >>>>> (println (base64_encode (substring line 0 57)))
     >>>>> (setq line (substring line 57 0))))

     >>> (when line (println (base64_encode line)))

     >>> (println "====")))

   base64_decode (base64_decode expr)
     The "base64_decode" intrinsic accepts one argument, which must evaluate
     to a string containing base64-encoded data, and returns a new string con-
     sisting of the unencoded data.  If the function encounters a character in
     the input string which is not part of the base64 vocabulary, or if the
     length of the argument string is not a multiple of four characters, it
     returns 0.

   isatty: (isatty expr)
     The "isatty" intrinsic is a wrapper for the isatty(3) library call.  The
     function accepts one argument which must evaluate to either fixnum 0, 1,
     or 2, specifying stdin, stdout, or stderr, respectively.  The function
     returns fixnum 0 if the specified descriptor is not connected to a termi-
     nal device, and a non-zero fixnum value, if the specified descriptor is
     connected to a terminal device.

   sleep: (sleep expr)
     The "sleep" intrinsic is a wrapper for the sleep(3) library call.  The
     function accepts one argument which must evaluate to a fixnum specifying
     a number of seconds for the interpreter to go to sleep.  The function
     returns when specified number of seconds has elapsed or a signal has been
     received by the interpreter.  The function returns 0 if the specified
     number of seconds has elapsed.  If the function is interrupted by a sig-
     nal, it returns the remaining, unslept number of seconds.  If the inter-
     preter receives a SIGTERM, this can be discovered by invoking "sigtermp".

   unsigned: (unsigned expr)
     The "unsigned" intrinsic accepts one argument which must evaluate to a
     fixnum and returns a string representing the value of the fixnum,
     expressed as an unsigned value.  This is not the same as the absolute
     value of the fixnum.  It is similar to casting an int to an unsigned int
     in C, but getting a string representation back instead of a number.

     The intrinsic is designed to be used in those situations where one would
     like to do unsigned arithmetic operations, with numbers large enough to
     cause the two's-complement representation of the result to wrap-around to
     the negative side, but not large enough to overflow the fixnum itself.
     That is to say, not generating a result greater than

     (unsigned (+ 1 (* (maxidx) 2)))

   form_encode: (form_encode expr)
   form_decode: (form_decode expr)
     These two intrinsics encode and decode strings to and from the x-www-
     form-url-encoding used by web clients to encode the data in forms.  Each
     intrinsic accepts one string argument, and returns a string.

                                April 15, 2014