File: part15.html

package info (click to toggle)
nyquist 3.20%2Bds-2
links: PTS, VCS
area: main
in suites: bookworm
size: 58,008 kB
sloc: ansic: 74,743; lisp: 17,929; java: 10,723; cpp: 6,690; sh: 171; xml: 58; makefile: 40; python: 15
file content (2131 lines) | stat: -rwxr-xr-x 102,511 bytes
parent folder | download | duplicates (7)
<html><head><title>Appendix 3: XLISP: An Object-oriented Lisp</title></head>
<a name = "100"><h2>Appendix 3: XLISP: An Object-oriented Lisp</h2></a>

<blockquote><b>Version 2.0</b>
<p>
February 6, 1988
<p>
by<br>

<b>David Michael Betz</b><br>

127 Taylor Road<br>

Peterborough, NH 03458
<p>
(603) 924-6936 (home)
<p>
Copyright (c) 1988, by David Michael Betz<br>

All Rights Reserved<br>

Permission is granted for unrestricted non-commercial use<br>

</blockquote>


<a name = "101"><h3>Introduction</h3></a>
<p>
        XLISP is an experimental programming language combining some of
        the features of Common Lisp with an object-oriented extension
        capability.  It was implemented to allow experimentation with
        object-oriented programming on small computers.
<p>
        There are currently implementations of XLISP running on the IBM-
        PC and clones under MS-DOS, on the Macintosh, the Atari-ST and
        the Amiga.  It is completely written in the programming language
        C and is easily extended with user written built-in functions
        and classes.  It is available in source form to non-commercial
        users.
<p>
        Many Common Lisp functions are built into XLISP.  In addition,
        XLISP defines the objects Object and Class as primitives.
        Object is the only class that has no superclass and hence is
        the root of the class hierarchy tree.  Class is the class of
        which all classes are instances (it is the only object that is
        an instance of itself).
<p>
        This document is a brief description of XLISP.  It assumes some
        knowledge of LISP and some understanding of the concepts of
        object-oriented programming.
<p>
        I recommend the book <i>Lisp</i> by Winston and Horn and published by
        Addison Wesley for learning Lisp.  The first edition of this
        book is based on MacLisp and the second edition is based on
        Common Lisp.  XLISP will continue to migrate towards
        compatibility with Common Lisp.
<p>
        You will probably also need a copy of <i>Common Lisp: The
        Language</i> by Guy L. Steele, Jr., published by Digital Press to
        use as a reference for some of the Common Lisp functions that
        are described only briefly in this document.
<p>
        <a name = "102"><h3>A Note From The Author</h3></a>        If you have any problems with XLISP, feel free to contact me [me being David Betz - RBD] for
        help or advice.  Please remember that since XLISP is available
        in source form in a high level language, many users [e.g. that Dannenberg fellow - RBD] have been
        making versions available on a variety of machines.  If you call
        to report a problem with a specific version, I may not be able
        to help you if that version runs on a machine to which I don't
        have access.  Please have the version number of the version that
        you are running readily accessible before calling me.
<p>
        If you find a bug in XLISP, first try to fix the bug yourself
        using the source code provided.  If you are successful in fixing
        the bug, send the bug report along with the fix to me.  If you
        don't have access to a C compiler or are unable to fix a bug,
        please send the bug report to me and I'll try to fix it.
<p>
        Any suggestions for improvements will be welcomed.  Feel free to
        extend the language in whatever way suits your needs.  However,
        PLEASE DO NOT RELEASE ENHANCED VERSIONS WITHOUT CHECKING WITH ME
        FIRST!!  I would like to be the clearing house for new features
        added to XLISP.  If you want to add features for your own
        personal use, go ahead.  But, if you want to distribute your
        enhanced version, contact me first.  Please remember that the
        goal of XLISP is to provide a language to learn and experiment
        with LISP and object-oriented programming on small computers.  I
        don't want it to get so big that it requires megabytes of memory
        to run.
<p>
        <a name = "103"><h3>XLISP Command Loop</h3></a><a name="index664"><a name="index665">        When XLISP is started, it first tries to load the workspace
        <code>xlisp.wks</code> from the current directory.  If that file doesn't
        exist, XLISP builds an initial workspace, empty except for the
        built-in functions and symbols.
<p>
        Then XLISP attempts to load <code>init.lsp</code> from the current
        directory.  It then loads any files named as parameters on the
        command line (after appending <code>.lsp</code> to their names).
<p>
        XLISP then issues the following prompt:
<pre>
        &gt
</pre>

        This indicates that XLISP is waiting for an expression to be
        typed.
<p>
        When a complete expression has been entered, XLISP attempts to
        evaluate that expression.  If the expression evaluates
        successfully, XLISP prints the result and then returns to the
        initial prompt waiting for another expression to be typed.
<p>
        <a name = "104"><h3>Break Command Loop</h3></a><a name="index666">        When XLISP encounters an error while evaluating an expression,
        it attempts to handle the error in the following way:
<p>
        If the symbol <code>*breakenable*<a name="index667"></code> is true, the message corresponding
        to the error is printed.  If the error is correctable, the
        correction message is printed.
<p>
        If the symbol <code>*tracenable*<a name="index668"></code> is true, a trace back is printed.
        The number of entries printed depends on the value of the symbol
        <code>*tracelimit*<a name="index669"></code>.  If this symbol is set to something other than a
        number, the entire trace back stack is printed.
<p>
        XLISP then enters a read/eval/print loop to allow the user to
        examine the state of the interpreter in the context of the
        error.  This loop differs from the normal top-level
        read/eval/print loop in that if the user invokes the function
        <code>continue</code>, XLISP will continue from a correctable error.  If
        the user invokes the function <code>clean-up</code>, XLISP will abort the
        break loop and return to the top level or the next lower
        numbered break loop.  When in a break loop, XLISP prefixes the
        break level to the normal prompt.
<p>
        If the symbol <code>*breakenable*<a name="index670"></code> is <code>nil</code>, XLISP looks for a
        surrounding errset function.  If one is found, XLISP examines
        the value of the print flag.  If this flag is true, the error
        message is printed.  In any case, XLISP causes the errset
        function call to return <code>nil</code>.
<p>
        If there is no surrounding errset function, XLISP prints the
        error message and returns to the top level.
<p>
        <a name = "105"><h3>Data Types</h3></a><a name="index671"><a name="index672">        There are several different data types available to XLISP
        programmers.
<p>
<ul>
<li>
lists
<li>symbols
<li>strings
<li>integers
<li>characters
<li>floats
<li>objects
<li>arrays
<li>streams
<li>subrs (built-in functions)
<li>fsubrs (special forms)
<li>closures (user defined functions)
</ul>
<p>
<a name = "106"><h3>The Evaluator</h3></a><a name="index673"><a name="index674">        The process of evaluation in XLISP:
<ul>
<li>
        Strings, integers, characters, floats, objects, arrays, streams,
        subrs, fsubrs and closures evaluate to themselves.
<li>        Symbols act as variables and are evaluated by retrieving the
        value associated with their current binding.
<li>        Lists are evaluated by examining the first element of the list
        and then taking one of the following actions:
<ul>
<li>
            If it is a symbol, the functional binding of the symbol is
            retrieved.
<li>            If it is a lambda expression, a closure is constructed for
            the function described by the lambda expression.
<li>            If it is a subr, fsubr or closure, it stands for itself.
<li>            Any other value is an error.
</ul>
        Then, the value produced by the previous step is examined:
<ul>
<li>
            If it is a subr or closure, the remaining list elements are
            evaluated and the subr or closure is called with these
            evaluated expressions as arguments.
<li>            If it is an fsubr, the fsubr is called using the remaining
            list elements as arguments (unevaluated).
<li>            If it is a macro, the macro is expanded using the remaining
            list elements as arguments (unevaluated).  The macro
            expansion is then evaluated in place of the original macro
            call.
</ul>
</ul>
<p>
<a name = "107"><h3>Lexical Conventions</h3></a><a name="index675"><a name="index676">        The following conventions must be followed when entering XLISP
        programs:
<p>
        Comments in XLISP code begin with a semi-colon character and
        continue to the end of the line.
<p>
        Symbol names in XLISP can consist of any sequence of non-blank
        printable characters except the following:
<pre>
                ( ) ' ` , " ;
</pre>

        Uppercase and lowercase characters are not distinguished within
        symbol names.  All lowercase characters are mapped to uppercase
        on input.
<p>
        Integer literals consist of a sequence of digits optionally
        beginning with a <code>+</code> or <code>-</code>.  The range of values an integer can
        represent is limited by the size of a C <code>long</code> on the machine on
        which XLISP is running.
<p>
        Floating point literals consist of a sequence of digits
        optionally beginning with a <code>+</code> or <code>-</code> and including an embedded
        decimal point.  The range of values a floating point number can
        represent is limited by the size of a C <code>float</code> (<code>double</code> on
        machines with 32 bit addresses) on the machine on which XLISP is
        running.
<p>
        Literal strings are sequences of characters surrounded by double
        quotes.  Within quoted strings the ``<code>\</code>'' character is used to
        allow non-printable characters to be included.  The codes
        recognized are:
<ul>
<li>
<code>\\</code>        means the character ``<code>\</code>''
<li><code>\n</code>      means newline
<li><code>\t</code>       means tab
<li><code>\r</code>       means return
<li><code>\f</code>       means form feed
<li><code>\nnn</code>    means the character whose octal code is nnn
</ul>
<p>
<a name = "108"><h3>Readtables</h3></a><a name="index677">        The behavior of the reader is controlled by a data structure
        called a <i>readtable</i>.  The reader uses the symbol <code>*readtable*<a name="index678"></code> to
        locate the current readtable.  This table controls the
        interpretation of input characters.  It is an array with 128
        entries, one for each of the ASCII character codes.  Each entry
        contains one of the following things:
<ul>
<li>
                <code>NIL</code> -          Indicating an invalid character
<li>                <code>:CONSTITUENT</code> -   Indicating a symbol constituent
<li>                <code>:WHITE-SPACE</code>  -  Indicating a whitespace character
<li>                <code>(:TMACRO . <i>fun</i>)</code> - Terminating readmacro
<li>                <code>(:NMACRO . <i>fun</i>)</code> - Non-terminating readmacro
<li>                <code>:SESCAPE</code> -       Single escape character ('\')
<li>                <code>:MESCAPE</code> -       Multiple escape character ('|')
</ul>
<p>
        In the case of <code>:TMACRO</code> and <code>:NMACRO</code>, the <i>fun</i> component is a
        function.  This can either be a built-in readmacro function or a
        lambda expression.  The function should take two parameters.
        The first is the input stream and the second is the character
        that caused the invocation of the readmacro.  The readmacro
        function should return <code>NIL</code> to indicate that the character should
        be treated as white space or a value consed with <code>NIL</code> to indicate
        that the readmacro should be treated as an occurence of the
        specified value.  Of course, the readmacro code is free to read
        additional characters from the input stream.
<p>
        XLISP defines several useful read macros:
<ul>
<li>
                '<i>&ltexpr&gt</i>         == (quote <i>&ltexpr&gt</i>)
<li>                #'<i>&ltexpr&gt</i>        == (function <i>&ltexpr&gt</i>)
<li>                #(<i>&ltexpr&gt</i>...)    == an array of the specified expressions
<li>                #x<i>&lthdigits&gt</i>     == a hexadecimal number (0-9,A-F)
<li>                #o<i>&ltodigits&gt</i>     == an octal number (0-7)
<li>                #b<i>&ltbdigits&gt</i>     == a binary number (0-1)
<li>                #\<i>&ltchar&gt</i> == the ASCII code of the character
<li>                #| ... |#       == a comment
<li>                #:<i>&ltsymbol&gt</i>      == an uninterned symbol
<li>                `<i>&ltexpr&gt</i>         == (backquote <i>&ltexpr&gt</i>)
<li>                ,<i>&ltexpr&gt</i>         == (comma <i>&ltexpr&gt</i>)
<li>                ,@<i>&ltexpr&gt</i>        == (comma-at <i>&ltexpr&gt</i>)
<li></ul>
<a name = "109"><h3>Lambda Lists</h3></a><a name="index679">        There are several forms in XLISP that require that a ``lambda
        list'' be specified.  A lambda list is a definition of the
        arguments accepted by a function.  There are four different
        types of arguments.
<p>
        The lambda list starts with required arguments.  Required
        arguments must be specified in every call to the function.
<p>
        The required arguments are followed by the &amp;optional arguments.
        Optional arguments may be provided or omitted in a call.  An
        initialization expression may be specified to provide a default
        value for an &amp;optional argument if it is omitted from a call.
        If no initialization expression is specified, an omitted
        argument is initialized to <code>NIL</code>.  It is also possible to provide
        the name of a <code>supplied-p</code> variable that can be used to
        determine if a call provided a value for the argument or if the
        initialization expression was used.  If specified, the supplied-
        p variable will be bound to T if a value was specified in the
        call and <code>NIL</code> if the default value was used.
<p>
        The &amp;optional arguments are followed by the &amp;rest argument.  The
        &amp;rest argument gets bound to the remainder of the argument list
        after the required and &amp;optional arguments have been removed.
<p>
        The &amp;rest argument is followed by the &amp;key arguments.  When a
        keyword argument is passed to a function, a pair of values
        appears in the argument list.  The first expression in the pair
        should evaluate to a keyword symbol (a symbol that begins with a
        ``<code>:</code>'').  The value of the second expression is the value of the
        keyword argument.  Like &amp;optional arguments, &amp;key arguments can
        have initialization expressions and supplied-p variables.  In
        addition, it is possible to specify the keyword to be used in a
        function call.  If no keyword is specified, the keyword obtained
        by adding a ``<code>:</code>'' to the beginning of the keyword argument symbol
        is used.  In other words, if the keyword argument symbol is
        <code>foo</code>, the keyword will be <code>':foo</code>.
<p>
        The &amp;key arguments are followed by the &amp;aux variables.  These
        are local variables that are bound during the evaluation of the
        function body.  It is possible to have initialization
        expressions for the &amp;aux variables.
<p>
    Here is the complete syntax for lambda lists:
<blockquote>
                (<i>rarg</i>...<br>

                 [&amp;optional [<i>oarg</i> | (<i>oarg</i> [<i>init</i> [<i>svar</i>]])]...]<br>

                 [&amp;rest <i>rarg</i>]<br>

                 [&amp;key<br>

                   [<i>karg</i> | ([<i>karg</i> | (<i>key</i> <i>karg</i>)] [<i>init</i> [<i>svar</i>]])]...<br>

                   &amp;allow-other-keys]<br>

                 [&amp;aux<br>

                   [<i>aux</i> | (<i>aux</i> [<i>init</i>])]...])
<p>
            where:
<p>
                <i>rarg</i> is a required argument symbol<br>

                <i>oarg</i> is an &amp;optional argument symbol<br>

                <i>rarg</i> is the &amp;rest argument symbol<br>

                <i>karg</i> is a &amp;key argument symbol<br>

                <i>key</i> is a keyword symbol<br>

                <i>aux</i> is an auxiliary variable symbol<br>

                <i>init</i> is an initialization expression<br>

                <i>svar</i> is a supplied-p variable symbol<br>

</blockquote>
<p>
<a name = "110"><h3>Objects</h3></a><a name="index680">        Definitions:
<ul>
<li>
selector - a symbol used to select an appropriate method
<li>message - a selector and a list of actual arguments
<li>method - the code that implements a message
</ul>
        Since XLISP was created to provide a simple basis for
        experimenting with object-oriented programming, one of the
        primitive data types included is <i>object</i>.  In XLISP, an object
        consists of a data structure containing a pointer to the
        object's class as well as an array containing the values of the
        object's instance variables.
<p>
        Officially, there is no way to see inside an object (look at the
        values of its instance variables).  The only way to communicate
        with an object is by sending it a message.
<p>
        You can send a message to an object using the <code>send</code> function.
        This function takes the object as its first argument, the
        message selector as its second argument (which must be a symbol)
        and the message arguments as its remaining arguments.
<p>
        The <code>send</code> function determines the class of the receiving object
        and attempts to find a method corresponding to the message
        selector in the set of messages defined for that class.  If the
        message is not found in the object's class and the class has a
        super-class, the search continues by looking at the messages
        defined for the super-class.  This process continues from one
        super-class to the next until a method for the message is found.
        If no method is found, an error occurs.
<p>
        A message can also be sent from the body of a method by using
        the current object, but the method lookup starts with the
        object's superclass rather than its class.  This allows a
        subclass to invoke a standard method in its parent class even
        though it overrides that method with its own specialized
        version.
<p>
        When a method is found, the evaluator binds the receiving object
        to the symbol <code>self</code> and evaluates the method using the
        remaining elements of the original list as arguments to the
        method.  These arguments are always evaluated prior to being
        bound to their corresponding formal arguments.  The result of
        evaluating the method becomes the result of the expression.
<p>
<a name = "111"><h3>The ``Object'' Class</h3></a><a name="index681"><code>Object</code><a name="index682"> - the top of the class hierarchy.
<p>
Messages:
<dl>
<dt>
<code>:show<a name="index683"></code> - show an object's instance variables.
<dd>
returns -  the object

<br>
<br><dt><code>:class<a name="index684"></code> - return the class of an object
<dd>
returns -  the class of the object

<br>
<br><dt><code>:isnew<a name="index685"></code> - the default object initialization routine
<dd>
returns -  the object
<br><dt>
<code>:sendsuper<a name="index686"></code> <i>sel</i> <i>args</i>... - send superclass a message
<dd>
<i>sel</i> - the message selector<br>
<i>args</i> - the message arguments<br>
returns -  the result of sending the message

<br>
<br><dt>
</dl>
<p>
<a name = "112"><h3>The ``Class'' Class</h3></a><a name="index687"><code>Class<a name="index688"></code> - class of all object classes (including itself)
<p>
            Messages:
<p>
<dl>
<dt>
                :new<a name="index689"> - create a new instance of a class
<dd>
                    returns -    the new class object

<br>
<br><dt>                :isnew<a name="index690"> <i>ivars</i> [<i>cvars</i> [<i>super</i>]] - initialize a new class
<dd>
                    <i>ivars</i> -    the list of instance variable symbols<br>
                    <i>cvars</i> -    the list of class variable symbols<br>
                    <i>super</i> -    the superclass (default is object)<br>
                    returns -    the new class object

<br>
<br><dt>                :answer<a name="index691"> <i>msg</i> <i>fargs</i> <i>code</i> - add a message to a class
<dd>
                    <i>msg</i> -      the message symbol<br>
                <i>fargs</i> -    the formal argument list (lambda list)<br>
                    <i>code</i> -     a list of executable expressions<br>
                    returns -    the object

<br>
<br><dt>
</dl>
<p>
        When a new instance of a class is created by sending the message
        <code>:new</code> to an existing class, the message <code>:isnew</code> followed by
        whatever parameters were passed to the <code>:new</code> message is sent to
        the newly created object.
<p>
        When a new class is created by sending the <code>:new</code> message to the
        object <code>Class</code>, an optional parameter may be specified
        indicating the superclass of the new class.  If this parameter
        is omitted, the new class will be a subclass of <code>Object</code>.  A
        class inherits all instance variables, class variables, and
        methods from its super-class.
<p>
<a name = "113"><h3>Profiling</h3></a><a name="index692">
The Xlisp 2.0 release has been extended with a profiling facility, which counts how many times and where <code>eval</code> is executed.  A separate count is maintained for each named function, closure, or macro, and a count indicates an <code>eval</code> in the immediately (lexically) enclosing named function, closure, or macro.  Thus, the count gives an indication of the amount of time spent in a function, not counting nested function calls.  The list of all functions executed is maintained on the global <code>*profile*</code> variable.  These functions in turn have <code>*profile*</code> properties, which maintain the counts.  The profile system merely increments counters and puts symbols on the <code>*profile*</code> list.  It is up to the user to initialize data and gather results.  Profiling is turned on or off with the <code>profile</code> function.  Unfortunately, methods cannot be profiled with this facility.
<p>
<a name = "114"><h3>SYMBOLS</h3></a><a name="index693">
<ul>
<li>
<code>self</code> - the current object (within a method context)
<li><code>*obarray*<a name="index694"></code> - the object hash table
<li><code>*standard-input*<a name="index695"></code> - the standard input stream
<li><code>*standard-output*<a name="index696"></code> - the standard output stream
<li><code>*error-output*<a name="index697"></code> - the error output stream
<li><code>*trace-output*<a name="index698"></code> - the trace output stream
<li><code>*debug-io*<a name="index699"></code> - the debug i/o stream
<li><code>*breakenable*<a name="index700"></code> - flag controlling entering break loop on errors
<li><code>*tracelist*<a name="index701"></code> - list of names of functions to trace
<li><code>*tracenable*<a name="index702"></code> - enable trace back printout on errors
<li><code>*tracelimit*<a name="index703"></code> - number of levels of trace back information
<li><code>*evalhook*<a name="index704"></code> - user substitute for the evaluator function
<li><code>*applyhook*<a name="index705"></code> - (not yet implemented)
<li><code>*readtable*<a name="index706"></code> - the current readtable
<li><code>*unbound*<a name="index707"></code> - indicator for unbound symbols
<li><code>*gc-flag*<a name="index708"></code> - controls the printing of gc messages
<li><code>*gc-hook*<a name="index709"></code> - function to call after garbage collection
<li><code>*integer-format*<a name="index710"></code> - format for printing integers (``%d'' or ``%ld'')
<li><code>*float-format*<a name="index711"></code> - format for printing floats (``%g'')
<li><code>*print-case*<a name="index712"></code> - symbol output case (:upcase or :downcase)
</ul>
<p>
        There are several symbols maintained by the read/eval/print
        loop.  The symbols <code>+</code>, <code>++</code>, and <code>+++</code> are bound to the most
        recent three input expressions.  The symbols <code>*</code>, <code>**</code> and <code>***</code>
        are bound to the most recent three results.  The symbol <code>-</code> is
        bound to the expression currently being evaluated.  It becomes
        the value of <code>+</code> at the end of the evaluation.
<a name = "115"><h3>Evaluation Functions</h3></a><a name="index713">
<dl>
<dt>
        (eval<a name="index714"> <i>expr</i>) - evaluate an xlisp expression
<dd>
            <i>expr</i> -     the expression to be evaluated<br>
            returns -     the result of evaluating the expression

<br>
<br><dt>        (apply<a name="index715"> <i>fun</i> <i>args</i>) - apply a function to a list of arguments
<dd>
            <i>fun</i> -      the function to apply (or function symbol)<br>
            <i>args</i> -     the argument list<br>
            returns -    the result of applying the function to the arguments

<br>
<br><dt>        (funcall<a name="index716"> <i>fun</i> <i>arg</i>...) - call a function with arguments
<dd>
            <i>fun</i> -      the function to call (or function symbol)<br>
            <i>arg</i> -      arguments to pass to the function<br>
            returns -    the result of calling the function with the arguments

<br>
<br><dt>        (quote<a name="index717"> <i>expr</i>) -  return an expression unevaluated
<dd>
            <i>expr</i>  -    the expression to be quoted (quoted)<br>
            returns   -  <i>expr</i> unevaluated

<br>
<br><dt>        (function<a name="index718"> <i>expr</i>) -  get the functional interpretation<dd>
            <i>expr</i> -     the symbol or lambda expression (quoted)<br>
            returns  -   the functional interpretation<br>

<br><dt>        (backquote<a name="index719"> <i>expr</i>) - fill in a template<dd>
            <i>expr</i> -     the template<br>
            returns  -   a copy of the template with comma and comma-at<br>
             expressions expanded

<br>
<br><dt>        (lambda<a name="index720"> <i>args</i> <i>expr</i>...) - make a function closure<dd>
            <i>args</i> -     formal argument list (lambda list) (quoted)<br>
            <i>expr</i> -     expressions of the function body<br>
            returns  -   the function closure<br>

<br><dt>        (get-lambda-expression<a name="index721"> <i>closure</i>) - get the lambda expression<dd>
            <i>closure</i> -  the closure<br>
            returns  -   the original lambda expression<br>

<br><dt>        (macroexpand<a name="index722"> <i>form</i>) - recursively expand macro calls<dd>
            <i>form</i> -     the form to expand<br>
            returns  -   the macro expansion<br>

<br><dt>        (macroexpand-1<a name="index723"> <i>form</i>) - expand a macro call<dd>
            <i>form</i> -     the macro call form<br>
            returns  -   the macro expansion<br>

<br><dt>
</dl><a name = "116"><h3>Symbol Functions</h3></a><a name="index724">
<dl>
<dt>
        (set<a name="index725"> <i>sym</i> <i>expr</i>) -  set the value of a symbol
<dd>
            <i>sym</i>  -     the symbol being set<br>
            <i>expr</i> -     the new value<br>
            returns  -   the new value<br>

<br><dt>        (setq<a name="index726"> [<i>sym</i> <i>expr</i>]...) -  set the value of a symbol
<dd>
            <i>sym</i>  -     the symbol being set (quoted)<br>
            <i>expr</i> -     the new value<br>
            returns  -   the new value<br>

<br><dt>        (psetq<a name="index727"> [<i>sym</i> <i>expr</i>]...)  - parallel version of setq
<dd>
            <i>sym</i>  -     the symbol being set (quoted)<br>
            <i>expr</i> -     the new value<br>
            returns  -   the new value<br>

<br><dt>        (setf<a name="index728"> [<i>place</i> <i>expr</i>]...)  - set the value of a field
<dd>
            <i>place</i> -     the field specifier (quoted):<br>
<dl><dd>
  <i>sym</i> -                  set value of a symbol<br>
  (car <i>expr</i>)  -          set car of a cons node<br>
  (cdr <i>expr</i>)  -          set cdr of a cons node<br>
  (nth <i>n</i> <i>expr</i>) -       set nth car of a list<br>
  (aref <i>expr</i> <i>n</i>) -       set nth element of an array<br>
  (get <i>sym</i> <i>prop</i>) -      set value of a property<br>
  (symbol-value <i>sym</i>) -   set value of a symbol<br>
  (symbol-function <i>sym</i>) - set functional value of a symbol<br>
  (symbol-plist <i>sym</i>) -    set property list of a symbol<br>
</dl>
        <i>expr</i> -     the new value<br>
        returns  -   the new value<br>

<br><dt>

        (defun<a name="index729"> <i>sym</i> <i>fargs</i> <i>expr</i>...)  - define a function<br>
        (defmacro<a name="index730"> <i>sym</i> <i>fargs</i> <i>expr</i>...) -  define a macro

<dd>
            <i>sym</i> -      symbol being defined (quoted)<br>
            <i>fargs</i> -     formal argument list (lambda list) (quoted)<br>
            <i>expr</i>  -    expressions constituting the body of the<br>
                        function (quoted)
            returns   -  the function symbol<br>

<br><dt>        (gensym<a name="index731"> [<i>tag</i>])  - generate a symbol
<dd>
            <i>tag</i>   -    string or number<br>
            returns   -  the new symbol<br>

<br><dt>(intern<a name="index732"> <i>pname</i>)  - make an interned symbol
<dd>
            <i>pname</i> -    the symbol's print name string<br>
            returns   -  the new symbol<br>

<br><dt>        (make-symbol<a name="index733"> <i>pname</i>)  - make an uninterned symbol
<dd>
            <i>pname</i> -    the symbol's print name string<br>
            returns   -  the new symbol<br>

<br><dt>        (symbol-name<a name="index734"> <i>sym</i>)  - get the print name of a symbol
<dd>
            <i>sym</i>   -    the symbol<br>
            returns   -  the symbol's print name<br>

<br><dt>    (symbol-value<a name="index735"> <i>sym</i>)  - get the value of a symbol
<dd>
            <i>sym</i>   -    the symbol<br>
            returns   -  the symbol's value<br>

<br><dt>        (symbol-function<a name="index736"> <i>sym</i>)  - get the functional value of a symbol
<dd>
            <i>sym</i>   -    the symbol<br>
            returns   -  the symbol's functional value<br>

<br><dt>        (symbol-plist<a name="index737"> <i>sym</i>)  - get the property list of a symbol
<dd>
            <i>sym</i>   -    the symbol<br>
            returns   -  the symbol's property list<br>

<br><dt>        (hash<a name="index738"> <i>sym</i> <i>n</i>)  - compute the hash index for a symbol
<dd>
            <i>sym</i>   -    the symbol or string<br>
            <i>n</i>     -    the table size (integer)<br>
            returns   -  the hash index (integer)<br>

<br><dt>
</dl><a name = "117"><h3>Property List Functions</h3></a><a name="index739">
<dl>
<dt>
        (get<a name="index740"> <i>sym</i> <i>prop</i>)  - get the value of a property
<dd>
            <i>sym</i>   -    the symbol<br>
            <i>prop</i>  -    the property symbol<br>
            returns   -  the property value or <code>nil</code><br>

<br><dt>        (putprop<a name="index741"> <i>sym</i> <i>val</i> <i>prop</i>)  - put a property onto a property list
<dd>
            <i>sym</i>   -    the symbol<br>
            <i>val</i>   -    the property value<br>
            <i>prop</i>  -    the property symbol<br>
            returns   -  the property value<br>

<br><dt>        (remprop<a name="index742"> <i>sym</i> <i>prop</i>)  - remove a property
<dd>
            <i>sym</i>   -    the symbol<br>
            <i>prop</i>  -    the property symbol<br>
            returns   -  <code>nil</code><br>

<br><dt>
</dl><a name = "118"><h3>Array Functions</h3></a><a name="index743">
<dl>
<dt>
        (aref<a name="index744"> <i>array</i> <i>n</i>)  - get the nth element of an array
<dd>
            <i>array</i> -    the array<br>
            <i>n</i>     -    the array index (integer)<br>
            returns   -  the value of the array element<br>

<br><dt>        (make-array<a name="index745"> <i>size</i>)  - make a new array
<dd>
            <i>size</i>  -    the size of the new array (integer)<br>
            returns   -  the new array<br>

<br><dt>        (vector<a name="index746"> <i>expr</i>...)  - make an initialized vector
<dd>
            <i>expr</i>  -    the vector elements<br>
            returns   -  the new vector<br>

<br><dt>
</dl><a name = "119"><h3>List Functions</h3></a><a name="index747">
<dl>
<dt>
        (car<a name="index748"> <i>expr</i>) -  return the car of a list node
<dd>
            <i>expr</i>  -    the list node<br>
            returns   -  the car of the list node<br>

<br><dt>        (cdr<a name="index749"> <i>expr</i>)  - return the cdr of a list node
<dd>
            <i>expr</i>  -    the list node<br>
            returns   -  the cdr of the list node<br>

<br><dt>        (c<i>xx</i>r<a name="index750"> <i>expr</i>)  - all c<i>xx</i>r combinations
<dd>

<br>
<br><dt>        (c<i>xxx</i>r<a name="index751"> <i>expr</i>)  - all c<i>xxx</i>r combinations
<dd>

<br>
<br><dt>        (c<i>xxxx</i>r<a name="index752"> <i>expr</i>)  - all c<i>xxxx</i>r combinations
<dd>

<br>
<br><dt>        (first<a name="index753"> <i>expr</i>)  -  a synonym for car
<dd>

<br>
<br><dt>        (second<a name="index754"> <i>expr</i>)  - a synonym for cadr
<dd>

<br>
<br><dt>        (third<a name="index755"> <i>expr</i>)  -  a synonym for caddr
<dd>

<br>
<br><dt>        (fourth<a name="index756"> <i>expr</i>)  - a synonym for cadddr
<dd>

<br>
<br><dt>        (rest<a name="index757"> <i>expr</i>)  -   a synonym for cdr
<dd>

<br>
<br><dt>        (cons<a name="index758"> <i>expr1</i> <i>expr2</i>)  - construct a new list node
<dd>
            <i>expr1</i> -    the car of the new list node<br>
            <i>expr2</i> -    the cdr of the new list node<br>
            returns   -  the new list node<br>

<br><dt>        (list<a name="index759"> <i>expr</i>...)  - create a list of values
<dd>
            <i>expr</i>  -    expressions to be combined into a list<br>
            returns   -  the new list<br>

<br><dt>        (append<a name="index760"> <i>expr</i>...)  - append lists
<dd>
            <i>expr</i>  -    lists whose elements are to be appended<br>
            returns   -  the new list<br>

<br><dt>        (reverse<a name="index761"> <i>expr</i>)  - reverse a list
<dd>
            <i>expr</i>  -    the list to reverse<br>
            returns   -  a new list in the reverse order<br>

<br><dt>        (last<a name="index762"> <i>list</i>)  - return the last list node of a list
<dd>
            <i>list</i>  -    the list<br>
            returns   -  the last list node in the list<br>

<br><dt>        (member<a name="index763"> <i>expr</i> <i>list</i> &amp;key :test :test-not)  - find an expression in a list
<dd>
            <i>expr</i>  -    the expression to find<br>
            <i>list</i>  -    the list to search<br>
            :test     -  the test function (defaults to eql)<br>
            :test-not -  the test function (sense inverted)      <br>
            returns   -  the remainder of the list starting with the expression<br>

<br><dt>        (assoc<a name="index764"> <i>expr</i> <i>alist</i> &amp;key :test :test-not)  - find an expression in an a-list
<dd>
            <i>expr</i>  -    the expression to find<br>
            <i>alist</i> -    the association list<br>
            :test     -  the test function (defaults to eql)<br>
            :test-not -  the test function (sense inverted)      <br>
            returns   -  the alist entry or <code>nil</code><br>

<br><dt>        (remove<a name="index765"> <i>expr</i> <i>list</i> &amp;key :test :test-not)  - remove elements from a list
<dd>
            <i>expr</i>  -    the element to remove<br>
            <i>list</i>  -    the list<br>
            :test     -  the test function (defaults to eql)<br>
            :test-not -  the test function (sense inverted)      <br>
            returns   -  copy of list with matching expressions removed<br>

<br><dt>        (remove-if<a name="index766"> <i>test</i> <i>list</i>)  - remove elements that pass test
<dd>
            <i>test</i>  -    the test predicate<br>
            <i>list</i>  -    the list<br>
            returns   -  copy of list with matching elements removed<br>

<br><dt>        (remove-if-not<a name="index767"> <i>test</i> <i>list</i>)  - remove elements that fail test
<dd>
            <i>test</i>  -    the test predicate<br>
            <i>list</i>  -    the list<br>
            returns   -  copy of list with non-matching elements removed<br>

<br><dt>        (length<a name="index768"> <i>expr</i>)  - find the length of a list, vector or string
<dd>
            <i>expr</i>  -    the list, vector or string<br>
            returns   -  the length of the list, vector or string<br>

<br><dt>        (nth<a name="index769"> <i>n</i> <i>list</i>)  - return the nth element of a list
<dd>
            <i>n</i>     -    the number of the element to return (zero origin)<br>
            <i>list</i>  -    the list<br>
            returns   -  the nth element or <code>nil</code> if the list isn't that long<br>

<br><dt>        (nthcdr<a name="index770"> <i>n</i> <i>list</i>)  - return the nth cdr of a list
<dd>
            <i>n</i>     -    the number of the element to return (zero origin)<br>
            <i>list</i>  -    the list<br>
            returns   -  the nth cdr or <code>nil</code> if the list isn't that long<br>

<br><dt>        (mapc<a name="index771"> <i>fcn</i> <i>list1</i> <i>list</i>...)  - apply function to successive cars
<dd>
            <i>fcn</i>   -    the function or function name<br>
            <i>listn</i> -    a list for each argument of the function<br>
            returns   -  the first list of arguments<br>

<br><dt>        (mapcar<a name="index772"> <i>fcn</i> <i>list1</i> <i>list</i>...)  - apply function to successive cars
<dd>
            <i>fcn</i>   -    the function or function name<br>
            <i>listn</i> -    a list for each argument of the function<br>
            returns   -  a list of the values returned<br>

<br><dt>        (mapl<a name="index773"> <i>fcn</i> <i>list1</i> <i>list</i>...)  - apply function to successive cdrs
<dd>
            <i>fcn</i>   -    the function or function name<br>
            <i>listn</i> -    a list for each argument of the function<br>
            returns   -  the first list of arguments<br>

<br><dt>        (maplist<a name="index774"> <i>fcn</i> <i>list1</i> <i>list</i>...)  - apply function to successive cdrs
<dd>
            <i>fcn</i>   -    the function or function name<br>
            <i>listn</i> -    a list for each argument of the function<br>
            returns   -  a list of the values returned<br>

<br><dt>       (subst<a name="index775"> <i>to</i> <i>from</i> <i>expr</i> &amp;key :test :test-not)  - substitute expressions
<dd>
            <i>to</i>    -    the new expression<br>
            <i>from</i>  -    the old expression<br>
            <i>expr</i>  -    the expression in which to do the substitutions<br>
            :test     -  the test function (defaults to eql)<br>
            :test-not -  the test function (sense inverted)      <br>
            returns   -  the expression with substitutions<br>

<br><dt>        (sublis<a name="index776"> <i>alist</i> <i>expr</i> &amp;key :test :test-not)  - substitute with an a-list
<dd>
            <i>alist</i> -    the association list<br>
            <i>expr</i>  -    the expression in which to do the substitutions<br>
            :test     -  the test function (defaults to eql)<br>
            :test-not -  the test function (sense inverted)      <br>
            returns   -  the expression with substitutions<br>

<br><dt>
</dl><a name = "120"><h3>Destructive List Functions</h3></a><a name="index777">
<dl>
<dt>
        (rplaca<a name="index778"> <i>list</i> <i>expr</i>)  - replace the car of a list node
<dd>
            <i>list</i> -     the list node<br>
            <i>expr</i> -     the new value for the car of the list node<br>
            returns  -   the list node after updating the car<br>

<br><dt>        (rplacd<a name="index779"> <i>list</i> <i>expr</i>)  - replace the cdr of a list node
<dd>
            <i>list</i> -     the list node<br>
            <i>expr</i> -     the new value for the cdr of the list node<br>
            returns  -   the list node after updating the cdr<br>

<br><dt>        (nconc<a name="index780"> <i>list</i>...)  - destructively concatenate lists
<dd>
            <i>list</i> -     lists to concatenate<br>
            returns  -   the result of concatenating the lists<br>

<br><dt>        (delete<a name="index781"> <i>expr</i> &amp;key :test :test-not)  - delete elements from a list
<dd>
            <i>expr</i> -     the element to delete<br>
            <i>list</i> -     the list<br>
            :test    -   the test function (defaults to eql)<br>
            :test-not -   the test function (sense inverted)      <br>
            returns   -  the list with the matching expressions deleted<br>

<br><dt>        (delete-if<a name="index782"> <i>test</i> <i>list</i>)  - delete elements that pass test
<dd>
            <i>test</i>  -    the test predicate<br>
            <i>list</i>  -    the list<br>
            returns   -  the list with matching elements deleted<br>

<br><dt>        (delete-if-not<a name="index783"> <i>test</i> <i>list</i>)  - delete elements that fail test
<dd>
            <i>test</i>  -    the test predicate<br>
            <i>list</i>  -    the list<br>
            returns   -  the list with non-matching elements deleted<br>

<br><dt>        (sort<a name="index784"> <i>list</i> <i>test</i>)  - sort a list
<dd>
            <i>list</i>  -    the list to sort<br>
            <i>test</i>  -    the comparison function<br>
            returns   -  the sorted list<br>

<br><dt>
</dl><a name = "121"><h3>Predicate Functions</h3></a><a name="index785">
<dl>
<dt>
	(atom<a name="index786"> <i>expr</i>)  - is this an atom?
<dd>
            <i>expr</i>  -    the expression to check<br>
            returns   - <code>t</code> if the value is an atom, <code>nil</code> otherwise<br>

<br><dt>        (symbolp<a name="index787"> <i>expr</i>)  - is this a symbol?
<dd>
            <i>expr</i>  -    the expression to check<br>
            returns   - <code>t</code> if the expression is a symbol, <code>nil</code> otherwise<br>

<br><dt>        (numberp<a name="index788"> <i>expr</i>)  - is this a number?
<dd>
            <i>expr</i>  -    the expression to check<br>
            returns   - <code>t</code> if the expression is a number, <code>nil</code> otherwise<br>

<br><dt>        (null<a name="index789"> <i>expr</i>)  - is this an empty list?
<dd>
            <i>expr</i>  -    the list to check<br>
            returns   - <code>t</code> if the list is empty, <code>nil</code> otherwise<br>

<br><dt>        (not<a name="index790"> <i>expr</i>)  - is this false?
<dd>
            <i>expr</i>  -    the expression to check<br>
            return    - <code>t</code> if the value is <code>nil</code>, <code>nil</code> otherwise<br>

<br><dt>        (listp<a name="index791"> <i>expr</i>)  - is this a list?
<dd>
            <i>expr</i>  -    the expression to check<br>
            returns   - <code>t</code> if the value is a cons or <code>nil</code>, <code>nil</code> otherwise<br>

<br><dt>        (endp<a name="index792"> <i>list</i>)  - is this the end of a list
<dd>
            <i>list</i>  -    the list<br>
            returns   - <code>t</code> if the value is <code>nil</code>, <code>nil</code> otherwise<br>

<br><dt>        (consp<a name="index793"> <i>expr</i>)  - is this a non-empty list?
<dd>
            <i>expr</i>  -    the expression to check<br>
            returns   - <code>t</code> if the value is a cons, <code>nil</code> otherwise<br>

<br><dt>        (integerp<a name="index794"> <i>expr</i>)  - is this an integer?
<dd>
            <i>expr</i>  -    the expression to check<br>
            returns   - <code>t</code> if the value is an integer, <code>nil</code> otherwise<br>

<br><dt>        (floatp<a name="index795"> <i>expr</i>)  - is this a float?
<dd>
            <i>expr</i>  -    the expression to check<br>
            returns   - <code>t</code> if the value is a float, <code>nil</code> otherwise<br>

<br><dt>        (stringp<a name="index796"> <i>expr</i>)  - is this a string?
<dd>
            <i>expr</i>  -    the expression to check<br>
            returns   - <code>t</code> if the value is a string, <code>nil</code> otherwise<br>

<br><dt>        (characterp<a name="index797"> <i>expr</i>)  - is this a character?
<dd>
            <i>expr</i>  -    the expression to check<br>
            returns   - <code>t</code> if the value is a character, <code>nil</code> otherwise<br>

<br><dt>        (arrayp<a name="index798"> <i>expr</i>)  - is this an array?
<dd>
            <i>expr</i>  -    the expression to check<br>
            returns   - <code>t</code> if the value is an array, <code>nil</code> otherwise<br>

<br><dt>        (streamp<a name="index799"> <i>expr</i>)  - is this a stream?
<dd>
            <i>expr</i>  -    the expression to check<br>
            returns   - <code>t</code> if the value is a stream, <code>nil</code> otherwise<br>

<br><dt>        (objectp<a name="index800"> <i>expr</i>)  - is this an object?
<dd>
            <i>expr</i>  -    the expression to check<br>
            returns   - <code>t</code> if the value is an object, <code>nil</code> otherwise<br>

<br><dt>        (boundp<a name="index801"> <i>sym</i>)  - is a value bound to this symbol?
<dd>
            <i>sym</i>   -    the symbol<br>
            returns   - <code>t</code> if a value is bound to the symbol, <code>nil</code> otherwise<br>

<br><dt>        (fboundp<a name="index802"> <i>sym</i>)  - is a functional value bound to this symbol?
<dd>
            <i>sym</i>   -    the symbol<br>
            returns   - <code>t</code> if a functional value is bound to the symbol,<br>
                        <code>nil</code> otherwise

<br>
<br><dt>        (minusp<a name="index803"> <i>expr</i>)  - is this number negative?
<dd>
            <i>expr</i>  -    the number to test<br>
            returns   - <code>t</code> if the number is negative, <code>nil</code> otherwise<br>

<br><dt>        (zerop<a name="index804"> <i>expr</i>)  - is this number zero?
<dd>
            <i>expr</i>  -    the number to test<br>
            returns   - <code>t</code> if the number is zero, <code>nil</code> otherwise<br>

<br><dt>        (plusp<a name="index805"> <i>expr</i>)  - is this number positive?
<dd>
            <i>expr</i>  -    the number to test<br>
            returns   - <code>t</code> if the number is positive, <code>nil</code> otherwise<br>

<br><dt>        (evenp<a name="index806"> <i>expr</i>)  - is this integer even?
<dd>
            <i>expr</i>  -    the integer to test<br>
            returns   - <code>t</code> if the integer is even, <code>nil</code> otherwise<br>

<br><dt>        (oddp<a name="index807"> <i>expr</i>)  - is this integer odd?
<dd>
            <i>expr</i>  -    the integer to test<br>
            returns   - <code>t</code> if the integer is odd, <code>nil</code> otherwise<br>

<br><dt>        (eq<a name="index808"> <i>expr1</i> <i>expr2</i>)  - are the expressions identical?
<dd>
            <i>expr1</i> -    the first expression<br>
            <i>expr2</i> -    the second expression<br>
            returns   - <code>t</code> if they are equal, <code>nil</code> otherwise<br>

<br><dt>(eql<a name="index809"> <i>expr1</i> <i>expr2</i>)  - are the expressions
identical? (works with all numbers)
<dd>
            <i>expr1</i> -    the first expression<br>
            <i>expr2</i> -    the second expression<br>
            returns   - <code>t</code> if they are equal, <code>nil</code> otherwise<br>

<br><dt>        (equal<a name="index810"> <i>expr1</i> <i>expr2</i>)  - are the expressions equal?
<dd>
            <i>expr1</i> -    the first expression<br>
            <i>expr2</i> -    the second expression<br>
            returns   - <code>t</code> if they are equal, <code>nil</code> otherwise<br>

<br><dt>
</dl><a name = "122"><h3>Control Constructs</h3></a><a name="index811">
<dl>
<dt>
        (cond<a name="index812"> <i>pair</i>...)  - evaluate conditionally
<dd>
            <i>pair</i>  -    pair consisting of:<br>
<dl><dd>
                            (<i>pred</i> <i>expr</i>...)
</dl>
                          where:
<dl><dd>
                            <i>pred</i> -     is a predicate expression<br>
                            <i>expr</i> -     evaluated if the predicate
 is not <code>nil</code>
</dl>
returns  -   the value of the first expression whose predicate is not
<code>nil</code>

<br>
<br><dt>        (and<a name="index813"> <i>expr</i>...)  - the logical and of a list of expressions
<dd>
            <i>expr</i> -     the expressions to be anded<br>
            returns  -   <code>nil</code> if any expression evaluates to <code>nil</code>,
                        otherwise the value of the last expression
                        (evaluation of expressions stops after the first
                         expression that evaluates to <code>nil</code>)

<br>
<br><dt>        (or<a name="index814"> <i>expr</i>...)  - the logical or of a list of expressions
<dd>
            <i>expr</i> -     the expressions to be ored<br>
            returns  -   <code>nil</code> if all expressions evaluate to <code>nil</code>,
                  otherwise the value of the first non-<code>nil</code> expression
                        (evaluation of expressions stops after the first
                         expression that does not evaluate to <code>nil</code>)

<br>
<br><dt>        (if<a name="index815"> <i>texpr</i> <i>expr1</i> [<i>expr2</i>])  - evaluate expressions conditionally
<dd>
            <i>texpr</i> -    the test expression<br>
            <i>expr1</i> -    the expression to be evaluated if texpr is non-<code>nil</code><br>
            <i>expr2</i> -    the expression to be evaluated if texpr is <code>nil</code><br>
            returns   -  the value of the selected expression<br>

<br><dt>        (when<a name="index816"> <i>texpr</i> <i>expr</i>...)  - evaluate only when a condition is true
<dd>
            <i>texpr</i> -    the test expression<br>
            <i>expr</i>  -    the expression(s) to be evaluated if texpr is non-<code>nil</code><br>
            returns - the value of the last expression or <code>nil</code>

<br>
<br><dt>        (unless<a name="index817"> <i>texpr</i> <i>expr</i>...)  - evaluate only when a condition is false
<dd>
            <i>texpr</i> -    the test expression<br>
            <i>expr</i>  -    the expression(s) to be evaluated if texpr is <code>nil</code><br>
            returns   -  the value of the last expression or <code>nil</code><br>

<br><dt>          (case<a name="index818"> <i>expr</i> <i>case</i>...)  - select by case
<dd>
            <i>expr</i>  -    the selection expression<br>
            <i>case</i>  -    pair consisting of:<br>
<dl><dd>
                            (<i>value</i> <i>expr</i>...)
</dl>
                          where:
<dl><dd>
                            <i>value</i> -     is a single expression or a list of
                                        expressions (unevaluated)<br>
                            <i>expr</i>  -    are expressions to execute if the
                                        case matches
</dl>
            returns -     the value of the last expression of the matching case<br>

<br><dt>

       (let<a name="index819"> (<i>binding</i>...) <i>expr</i>...)  - create local bindings<br>
        (let*<a name="index820"> (<i>binding</i>...) <i>expr</i>...)  - let with sequential binding

<dd>
            <i>binding</i> -   the variable bindings each of which is either:<br>
<dl><dd>
                        1)  a symbol (which is initialized to <code>nil</code>)<br>
                        2)  a list whose car is a symbol and whose cadr
                                is an initialization expression
</dl>
            <i>expr</i> -     the expressions to be evaluated<br>
            returns  -   the value of the last expression<br>

<br><dt>

        (flet<a name="index821"> (<i>binding</i>...) <i>expr</i>...)  - create local functions<br>
        (labels<a name="index822"> (<i>binding</i>...) <i>expr</i>...) -  flet with recursive functions<br>
        (macrolet<a name="index823"> (<i>binding</i>...) <i>expr</i>...) -  create local macros

<dd>
            <i>binding</i> -  the function bindings each of which is:<br>
<dl><dd>
                          (<i>sym</i> <i>fargs</i> <i>expr</i>...)
</dl>
                        where:
<dl><dd>
                            <i>sym</i> -      the function/macro name<br>
                            <i>fargs</i> -     formal argument list (lambda list)<br>
                            <i>expr</i>  -    expressions constituting the body of
                                        the function/macro
</dl>
            <i>expr</i> -     the expressions to be evaluated<br>
            returns  -   the value of the last expression

<br>
<br><dt>        (catch<a name="index824"> <i>sym</i> <i>expr</i>...)  - evaluate expressions and catch throws
<dd>
            <i>sym</i>  -     the catch tag<br>
            <i>expr</i> -     expressions to evaluate<br>
            returns  -   the value of the last expression the throw expression<br>

<br><dt>        (throw<a name="index825"> <i>sym</i> [<i>expr</i>])  - throw to a catch
<dd>
            <i>sym</i>  -     the catch tag<br>
            <i>expr</i> -     the value for the catch to return (defaults to <code>nil</code>)<br>
            returns  -   never returns<br>

<br><dt>        (unwind-protect<a name="index826"> <i>expr</i> <i>cexpr</i>...)  - protect evaluation of an expression
<dd>
            <i>expr</i> -     the expression to protect<br>
            <i>cexpr</i> -     the cleanup expressions<br>
            returns   -  the value of the expression<br>
          Note:  unwind-protect guarantees to execute the cleanup expressions
                 even if a non-local exit terminates the evaluation of the
                 protected expression

<br>
<br><dt>
</dl>
<p>
<a name = "123"><h3>Looping Constructs</h3></a><a name="index827">
<dl>
<dt>
        (loop<a name="index828"> <i>expr</i>...)  - basic looping form
<dd>
            <i>expr</i> -     the body of the loop<br>
            returns  -   never returns (must use non-local exit)<br>

<br><dt>

        (do<a name="index829"> (<i>binding</i>...) (<i>texpr</i> <i>rexpr</i>...) <i>expr</i>...)<br>
        (do*<a name="index830"> (<i>binding</i>...) (<i>texpr</i> <i>rexpr</i>...) <i>expr</i>...)

<dd>
            <i>binding</i> -  the variable bindings each of which is either:<br>
<dl><dd>
                        1)  a symbol (which is initialized to <code>nil</code>)<br>
                        2)  a list of the form: (<i>sym</i> <i>init</i> [<i>step</i>])
                            where:
<dl><dd>
                                <i>sym</i> - is the symbol to bind<br>
                                <i>init</i> - is the initial value of the symbol<br>
                                <i>step</i> - is a step expression<br>
</dl>
</dl>
            <i>texpr</i> -    the termination test expression<br>
            <i>rexpr</i> -    result expressions (the default is <code>nil</code>)<br>
            <i>expr</i>  -    the body of the loop (treated like an implicit prog)<br>
            returns   -  the value of the last result expression<br>

<br><dt>    (dolist<a name="index831"> (<i>sym</i> <i>expr</i> [<i>rexpr</i>]) <i>expr</i>...)  - loop through a list
<dd>
            <i>sym</i>   -    the symbol to bind to each list element<br>
            <i>expr</i>  -    the list expression<br>
            <i>rexpr</i> -    the result expression (the default is <code>nil</code>)<br>
            <i>expr</i>  -    the body of the loop (treated like an implicit prog)<br>

<br><dt>        (dotimes<a name="index832"> (<i>sym</i> <i>expr</i> [<i>rexpr</i>]) <i>expr</i>...)  - loop from zero to n-1
<dd>
            <i>sym</i>   -    the symbol to bind to each value from 0 to n-1<br>
            <i>expr</i>  -    the number of times to loop<br>
            <i>rexpr</i> -    the result expression (the default is <code>nil</code>)<br>
            <i>expr</i>  -    the body of the loop (treated like an implicit prog)<br>

<br><dt>
</dl><a name = "124"><h3>The Program Feature</h3></a><a name="index833">
<dl>
<dt>

(prog<a name="index834"> (<i>binding</i>...) <i>expr</i>...)  - the program feature<br>
(prog*<a name="index835"> (<i>binding</i>...) <i>expr</i>...)  - prog with sequential binding

<dd>
            <i>binding</i> -  the variable bindings each of which is either:<br>
<dl><dd>
                        1)  a symbol (which is initialized to <code>nil</code>)<br>
                        2)  a list whose car is a symbol and whose cadr
                                is an initialization expression
</dl>
            <i>expr</i>  -    expressions to evaluate or tags (symbols)<br>
            returns   -  <code>nil</code> or the argument passed to the return function<br>

<br><dt>        (block<a name="index836"> <i>name</i> <i>expr</i>...)  - named block
<dd>
            <i>name</i>  -    the block name (symbol)<br>
            <i>expr</i>  -    the block body<br>
            returns   -  the value of the last expression<br>

<br><dt>        (return<a name="index837"> [<i>expr</i>])  - cause a prog construct to return a value
<dd>
            <i>expr</i>  -    the value (defaults to <code>nil</code>)<br>
            returns   -  never returns<br>

<br><dt>        (return-from<a name="index838"> <i>name</i> [<i>value</i>])  - return from a named block
<dd>
            <i>name</i>  -    the block name (symbol)<br>
            <i>value</i> -    the value to return (defaults to <code>nil</code>)<br>
            returns   -  never returns<br>

<br><dt>        (tagbody<a name="index839"> <i>expr</i>...)  - block with labels
<dd>
            <i>expr</i>  -    expression(s) to evaluate or tags (symbols)<br>
            returns   -  <code>nil</code><br>

<br><dt>        (go<a name="index840"> <i>sym</i>)  - go to a tag within a tagbody or prog
<dd>
            <i>sym</i>   -    the tag (quoted)<br>
            returns   -  never returns<br>

<br><dt>        (progv<a name="index841"> <i>slist</i> <i>vlist</i> <i>expr</i>...)  - dynamically bind symbols
<dd>
            <i>slist</i> -    list of symbols<br>
            <i>vlist</i> -    list of values to bind to the symbols<br>
            <i>expr</i>  -    expression(s) to evaluate<br>
            returns   -  the value of the last expression<br>

<br><dt>        (prog1<a name="index842"> <i>expr1</i> <i>expr</i>...)  - execute expressions sequentially
<dd>
            <i>expr1</i> -    the first expression to evaluate<br>
            <i>expr</i>  -    the remaining expressions to evaluate<br>
            returns   -  the value of the first expression<br>

<br><dt>        (prog2<a name="index843"> <i>expr1</i> <i>expr2</i> <i>expr</i>...)  - execute expressions sequentially
<dd>
            <i>expr1</i> -    the first expression to evaluate<br>
            <i>expr2</i> -    the second expression to evaluate<br>
            <i>expr</i>  -    the remaining expressions to evaluate<br>
            returns   -  the value of the second expression<br>

<br><dt>        (progn<a name="index844"> <i>expr</i>...)  - execute expressions sequentially
<dd>
            <i>expr</i>  -    the expressions to evaluate<br>
            returns   -  the value of the last expression (or <code>nil</code>)<br>

<br><dt>
</dl><a name = "125"><h3>Debugging and Error Handling</h3></a><a name="index845"><a name="index846">
<dl>
<dt>
        (trace<a name="index847"> <i>sym</i>)  - add a function to the trace list
<dd>
            <i>sym</i>   -    the function to add (quoted)<br>
            returns   -  the trace list<br>

<br><dt>        (untrace<a name="index848"> <i>sym</i>)  - remove a function from the trace list
<dd>
            <i>sym</i>   -    the function to remove (quoted)<br>
            returns   -  the trace list<br>

<br><dt>        (error<a name="index849"> <i>emsg</i> [<i>arg</i>])  - signal a non-correctable error
<dd>
            <i>emsg</i>  -    the error message string<br>
            <i>arg</i>   -    the argument expression (printed after the message)<br>
            returns   -  never returns<br>

<br><dt>        (cerror<a name="index850"> <i>cmsg</i> <i>emsg</i> [<i>arg</i>])  - signal a correctable error
<dd>
            <i>cmsg</i>  -    the continue message string<br>
            <i>emsg</i>  -    the error message string<br>
            <i>arg</i>   -    the argument expression (printed after the message)<br>
            returns   -  <code>nil</code> when continued from the break loop<br>

<br><dt>        (break<a name="index851"> [<i>bmsg</i> [<i>arg</i>]])  - enter a break loop
<dd>
            <i>bmsg</i>  -    the break message string (defaults to <code>**break**</code>)<br>
            <i>arg</i>   -    the argument expression (printed after the message)<br>
            returns   -  <code>nil</code> when continued from the break loop<br>

<br><dt>        (clean-up<a name="index852">)  - clean-up after an error
<dd>
            returns   -  never returns<br>

<br><dt>        (top-level<a name="index853">)  - clean-up after an error and return to the top level
<dd>
            returns   -  never returns<br>

<br><dt>        (continue<a name="index854">)  - continue from a correctable error
<dd>
            returns   -  never returns<br>

<br><dt>        (errset<a name="index855"> <i>expr</i> [<i>pflag</i>])  - trap errors
<dd>
            <i>expr</i>  -    the expression to execute<br>
            <i>pflag</i> -    flag to control printing of the error message<br>
            returns   -  the value of the last expression consed with <code>nil</code><br>
                        or <code>nil</code> on error

<br>
<br><dt>        (baktrace<a name="index856"><a name="index857"><a name="index858"> [<i>n</i>])  - print n levels of trace back information
<dd>
            <i>n</i>     -    the number of levels (defaults to all levels)<br>
            returns   -  <code>nil</code><br>

<br><dt>        (evalhook<a name="index859"> <i>expr</i> <i>ehook</i> <i>ahook</i> [<i>env</i>])  - evaluate with hooks
<dd>
            <i>expr</i>  -    the expression to evaluate<br>
            <i>ehook</i> -    the value for <code>*evalhook*</code><br>
            <i>ahook</i> -    the value for <code>*applyhook*</code><br>
            <i>env</i>   -    the environment (default is <code>nil</code>)<br>
            returns   -  the result of evaluating the expression<br>

<br><dt>        (profile<a name="index860"> <i>flag</i>) <a href = "foot.html#foot3">(Footnote 3)</a>   - turn profiling on or off.
<dd>
            <i>flag</i>   -    <code>nil</code> turns profiling off, otherwise on<br>
            returns   -  the previous state of profiling.<br>

<br><dt>
</dl><a name = "126"><h3>Arithmetic Functions</h3></a><a name="index861">
<dl>
<dt>
        (truncate<a name="index862"> <i>expr</i>)  - truncates a floating point number to an integer
<dd>
            <i>expr</i>  -    the number<br>
            returns   -  the result of truncating the number<br>

<br><dt>        (float<a name="index863"> <i>expr</i>)  - converts an integer to a floating point number
<dd>
            <i>expr</i>  -    the number<br>
            returns   -  the result of floating the integer<br>

<br><dt>        (+<a name="index864"> <i>expr</i>...)  - add a list of numbers
<dd>
            <i>expr</i>  -    the numbers<br>
            returns   -  the result of the addition<br>

<br><dt>        (-<a name="index865"> <i>expr</i>...)  - subtract a list of numbers or negate a single number
<dd>
            <i>expr</i>  -    the numbers<br>
            returns   -  the result of the subtraction<br>

<br><dt>        (*<a name="index866"> <i>expr</i>...)  - multiply a list of numbers
<dd>
            <i>expr</i>  -    the numbers<br>
            returns   -  the result of the multiplication<br>

<br><dt>        (/<a name="index867"> <i>expr</i>...)  - divide a list of numbers
<dd>
            <i>expr</i>  -    the numbers<br>
            returns   -  the result of the division<br>

<br><dt>        (1+<a name="index868"> <i>expr</i>)  - add one to a number
<dd>
            <i>expr</i>  -    the number<br>
            returns   -  the number plus one<br>

<br><dt>        (1-<a name="index869"> <i>expr</i>)  - subtract one from a number
<dd>
            <i>expr</i>  -    the number<br>
            returns   -  the number minus one<br>

<br><dt>        (rem<a name="index870"><a name="index871"><a name="index872"> <i>expr</i>...)  - remainder of a list of numbers
<dd>
            <i>expr</i>  -    the numbers<br>
            returns   -  the result of the remainder operation<br>

<br><dt>        (min<a name="index873"><a name="index874"> <i>expr</i>...)  - the smallest of a list of numbers
<dd>
            <i>expr</i>  -    the expressions to be checked<br>
            returns   -  the smallest number in the list<br>

<br><dt>        (max<a name="index875"><a name="index876"> <i>expr</i>...)  - the largest of a list of numbers
<dd>
            <i>expr</i>  -    the expressions to be checked<br>
            returns   -  the largest number in the list<br>

<br><dt>        (abs<a name="index877"> <i>expr</i>)  - the absolute value of a number
<dd>
            <i>expr</i>  -    the number<br>
            returns   -  the absolute value of the number<br>

<br><dt>        (gcd<a name="index878"> <i>n1</i> <i>n2</i>...)  - compute the greatest common divisor
<dd>
            <i>n1</i>    -    the first number (integer)<br>
            <i>n2</i>    -    the second number(s) (integer)<br>
            returns   -  the greatest common divisor<br>

<br><dt>       (random<a name="index879"> <i>n</i>)  - compute a random number between 1 and n-1
<dd>
            <i>n</i>     -    the upper bound (integer)<br>
            returns   -  a random number<br>

<br><dt>        (sin<a name="index880"> <i>expr</i>)  - compute the sine of a number
<dd>
            <i>expr</i>  -    the floating point number<br>
            returns   -  the sine of the number<br>

<br><dt>        (cos<a name="index881"> <i>expr</i>)  - compute the cosine of a number
<dd>
            <i>expr</i>  -    the floating point number<br>
            returns   -  the cosine of the number<br>

<br><dt>        (tan<a name="index882"> <i>expr</i>)  - compute the tangent of a number
<dd>
            <i>expr</i>  -    the floating point number<br>
            returns   -  the tangent of the number<br>

<br><dt>        (expt<a name="index883"> <i>x-expr</i> <i>y-expr</i>)  - compute x to the y power
<dd>
            <i>x-expr</i> -    the floating point number<br>
            <i>y-expr</i> -   the floating point exponent<br>
            returns    - x to the y power<br>

<br><dt>        (exp<a name="index884"> <i>x-expr</i>)  - compute e to the x power
<dd>
            <i>x-expr</i> -   the floating point number<br>
            returns   -  e to the x power<br>

<br><dt>        (sqrt<a name="index885"> <i>expr</i>)  - compute the square root of a number
<dd>
            <i>expr</i>  -    the floating point number<br>
            returns   -  the square root of the number<br>

<br><dt>

(&lt<a name="index886"> <i>n1</i> <i>n2</i>...)  - test for less than<br>
(&lt=<a name="index887"> <i>n1</i> <i>n2</i>...) -  test for less than or equal to<br>
(=<a name="index888"> <i>n1</i> <i>n2</i>...)  - test for equal to<br>
(/=<a name="index889"> <i>n1</i> <i>n2</i>...) -  test for not equal to<br>
(&gt=<a name="index890"> <i>n1</i> <i>n2</i>...) -   test for greater than or equal to<br>
(&gt<a name="index891"> <i>n1</i> <i>n2</i>...) -   test for greater than

<dd>
            <i>n1</i>    -    the first number to compare<br>
            <i>n2</i>    -    the second number to compare<br>
returns   -  <code>t</code> if the results of comparing <i>n1</i> with <i>n2</i>,
<i>n2</i> with <i>n3</i>, etc., are all true.<br>

<br><dt>
</dl><a name = "127"><h3>Bitwise Logical Functions</h3></a><a name="index892">
<dl>
<dt>
        (logand<a name="index893"> <i>expr</i>...) -  the bitwise and of a list of numbers
<dd>
            <i>expr</i>  -    the numbers<br>
            returns   -  the result of the and operation<br>

<br><dt>        (logior<a name="index894"> <i>expr</i>...)  - the bitwise inclusive or of a list of numbers
<dd>
            <i>expr</i>  -    the numbers<br>
            returns   -  the result of the inclusive or operation<br>

<br><dt>        (logxor<a name="index895"> <i>expr</i>...)  - the bitwise exclusive or of a list of numbers
<dd>
            <i>expr</i>  -    the numbers<br>
            returns   -  the result of the exclusive or operation<br>

<br><dt>        (lognot<a name="index896"> <i>expr</i>)  - the bitwise not of a number
<dd>
            <i>expr</i>  -    the number<br>
            returns   -  the bitwise inversion of number<br>

<br><dt>
</dl><a name = "128"><h3>String Functions</h3></a><a name="index897">
<dl>
<dt>
        (string<a name="index898"> <i>expr</i>) -  make a string from an integer ascii value
<dd>
            <i>expr</i>  -    the integer<br>
            returns   -  a one character string<br>

<br><dt>        (string-search<a name="index899"> <i>pat</i> <i>str</i> &amp;key :start :end) <a href = "foot.html#foot4">(Footnote 4)</a>   - search for pattern in string
<dd>
            <i>pat</i>   -    a string to search for<br>
            <i>str</i>   -    the string to be searched<br>
            :start    -  the starting offset in str<br>
            :end      -  the ending offset + 1<br>
            returns   -  index of pat in str or NIL if not found<br>

<br><dt>        (string-trim<a name="index900"> <i>bag</i> <i>str</i>)  - trim both ends of a string
<dd>
            <i>bag</i>   -    a string containing characters to trim<br>
            <i>str</i>   -    the string to trim<br>
            returns   -  a trimed copy of the string<br>

<br><dt>        (string-left-trim<a name="index901"> <i>bag</i> <i>str</i>)  - trim the left end of a string
<dd>
            <i>bag</i>   -    a string containing characters to trim<br>
            <i>str</i>   -    the string to trim<br>
            returns   -  a trimed copy of the string<br>

<br><dt>        (string-right-trim<a name="index902"> <i>bag</i> <i>str</i>)  - trim the right end of a string
<dd>
            <i>bag</i>   -    a string containing characters to trim<br>
            <i>str</i>   -    the string to trim<br>
            returns   -  a trimed copy of the string<br>

<br><dt>        (string-upcase<a name="index903"> <i>str</i> &amp;key :start :end)  - convert to uppercase
<dd>
            <i>str</i>   -    the string<br>
            :start    -  the starting offset<br>
            :end      -  the ending offset + 1<br>
            returns   -  a converted copy of the string<br>

<br><dt>        (string-downcase<a name="index904"> <i>str</i> &amp;key :start :end)  - convert to lowercase
<dd>
            <i>str</i>   -    the string<br>
            :start    -  the starting offset<br>
            :end      -  the ending offset + 1<br>
            returns   -  a converted copy of the string<br>

<br><dt>        (nstring-upcase<a name="index905"> <i>str</i> &amp;key :start :end)  - convert to uppercase
<dd>
            <i>str</i>   -    the string<br>
            :start    -  the starting offset<br>
            :end      -  the ending offset + 1<br>
            returns   -  the converted string (not a copy)<br>

<br><dt>        (nstring-downcase<a name="index906"> <i>str</i> &amp;key :start :end)  - convert to lowercase
<dd>
            <i>str</i>   -    the string<br>
            :start    -  the starting offset<br>
            :end      -  the ending offset + 1<br>
            returns  -   the converted string (not a copy)<br>

<br><dt>        (strcat<a name="index907"><a name="index908"> <i>expr</i>...)  - concatenate strings
<dd>
            <i>expr</i> -     the strings to concatenate<br>
            returns  -   the result of concatenating the strings<br>

<br><dt>        (subseq<a name="index909"> <i>string</i> <i>start</i> [<i>end</i>])  - extract a substring
<dd>
            <i>string</i> -   the string<br>
            <i>start</i>  -   the starting position (zero origin)<br>
            <i>end</i>    -   the ending position + 1 (defaults to end)<br>
            returns    - substring between <i>start</i> and <i>end</i><br>

<br><dt>

        (string&lt<a name="index910"> <i>str1</i> <i>str2</i> &amp;key :start1 :end1 :start2 :end2)<br>
        (string&lt=<a name="index911"> <i>str1</i> <i>str2</i> &amp;key :start1 :end1 :start2 :end2)<br>
        (string=<a name="index912"> <i>str1</i> <i>str2</i> &amp;key :start1 :end1 :start2 :end2)<br>
        (string/=<a name="index913"> <i>str1</i> <i>str2</i> &amp;key :start1 :end1 :start2 :end2)<br>
        (string&gt=<a name="index914"> <i>str1</i> <i>str2</i> &amp;key :start1 :end1 :start2 :end2)<br>
        (string&gt<a name="index915"> <i>str1</i> <i>str2</i> &amp;key :start1 :end1 :start2 :end2)

<dd>
            <i>str1</i> -     the first string to compare<br>
            <i>str2</i> -     the second string to compare<br>
            :start1  -   first substring starting offset<br>
            :end1    -   first substring ending offset + 1<br>
            :start2  -   second substring starting offset<br>
            :end2    -   second substring ending offset + 1<br>
            returns  -   <code>t</code> if predicate is true, <code>nil</code> otherwise<br>
          Note: case is significant with these comparison functions.

<br>
<br><dt>

(string-lessp<a name="index916"> <i>str1</i> <i>str2</i> &amp;key :start1 :end1 :start2 :end2)<br>
(string-not-greaterp<a name="index917"> <i>str1</i> <i>str2</i> &amp;key :start1 :end1 :start2 :end2)<br>
(string-equalp<a name="index918"> <i>str1</i> <i>str2</i> &amp;key :start1 :end1 :start2 :end2)<br>
(string-not-equalp<a name="index919"> <i>str1</i> <i>str2</i> &amp;key :start1 :end1 :start2 :end2)<br>
(string-not-lessp<a name="index920"> <i>str1</i> <i>str2</i> &amp;key :start1 :end1 :start2 :end2)<br>
(string-greaterp <i>str1</i> <i>str2</i> &amp;key :start1 :end1 :start2 :end2)

<dd>
            <i>str1</i> -     the first string to compare<br>
            <i>str2</i> -     the second string to compare<br>
            :start1  -   first substring starting offset<br>
            :end1    -   first substring ending offset + 1<br>
            :start2  -   second substring starting offset<br>
            :end2    -   second substring ending offset + 1<br>
    returns  -   <code>t</code> if predicate is true, <code>nil</code> otherwise<br>
          Note: case is not significant with these comparison functions.

<br>
<br><dt>
</dl>
<p>
<a name = "129"><h3>Character Functions</h3></a><a name="index921">
<dl>
<dt>
        (char<a name="index922"> <i>string</i> <i>index</i>) -  extract a character from a string
<dd>
            <i>string</i> -   the string<br>
            <i>index</i>  -   the string index (zero relative)<br>
            returns    - the ascii code of the character<br>

<br><dt>        (upper-case-p<a name="index923"> <i>chr</i>)  - is this an upper case character?
<dd>
            <i>chr</i> -      the character<br>
            returns -    <code>t</code> if the character is upper case, <code>nil</code> otherwise<br>

<br><dt>        (lower-case-p<a name="index924"> <i>chr</i>)  - is this a lower case character?
<dd>
            <i>chr</i> -      the character<br>
            returns -    <code>t</code> if the character is lower case, <code>nil</code> otherwise<br>

<br><dt>        (both-case-p<a name="index925"> <i>chr</i>)  - is this an alphabetic (either case) character?
<dd>
            <i>chr</i> -      the character<br>
            returns -    <code>t</code> if the character is alphabetic, <code>nil</code> otherwise<br>

<br><dt>        (digit-char-p<a name="index926"> <i>chr</i>)  - is this a digit character?
<dd>
            <i>chr</i> -      the character<br>
            returns -    the digit weight if character is a digit, <code>nil</code> otherwise<br>

<br><dt>        (char-code<a name="index927"> <i>chr</i>)  - get the ascii code of a character
<dd>
            <i>chr</i> -      the character<br>
            returns -    the ascii character code (integer)<br>

<br><dt>        (code-char<a name="index928"> <i>code</i>)  - get the character with a specified ascii code
<dd>
            <i>code</i> -     the ascii code (integer)<br>
            returns  -   the character with that code or <code>nil</code><br>

<br><dt>        (char-upcase<a name="index929"> <i>chr</i>)  - convert a character to upper case
<dd>
            <i>chr</i>  -     the character<br>
            returns  -   the upper case character<br>

<br><dt>        (char-downcase<a name="index930"> <i>chr</i>)  - convert a character to lower case
<dd>
            <i>chr</i>  -     the character<br>
            returns  -   the lower case character<br>

<br><dt>        (digit-char<a name="index931"> <i>n</i>)  - convert a digit weight to a digit
<dd>
            <i>n</i>    -     the digit weight (integer)<br>
            returns  -   the digit character or <code>nil</code><br>

<br><dt>        (char-int<a name="index932"> <i>chr</i>)  - convert a character to an integer
<dd>
            <i>chr</i>  -     the character<br>
            returns  -   the ascii character code<br>

<br><dt>        (int-char<a name="index933"> <i>int</i>)  - convert an integer to a character
<dd>
            <i>int</i>  -     the ascii character code<br>
            returns  -   the character with that code<br>

<br><dt>

       (char&lt<a name="index934"> <i>chr1</i> <i>chr2</i>...)<br>
        (char&lt=<a name="index935"> <i>chr1</i> <i>chr2</i>...)<br>
        (char=<a name="index936"> <i>chr1</i> <i>chr2</i>...)<br>
        (char/=<a name="index937"> <i>chr1</i> <i>chr2</i>...)<br>
        (char&gt=<a name="index938"> <i>chr1</i> <i>chr2</i>...)<br>
        (char&gt<a name="index939"> <i>chr1</i> <i>chr2</i>...)

<dd>
            <i>chr1</i> -     the first character to compare<br>
            <i>chr2</i> -     the second character(s) to compare<br>
            returns  -   <code>t</code> if predicate is true, <code>nil</code> otherwise<br>
          Note: case is significant with these comparison functions.

<br>
<br><dt>

(char-lessp<a name="index940"> <i>chr1</i> <i>chr2</i>...)<br>
(char-not-greaterp<a name="index941"> <i>chr1</i> <i>chr2</i>...)<br>
(char-equalp<a name="index942"> <i>chr1</i> <i>chr2</i>...)<br>
(char-not-equalp<a name="index943"> <i>chr1</i> <i>chr2</i>...)<br>
(char-not-lessp<a name="index944"> <i>chr1</i> <i>chr2</i>...)<br>
(char-greaterp<a name="index945"> <i>chr1</i> <i>chr2</i>...)

<dd>
<i>chr1</i> -     the first string to compare<br>
<i>chr2</i> -     the second string(s) to compare<br>
returns  -   <code>t</code> if predicate is true, <code>nil</code> otherwise<br>

<br><dt>
          Note: case is not significant with these comparison functions.
</dl>
<p>
<a name = "130"><h3>Input/Output Functions</h3></a><a name="index946">
<dl>
<dt>
        (read<a name="index947"> [<i>stream</i> [<i>eof</i> [<i>rflag</i>]]])  - read an expression
<dd>
            <i>stream</i> -   the input stream (default is standard input)<br>
            <i>eof</i>    -   the value to return on end of file (default is <code>nil</code>)<br>
            <i>rflag</i>  -   recursive read flag (default is <code>nil</code>)<br>
            returns    - the expression read<br>

<br><dt>        (print<a name="index948"> <i>expr</i> [<i>stream</i>])  - print an expression on a new line
<dd>
            <i>expr</i>   -   the expression to be printed<br>
            <i>stream</i> -   the output stream (default is standard output)<br>
            returns    - the expression<br>

<br><dt>        (prin1<a name="index949"> <i>expr</i> [<i>stream</i>])  - print an expression
<dd>
            <i>expr</i>   -   the expression to be printed<br>
            <i>stream</i> -   the output stream (default is standard output)<br>
            returns    - the expression<br>

<br><dt>        (princ<a name="index950"> <i>expr</i> [<i>stream</i>])  - print an expression without quoting
<dd>
            <i>expr</i>   -   the expressions to be printed<br>
            <i>stream</i> -   the output stream (default is standard output)<br>
            returns   -  the expression<br>

<br><dt>        (pprint<a name="index951"> <i>expr</i> [<i>stream</i>])  - pretty print an expression
<dd>
            <i>expr</i>  -    the expressions to be printed<br>
            <i>stream</i> -   the output stream (default is standard output)<br>
            returns -    the expression<br>

<br><dt>        (terpri<a name="index952"> [<i>stream</i>])  - terminate the current print line
<dd>
            <i>stream</i> -   the output stream (default is standard output)<br>
            returns   -  <code>nil</code><br>

<br><dt>        (flatsize<a name="index953"> <i>expr</i>)  - length of printed representation using prin1
<dd>
            <i>expr</i>  -    the expression<br>
            returns  -   the length<br>

<br><dt>        (flatc<a name="index954"> <i>expr</i>)  - length of printed representation using princ
<dd>
            <i>expr</i> -     the expression<br>
            returns  -   the length<br>

<br><dt>
</dl><a name = "131"><h3>The Format Function</h3></a><a name="index955">
<dl>
<dt>
(format<a name="index956"> <i>stream</i> <i>fmt</i> <i>arg</i>...)   - do formated
output
<dd>
            <i>stream</i> -   the output stream<br>
            <i>fmt</i>    -   the format string<br>
            <i>arg</i>    -   the format arguments<br>
            returns   -  output string if <i>stream</i> is <code>nil</code>, <code>nil</code> otherwise<br>

<br><dt>
</dl>
       The format string can contain characters that should be copied
        directly to the output and formatting directives.  The
        formatting directives are:
<blockquote>
~A - print next argument using princ<br>

~S - print next argument using prin1<br>

~% - start a new line<br>

~~ - print a tilde character<br>

</blockquote>
<p>
<a name = "132"><h3>File I/O Functions</h3></a><a name="index957">
Note that files are ordinarily opened as text. Binary files (such as standard midi files) must be opened with <code>open-binary</code> on non-unix systems.
<dl>
<dt>
        (open<a name="index958"> <i>fname</i> &amp;key :direction) -  open a file stream
<dd>
            <i>fname</i> -    the file name string or symbol<br>
            :direction - :input or :output (default is :input)<br>
            returns   -  a stream<br>

<br><dt>
        (open-binary<a name="index959"><a name="index960"> <i>fname</i> &amp;key :direction) -  open a binary file stream
<dd>
            <i>fname</i> -    the file name string or symbol<br>
            :direction - :input or :output (default is :input)<br>
            returns   -  a stream<br>

<br><dt>        (close<a name="index961"> <i>stream</i>)  - close a file stream
<dd>
            <i>stream</i> -   the stream<br>
            returns    - <code>nil</code><br>

<br><dt>        (read-char<a name="index962"> [<i>stream</i>])  - read a character from a stream
<dd>
            <i>stream</i> -   the input stream (default is standard input)<br>
            returns   -  the character<br>

<br><dt>        (peek-char<a name="index963"> [<i>flag</i> [<i>stream</i>]])  - peek at the next character
<dd>
            <i>flag</i>  -    flag for skipping white space (default is <code>nil</code>)<br>
            <i>stream</i> -    the input stream (default is standard input)<br>
            returns   -  the character (integer)<br>

<br><dt>        (write-char<a name="index964"> <i>ch</i> [<i>stream</i>])  - write a character to a stream
<dd>
            <i>ch</i>    -    the character to write<br>
            <i>stream</i> -   the output stream (default is standard output)<br>
            returns   -  the character<br>

<br><dt>        (read-int<a name="index965"> [<i>stream</i> [<i>length</i>]])  - read a binary integer from a stream
<dd>
            <i>stream</i> -   the input stream (default is standard input)<br>
            <i>length</i> - the length of the integer in bytes (default is 4)<br>
            returns   -  the integer<br>
Note: Integers are assumed to be big-endian (high-order byte first) and 
signed, regardless of the platform. To read little-endian format, use a
negative number for the length, e.g. -4 indicates a 4-bytes, low-order
byte first. The file should be opened in binary mode.<br>

<br><dt>        (write-int<a name="index966"> <i>ch</i> [<i>stream</i> [<i>length</i>]])  - write a binary integer to a stream
<dd>
            <i>ch</i>    -    the character to write<br>
            <i>stream</i> -   the output stream (default is standard output)<br>
            <i>length</i> - the length of the integer in bytes (default is 4)<br>
            returns   -  the integer<br>
Note: Integers are assumed to be big-endian (high-order byte first) and 
signed, regardless of the platform. To write in little-endian format, use a
negative number for the length, e.g. -4 indicates a 4-bytes, low-order
byte first. The file should be opened in binary mode.<br>

<br><dt>        (read-float<a name="index967"> [<i>stream</i> [<i>length</i>]])  - read a binary floating-point number from a stream
<dd>
            <i>stream</i> -   the input stream (default is standard input)<br>
            <i>length</i> - the length of the float in bytes (default is 4, legal values are -4, -8, 4, and 8)<br>
            returns   -  the integer<br>
Note: Floats are assumed to be big-endian (high-order byte first) and 
signed, regardless of the platform. To read little-endian format, use a
negative number for the length, e.g. -4 indicates a 4-bytes, low-order
byte first. The file should be opened in binary mode.<br>

<br><dt>        (write-float<a name="index968"> <i>ch</i> [<i>stream</i> [<i>length</i>]])  - write a binary floating-point number to a stream
<dd>
            <i>ch</i>    -    the character to write<br>
            <i>stream</i> -   the output stream (default is standard output)<br>
            <i>length</i> - the length of the float in bytes (default is 4, legal values are -4, -8, 4, and 8)<br>
            returns   -  the integer<br>
Note: Floats are assumed to be big-endian (high-order byte first) and 
signed, regardless of the platform. To write in little-endian format, use a
negative number for the length, e.g. -4 indicates a 4-bytes, low-order
byte first. The file should be opened in binary mode.<br>

<br><dt>        (read-line<a name="index969"> [<i>stream</i>])  - read a line from a stream
<dd>
            <i>stream</i> -   the input stream (default is standard input)<br>
            returns   -  the string<br>

<br><dt>        (read-byte<a name="index970"> [<i>stream</i>])  - read a byte from a stream
<dd>
            <i>stream</i> -   the input stream (default is standard input)<br>
            returns    - the byte (integer)<br>

<br><dt>        (write-byte<a name="index971"> <i>byte</i> [<i>stream</i>])  - write a byte to a stream
<dd>
            <i>byte</i>   -   the byte to write (integer)<br>
            <i>stream</i> -   the output stream (default is standard output)<br>
            returns    - the byte (integer)<br>

<br><dt>
</dl><a name = "133"><h3>String Stream Functions</h3></a><a name="index972">
        These functions operate on unnamed streams.  An unnamed output
        stream collects characters sent to it when it is used as the
        destination of any output function.  The functions 
<code>get-output-stream-string</code> and string or a list of characters.
<p>
An unnamed input stream is setup with the 
 <code>make-string-input-stream</code> function and returns each character of the string when
        it is used as the source of any input function.
<p>
<dl>
<dt>
<br><dt>
        (make-string-input-stream<a name="index973"> <i>str</i> [<i>start</i> [<i>end</i>]])
<dd>
            <i>str</i>    -   the string<br>
            <i>start</i>  -   the starting offset<br>
            <i>end</i>    -   the ending offset + 1<br>
            returns    - an unnamed stream that reads from the string<br>

<br><dt>        (make-string-output-stream)<a name="index974">
<dd>
            returns   -  an unnamed output stream<br>

<br><dt>        (get-output-stream-string<a name="index975"> <i>stream</i>)
<dd>
            <i>stream</i> -    the output stream<br>
            returns    - the output so far as a string<br>

          Note:  the output stream is emptied by this function
<br>
<br><dt>        (get-output-stream-list<a name="index976"> <i>stream</i>)
<dd>
            <i>stream</i> -   the output stream<br>
            returns   -  the output so far as a list<br>

          Note:  the output stream is emptied by this function
<br>
<br><dt>
</dl>
<p>
<a name = "134"><h3>System Functions</h3></a><a name="index977">
Note: the <code>load</code> function first tries to load a file from the current directory. A <code>.lsp</code> extension is added if there is not already an alphanumeric extension following  a period.  If that fails, XLisp searches the path, which is obtained from the XLISPPATH environment variable in Unix and  HKEY_LOCAL_MACHINE\SOFTWARE\CMU\Nyquist\XLISPPATH under Win32. (The Macintosh version has no search path.)
<p>
<dl>
<dt>
        (load<a name="index978"> <i>fname</i> &amp;key :verbose :print)   - load a source file
<dd>
            <i>fname</i>   -  the filename string or symbol<br>
            :verbose  -  the verbose flag (default is t)<br>
            :print    -  the print flag (default is <code>nil</code>)<br>
            returns   -  the filename<br>

<br><dt>        (save<a name="index979"> <i>fname</i>) - save workspace to a file
<dd>
            <i>fname</i> -    the filename string or symbol<br>
            returns   - <code>t</code> if workspace was written, <code>nil</code> otherwise<br>

<br><dt>        (restore<a name="index980"> <i>fname</i>)  - restore workspace from a file
<dd>
            <i>fname</i> -    the filename string or symbol<br>
            returns   -  <code>nil</code> on failure, otherwise never returns<br>

<br><dt>        (dribble<a name="index981"> [<i>fname</i>])  - create a file with a transcript of a session
<dd>
            <i>fname</i> -    file name string or symbol
                        (if missing, close current transcript)<br>
            returns   - <code>t</code> if the transcript is opened, <code>nil</code> if it is closed<br>

<br><dt>        (gc<a name="index982">)  - force garbage collection
<dd>
            returns -    <code>nil</code><br>

<br><dt>        (expand<a name="index983"> <i>num</i>)  - expand memory by adding segments
<dd>
            <i>num</i> -      the number of segments to add<br>
            returns -    the number of segments added<br>

<br><dt>        (alloc<a name="index984"> <i>num</i>)  - change number of nodes to allocate in each segment
<dd>
            <i>num</i> -      the number of nodes to allocate<br>
            returns -    the old number of nodes to allocate<br>

<br><dt>        (room<a name="index985">)  - show memory allocation statistics
<dd>
            returns -    <code>nil</code><br>

<br><dt>        (type-of<a name="index986"> <i>expr</i>)  - returns the type of the expression
<dd>
            <i>expr</i> -     the expression to return the type of<br>
            returns  -   <code>nil</code> if the value is <code>nil</code> otherwise one of the symbols:<br>
<dl><dd>
                          SYMBOL      -    for symbols<br>
                          OBJECT      -    for objects<br>
                          CONS        -    for conses<br>
                          SUBR        -    for built-in functions<br>
                          FSUBR       -    for special forms<br>
                          CLOSURE     -    for defined functions<br>
                          STRING      -    for strings<br>
                          FIXNUM      -    for integers<br>
                          FLONUM      -    for floating point numbers<br>
                          CHARACTER   -    for characters<br>
                          FILE-STREAM -    for file pointers<br>
                          UNNAMED-STREAM - for unnamed streams<br>
                          ARRAY          - for arrays<br>
</dl>

<br><dt>        (peek<a name="index987"> <i>addrs</i>)   - peek at a location in memory
<dd>
            <i>addrs</i>  -   the address to peek at (integer)<br>
            returns    - the value at the specified address (integer)<br>

<br><dt>        (poke<a name="index988"> <i>addrs</i> <i>value</i>) -  poke a value into memory
<dd>
            <i>addrs</i>  -   the address to poke (integer)<br>
            <i>value</i>  -   the value to poke into the address (integer)<br>
            returns    - the value<br>

<br><dt>        (address-of<a name="index989"> <i>expr</i>)  - get the address of an xlisp node
<dd>
            <i>expr</i>   -   the node<br>
            returns    - the address of the node (integer)<br>

<br><dt>        (exit<a name="index990">)  - exit xlisp
<dd>
            returns    - never returns<br>

<br><dt>        (setup-console<a name="index991"><a name="index992">)  - set default console attributes
<dd>
            returns    - NIL<br>
Note: Under Windows, Nyquist normally starts up in a medium-sized console window with black text and a white background, with a window title of ``Nyquist.'' This is normally accomplished by calling <code>setup-console</code> in <code>system.lsp</code>. In Nyquist, you can avoid this behavior by setting <code>*setup-console*</code> to NIL in your <code>init.lsp</code> file. If <code>setup-console</code> is not called, Nyquist uses standard input and output as is. This is what you want if you are running Nyquist inside of emacs, for example.<a name="index993"><br>

</dl><a name = "135"><h3>File I/O Functions</h3></a><a name="index994"><a name = "136"><h4>Input from a File</h4></a><a name="index995">To open a file for input, use the <code>open</code> function with the keyword
argument <code>:direction</code> set to <code>:input</code>.  To open a file for output,
use the <code>open</code> function with the keyword argument <code>:direction</code> set
to <code>:output</code>.  The <code>open</code> function takes a single required argument which
is the name of the file to be opened.  This name can be in the form of a
string or a symbol.  The <code>open</code> function returns an object of type
<code>FILE-STREAM</code> if it succeeds in opening the specified file.  It returns the
value <code>nil</code> if it fails.  In order to manipulate the file, it is
necessary to save the value returned by the <code>open</code> function.  This is
usually done by assigning it to a variable with the <code>setq</code> special form or by
binding it using <code>let</code> or <code>let*</code>.  Here is an example:
<pre>
(setq fp (open "init.lsp" :direction :input))
</pre>

        Evaluating this expression will result in the file <code>init.lsp</code>
        being opened.  The file object that will be returned by the <code>open</code>
        function will be assigned to the variable <code>fp</code>.
<p>
        It is now possible to use the file for input.  To read an
        expression from the file, just supply the value of the <code>fp</code>
        variable as the optional <i>stream</i> argument to <code>read</code>.
<pre>
(read fp)
</pre>

        Evaluating this expression will result in reading the first
        expression from the file <code>init.lsp</code>.  The expression will be
        returned as the result of the <code>read</code> function.  More expressions
        can be read from the file using further calls to the <code>read</code>
        function.  When there are no more expressions to read, the <code>read</code>
        function will return <code>nil</code> (or whatever value was supplied as the
        second argument to <code>read</code>).
<p>
        Once you are done reading from the file, you should close it.
        To close the file, use the following expression:
<pre>
(close fp)
</pre>

        Evaluating this expression will cause the file to be closed.
<p>
<a name = "137"><h4>Output to a File</h4></a><a name="index996">        Writing to a file is pretty much the same as reading from one.
        You need to open the file first.  This time you should use the
        <code>open</code> function to indicate that you will do output to the file.
        For example:
<pre>
(setq fp (open "test.dat" :direction :output))
</pre>

        Evaluating this expression will open the file <code>test.dat</code> for
        output.  If the file already exists, its current contents will
        be discarded.  If it doesn't already exist, it will be created.
        In any case, a <code>FILE-STREAM</code> object will be returned by the <code>OPEN</code>
        function.  This file object will be assigned to the <code>fp</code>
        variable.
<p>
        It is now possible to write to this file by supplying the value
        of the <code>fp</code> variable as the optional <i>stream</i> parameter in the  <code>print</code> function.
<pre>
(print "Hello there" fp)
</pre>

        Evaluating this expression will result in the string ``Hello
        there'' being written to the file <code>test.dat</code>.  More data can be
        written to the file using the same technique.
<p>
        Once you are done writing to the file, you should close it.
        Closing an output file is just like closing an input file.
<pre>
(close fp)
</pre>

        Evaluating this expression will close the output file and make
        it permanent.
<p>
<a name = "138"><h4>A Slightly More Complicated File Example</h4></a>        This example shows how to open a file, read each Lisp expression
        from the file and print it.  It demonstrates the use of files
        and the use of the optional <i>stream</i> argument to the <code>read</code>
        function.
<pre>
(do* ((fp (open "test.dat" :direction :input))
      (ex (read fp) (read fp)))
     ((null ex) nil)
  (print ex))
</pre>

<p>

<hr>
<a href = "part14.html">Previous Section</a> | <a href = "indx.html">Next Section (Index)</a> | <a href = "home.html#toc">Table of Contents</a> | <a href = "home.html">Title Page</a>
</body></html>