Nlisp
Reference Manual

Version 0.3t
2022 July 27

	



     TABLE OF CONTENTS

     COMMAND LOOP
     BREAK COMMAND LOOP
     DATA TYPES
     THE EVALUATOR
     LEXICAL CONVENTIONS
 
     SYMBOLS

     EVALUATION PROCEDURES
     SYMBOL PROCEDURES
     PROPERTY LIST PROCEDURES
     ARRAY PROCEDURES
     LIST PROCEDURES

     DESTRUCTIVE LIST PROCEDURES

     CONVERSION PROCEDURES
     PREDICATE PROCEDURES
     CONTROL CONSTRUCTS
     LOOPING CONSTRUCTS 
     THE PROGRAM FEATURE
     DEBUGGING AND ERROR HANDLING

     ARITHMETIC PROCEDURES

     BITWISE LOGICAL PROCEDURES
     RELATIONAL PROCEDURES
     STRING PROCEDURES

     INPUT/OUTPUT PROCEDURES
     FILE I/O PROCEDURES

     SYSTEM PROCEDURES
     EXAMPLES





     COMMAND LOOP

     When nLisp is started, it first tries to load "init.l" from
     the default directory which is /usr/local/share/nLisp.  The
     "init.l" file is stored in the directory "macros".
				    
				    
     It then issues the prompt:

     >

     This indicates that nLisp is waiting for an expression to be
     typed.  When an incomplete expression has been typed (one where
     the left and right parens don't match) nLisp changes its prompt
     to:
     
     n:>

     where n is an integer indicating how many levels of left parens
     remain unclosed.

     When a complete expression has been entered, nLisp attempts to
     evaluate that expression.  If the expression evaluates
     successfully, nLisp prints the result of the evaluation and then
     returns to the initial prompt waiting for another expression to
     be typed.



     BREAK COMMAND LOOP

     When nLisp encounters an error while evaluating an expression,
     it attempts to handle the error in the following way:

     If the symbol '*breakenable*' is true, the message corresponding
     to the error is printed.  If the error is correctable, the
     correction message is printed.  If the symbol '*tracenable*' is
     true, a trace back is printed.  The number of entries printed
     depends on the value of the symbol '*tracelimit*'.  If this
     symbol is set to something other than a number, the entire trace
     back stack is printed.  nLisp 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 'continue', nLisp will continue from a correctable
     error.  If the user invokes the function 'clean-up', nLisp will
     abort the break loop and return to the top level or the next
     lower numbered break loop.  When in a break loop, nLisp prefixes
     the break level to the normal prompt.

     If the symbol '*breakenable*' is nil, nLisp looks for a
     surrounding errset function.  If one is found, nLisp examines
     the value of the print flag.  If this flag is true, the error
     message is printed.  In any case, nLisp causes the errset
     function call to return nil.

     If there is no surrounding errset function, nLisp prints the
     error message and returns to the top level.



     DATA TYPES

     There are several different data types available to nLisp
     programmers.

            o lists (cons)
            o symbols
            o strings
            o integers
            o real
            o vectors
            o file pointers
            o primitive (built-in functions)
            o special (special forms)

     Another data type is the stream.  A stream is a list node whose
     car points to the head of a list of integers and whose cdr
     points to the last list node of the list.  An empty stream is a
     list node whose car and cdr are nil.  Each of the integers in
     the list represents a character in the stream.  When a character
     is read from a stream, the first integer from the head of the
     list is removed and returned.  When a character is written to a
     stream, the integer representing the character code of the
     character is appended to the end of the list.  When a function
     indicates that it takes an input source as a parameter, this
     parameter can either be an input file pointer or a stream.
     Similarly, when a function indicates that it takes an output
     sink as a parameter, this parameter can either be an output file
     pointer or a stream.



     THE EVALUATOR

     The process of evaluation in nLisp:
     
     Integers, reals, strings, file pointers, primitives, special,
     and arrays evaluate to themselves
     
     Symbols evaluate to the value associated with their current
     binding
     
     Lists are evaluated by evaluating the first element of the list
     and then taking one of the following actions:
     
        If it is a primitive, the remaining list elements are evaluated
        and the primitive is called with these evaluated expressions as
        arguments.

        If it is an special, the special is called using the remaining
        list elements as arguments (unevaluated)

        If it is a list:

           If the list is a function closure (a list whose car is a
           lambda expression and whose cdr is an environment list),
           the car of the list is used as the function to be
           applied and the cdr is used as the environment to be
           extended with the parameter bindings.

           If the list is a lambda expression, the current
           environment is used for the function application.

                In either of the above two cases, the remaining list
                elements are evaluated and the resulting expressions
                are bound to the formal arguments of the lambda
                expression.  The body of the function is executed
                within this new binding environment.

           If it is a list and the car of the list is 'macro', the
           remaining list elements are bound to the formal
           arguments of the macro expression.  The body of the
           function is executed within this new binding
           environment.  The result of this evaluation is
           considered the macro expansion.  This result is then
           evaluated in place of the original expression.



     LEXICAL CONVENTIONS

     The following conventions must be followed when entering nLisp
     programs:

     Comments in nLisp code begin with a semi-colon character and
     continue to the end of the line.
     
     Symbol names in nLisp can consist of any sequence of non-blank
     printable characters except the following:

                ( ) ' ` , " ;

     Integer literals consist of a sequence of digits optionally
     beginning with a '+' or '-'.  The range of values an integer can
     represent is limited by the size of a C 'long' on the machine on
     which nLisp is running.

     Floating point literals consist of a sequence of digits
     optionally beginning with a '+' or '-' and including an embedded
     decimal point.  The range of values a floating point number can
     represent is limited by the size of a C 'float' ('double' on
     machines with 32 bit addresses) on the machine on which nLisp is
     running.

     Literal strings are sequences of characters surrounded by double
     quotes.  Within quoted strings the '' character is used to allow
     non-printable characters to be included.  The codes recognized
     are:

                \\        means the character '\'
                \n       means newline
                \t       means tab
                \r       means return
                \f       means form feed
                \nnn     means the character whose octal code is nnn

        nLisp defines several useful read macros:

                '<expr>         == (quote <expr>)
                #(<expr>...)    == an array of the specified expressions
                #x<hdigits>     == a hexadecimal number
                #\<char> == the ASCII code of the character
                `<expr>         == (backquote <expr>)
                ,<expr>         == (comma <expr>)
                ,@<expr>        == (comma-at <expr>)




    SYMBOLS

            o *oblist* - the object hash table
            o *standard-input* - the standard input file
            o *standard-output* - the standard output file
            o *breakenable* - flag controlling entering break loop on errors
            o *tracenable* - enable baktrace on errors
            o *tracelist* - trace list of procedures
            o *unbound* - indicator for unbound symbols
            o *gc-flag* - controls the printing of gc messages


				
    EVALUATION PROCEDURES

        (eval <expr>)  EVALUATE AN nLisp EXPRESSION
            <expr>      the expression to be evaluated
            returns     the result of evaluating the expression

        (apply <fun> <args>)  APPLY A FUNCTION TO A LIST OF ARGUMENTS
            <fun>       the function to apply (or function symbol)
            <args>      the argument list
            returns     the result of applying the function to the arguments

        (quote <expr>)  RETURN AN EXPRESSION UNEVALUATED
            <expr>      the expression to be quoted (quoted)
            returns     <expr> unevaluated

        (backquote <expr>)  FILL IN A TEMPLATE
            <expr>      the template
            returns     a copy of the template with comma and comma-at
                        expressions expanded

        (lambda <args> [<expr>]...)  MAKE A FUNCTION CLOSURE
            <args>      the argument list (quoted)
            <expr>      expressions of the function body
            returns     the function closure



    SYMBOL PROCEDURES

        (set <sym> <expr>)  SET THE VALUE OF A SYMBOL
            <sym>    the symbol being set
            <expr>   the new value
            returns   the new value

                example:  (set a 1)
                          a => 1
                          (set add (lambda (a b) (+ a b)))
                          (add 1 2) => 3

        (set! [<sym> <value>])  MODIFY THE VALUE OF A SYMBOL
            <sym>     the symbol being modified
            <value>   the new value
            returns   the new value

        (pset [<sym> <value>] ...)  PARALLEL SET THE VALUE OF A SYMBOL
            <sym>     the symbol being set
            <expr>    the new expr
            returns   the last expr set

                example:  (pset a 1 inc (lambda (n) (+ n 1)))
                          a => 1
                          (inc 2) => 3                  


        (def <sym> <fargs> [<expr>]...)  DEFINE A PROCEDURE

        (def-macro <sym> <fargs> [<expr>]...)  DEFINE A MACRO
            <sym>       symbol being defined (quoted)
            <fargs>     list of formal arguments (quoted)
                          this list is of the form:
                            ([<farg>]...
                             [&optional [<oarg>]...]
                             [&rest <rarg>]
                             [&aux [<aux>]...])
                          where
                            <farg>      is a formal argument
                            <oarg>      is an optional argument
                            <rarg>      bound to the rest of the arguments
                            <aux>       is an auxiliary variable
            <expr>      expressions constituting the body of the
                        function (quoted)
            returns     the function symbol

        (gensym [<tag>])  GENERATE A SYMBOL
            <tag>       string or number
            returns     the new symbol

        (intern <name>)  MAKE AN INTERNED SYMBOL
            <name>      the symbol's name string
            returns     the new symbol

        (symbol-name <sym>)  GET THE NAME OF A SYMBOL
            <sym>       the symbol
            returns     the symbol's name

        (symbol-value <sym>)  GET THE VALUE OF A SYMBOL
            <sym>       the symbol
            returns     the symbol's value

        (symbol-plist <sym>)  GET THE PROPERTY LIST OF A SYMBOL
            <sym>       the symbol
            returns     the symbol's property list

        (make-symbol <name>)  MAKE AN UNINTERNED SYMBOL
            <name>      the symbol's name string
            returns     the new symbol

                example:  (make-symbol "x")
                          (symbol-name 'x) => "x"
                          (symbol-value 'x) => nil
                          (symbol-plist 'x) => nil
                          (set (symbol-value 'x) 1)
                          (symbol-value 'x) => 1


        (hash <sym> <n>)  COMPUTE THE HASH INDEX FOR A SYMBOL
            <sym>       the symbol or string
            <n>         the table size (integer)
            returns     the hash index (integer)



    PROPERTY LIST PROCEDURES

        (get <sym> <prop>)  GET THE VALUE OF A PROPERTY
            <sym>       the symbol
            <prop>      the property symbol
            returns     the property value or nil

        (putprop <sym> <val> <prop>)  PUT A PROPERTY ONTO A PROPERTY LIST
            <sym>       the symbol
            <val>       the property value
            <prop>      the property symbol
            returns     the property value

        (remprop <sym> <prop>)  REMOVE A PROPERTY
            <sym>       the symbol
            <prop>      the property symbol
            returns     nil



    VECTOR PROCEDURES

	(vector [element]...)  MAKE A NEW VECTOR

        (make-vector <size>)  MAKE A NEW VECTOR
            <size>      the size of the new vector (integer)
            returns     the new vector

        (vector-ref <array> <n>)  GET THE NTH ELEMENT OF A VECTOR
            <array>     the array
            <n>         the array index (integer)
            returns     the value of the vector element

        (vector-set! <array> <n> <val>)  SET THE NTH ELEMENT OF A VECTOR
            <array>     the array
            <n>         the array index (integer)
            <val>       the new value of the nth element
	    returns     the value of the vector element



    LIST PROCEDURES

        (car <expr>)  RETURN THE CAR OF A LIST NODE
            <expr>      the list node
            returns     the car of the list node

        (cdr <expr>)  RETURN THE CDR OF A LIST NODE
            <expr>      the list node
            returns     the cdr of the list node

        (cxxr <expr>)  ALL CxxR COMBINATIONS
        (cxxxr <expr>)  ALL CxxxR COMBINATIONS
        (cxxxxr <expr>)  ALL CxxxxR COMBINATIONS

        (cons <expr1> <expr2>)  CONSTRUCT A NEW LIST NODE
            <expr1>     the car of the new list node
            <expr2>     the cdr of the new list node
            returns     the new list node

        (list [<expr>]...)  CREATE A LIST OF VALUES
            <expr>      expressions to be combined into a list
            returns     the new list

        (append [<expr>]...)  APPEND LISTS
            <expr>      lists whose elements are to be appended
            returns     the new list

        (reverse <expr>)  REVERSE A LIST
            <expr>      the list to reverse
            returns     a new list in the reverse order

        (last-pair <list>)  RETURN THE LAST LIST PAIR OF A LIST
            <list>      the list
            returns     the last cons pair in the list

        (member <expr> <list> [<key> <test>])  FIND AN EXPRESSION IN A LIST
            <expr>      the expression to find
            <list>      the list to search
            <key>       the keyword :test or :test-not
            <test>      the test function (defaults to eql)
            returns     the remainder of the list starting with the expression

        (assoc <expr> <alist> [<key> <test>])  FIND AN EXPRESSION IN AN A-LIST
            <expr>      the expression to find
            <alist>     the association list
            <key>       the keyword :test or :test-not
            <test>      the test function (defaults to eql)
            returns     the alist entry or nil


        (remove <expr> <list> [<key> <test>])  REMOVE AN EXPRESSION
            <expr>      the expression to delete
            <list>      the list
            <key>       the keyword :test or :test-not
            <test>      the test function (defaults to eql)
            returns     the list with the matching expressions deleted

        (length <expr>)  FIND THE LENGTH OF A LIST
            <expr>      the list
            returns     the length of the list

        (list-ref <n> <list>)  RETURN THE NTH ELEMENT OF A LIST
            <n>         the number of the element to return (zero origin)
            <list>      the list
            returns     the nth element or nil if the list isn't that long

        (nthcdr <n> <list>)  RETURN THE NTH CDR OF A LIST
            <n>         the number of the element to return (zero origin)
            <list>      the list
            returns     the nth cdr or nil if the list isn't that long

        (map <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CARS
            <fcn>       the function or function name
            <listn>     a list for each argument of the function
            returns     a list of the values returned

        (mapc <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CARS
            <fcn>       the function or function name
            <listn>     a list for each argument of the function
            returns     the first list of arguments

        (mapl <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CDRS
            <fcn>       the function or function name
            <listn>     a list for each argument of the function
            returns     the first list of arguments

        (maplist <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CDRS
            <fcn>       the function or function name
            <listn>     a list for each argument of the function
            returns     a list of the values returned

        (subst <to> <from> <expr> [<key> <test>])  SUBSTITUTE EXPRESSIONS
            <to>        the new expression
            <from>      the old expression
            <expr>      the expression in which to do the substitutions
            <key>       the keyword :test or :test-not
            <test>      the test function (defaults to eql)
            returns     the expression with substitutions

        (sublis <alist> <expr> [<key> <test>])  SUBSTITUTE WITH AN A-LIST
            <alist>     the association list
            <expr>      the expression in which to do the substitutions
            <key>       the keyword :test or :test-not
            <test>      the test function (defaults to eql)
            returns     the expression with substitutions



    DESTRUCTIVE LIST PROCEDURES

        (nconc! [<list>]...)  DESTRUCTIVELY CONCATENATE LISTS
            <list>      lists to concatenate
            returns     the result of concatenating the lists

        (delete! <expr> <list> [<key> <test>]) DELETE AN EXPRESSION FROM A LIST
            <expr>      the expression to delete
            <list>      the list
            <key>       the keyword :test or :test-not
            <test>      the test function (defaults to eql)
            returns     the list with the matching expressions deleted



    CONVERSION PROCEDURES

        (string->symbol <string>) CONVERT A STRING TO A SYMBOL
            <string>    the string
            returns     the symbol object

        (char->integer <chr>) CONVERT A CHARACTER TO AN INTEGER
            <chr>       the character
            returns     the ASCII character code

        (integer->char <int>) CONVERT AN INTEGER TO A CHARACTER
            <int>       the ASCII character code
            returns     the character with that code

        (string->integer <string>) CONVERT A STRING TO AN INTEGER
            <string>    the string
            returns     the INTEGER number

        (integer->string <integer>) CONVERT AN INTEGER TO A STRING
            <integer>   the integer
            returns     the character string

        (string->list <string>)   CONVERT A STRING TO A LIST
            <string>    the string, eg. "dog"
            returns     the list of characters, eg. (#\d #\o #\g)

        (list->string <list>)   CONVERT A LIST TO A STRING
            <list>      the list of characters, eg. (#\d #\o #\g)
            returns     the string, eg. "dog"


    PREDICATE PROCEDURES

        (atom <expr>)  IS THIS AN ATOM?
            <expr>      the expression to check
            returns     #t if the value is an atom, nil otherwise

        (symbol? <expr>)  IS THIS A SYMBOL?
            <expr>      the expression to check
            returns     #t if the expression is a symbol, nil otherwise

        (number? <expr>)  IS THIS A NUMBER?
            <expr>      the expression to check
            returns     #t if the expression is a number, nil otherwise

        (null <expr>)  IS THIS AN EMPTY LIST?
            <expr>      the list to check
            returns     #t if the list is empty, nil otherwise

        (not <expr>)  IS THIS FALSE?
            <expr>      the expression to check
            return      #t if the expression is nil, nil otherwise

        (list? <expr>)  IS THIS A LIST?
            <expr>      the expression to check
            returns     #t if the value is a list node or nil, nil otherwise

        (cons? <expr>)  IS THIS A NON-EMPTY LIST?
            <expr>      the expression to check
            returns     #t if the value is a list node, nil otherwise

        (bound? <sym>)  IS THIS A BOUND SYMBOL?
            <sym>       the symbol
            returns     #t if a value is bound to the symbol, nil otherwise

                  example:  (make-symbol "x") => symbol with no value
                            (bound? 'x) => nil

        (minus? <expr>)  IS THIS NUMBER NEGATIVE?
            <expr>      the number to test
            returns     #t if the number is negative, nil otherwise

        (zero? <expr>)  IS THIS NUMBER ZERO?
            <expr>      the number to test
            returns     #t if the number is zero, nil otherwise

        (plus? <expr>)  IS THIS NUMBER POSITIVE?
            <expr>      the number to test
            returns     #t if the number is positive, nil otherwise

        (even? <expr>)  IS THIS NUMBER EVEN?
            <expr>      the number to test
            returns     #t if the number is even, nil otherwise

        (odd? <expr>)  IS THIS NUMBER ODD?
            <expr>      the number to test
            returns     #t if the number is odd, nil otherwise

        (eq? <expr1> <expr2>)  ARE THE EXPRESSIONS IDENTICAL?
            <expr1>     the first expression
            <expr2>     the second expression
            returns     #t if they are equal, nil otherwise

        (eql? <expr1> <expr2>)  ARE THE EXPRESSIONS EQUAl?
                                (WORKS WITH NUMBERS AND STRINGS)
            <expr1>     the first expression
            <expr2>     the second expression
            returns     #t if they are equal, nil otherwise

        (equal? <expr1> <expr2>)  ARE THE EXPRESSIONS EQUAL?
            <expr1>     the first expression
            <expr2>     the second expression
            returns     #t if they are equal, nil otherwise



    CONTROL CONSTRUCTS

        (cond [<pair>]...)  EVALUATE CONDITIONALLY
            <pair>      pair consisting of:
                            (<pred> [<expr>]...)
                          where
                            <pred>      is a predicate expression
                            <expr>      evaluated if the predicate
                                        is not nil
            returns     the value of the first expression whose predicate
                        is not nil

        (and [<expr>]...)  THE LOGICAL AND OF A LIST OF EXPRESSIONS
            <expr>      the expressions to be ANDed
            returns     nil if any expression evaluates to nil,
                        otherwise the value of the last expression
                        (evaluation of expressions stops after the first
                         expression that evaluates to nil)

        (or [<expr>]...)  THE LOGICAL OR OF A LIST OF EXPRESSIONS
            <expr>      the expressions to be ORed
            returns     nil if all expressions evaluate to nil,
                        otherwise the value of the first non-nil expression
                        (evaluation of expressions stops after the first
                         expression that does not evaluate to nil)

        (if <texpr> <expr1> [<expr2>])  EXECUTE EXPRESSIONS CONDITIONALLY
            <texpr>     the test expression
            <expr1>     the expression to be evaluated if texpr is non-nil
            <expr2>     the expression to be evaluated if texpr is nil
            returns     the value of the selected expression

        (case <expr> [<case>]...)  SELECT BY CASE
            <expr>      the selection expression
            <case>      pair consisting of:
                            (<value> [<expr>]...)
                          where:
                            <value>     is a single expression or a list of
                                        expressions (unevaluated)
                            <expr>      are expressions to execute if the
                                        case matches
            returns     the value of the last expression of the matching case

        (when <test> <expr>)
            <test>   test equivalent to an "as if"; "actuate if true"
            <expr>   executes the expression body <expr> in a single
                     test.

        (unless <test> <expr>)
            <test>   test equivalent to an "as if not"; "actuate if false"
            <expr>   Unless is an "exclusion" test which is the opposite
                     of when.  <expr> is executed if <test> is false

        (let ([<binding>]...) [<expr>]...)  CREATE LOCAL BINDINGS
        (let* ([<binding>]...) [<expr>]...)  LET WITH SEQUENTIAL BINDING
            <binding>   the variable bindings each of which is either:
                        1)  a symbol (which is initialized to nil)
                        2)  a list whose car is a symbol and whose cadr
                                is an initialization expression
            <expr>      the expressions to be evaluated
            returns     the value of the last expression

        (flet ([<name lambda-list-procedure] ...) [<expr>]...)
            SPECIAL FORM FOR LOCAL FUNCTION BINDING
               name - procedure name
               lambda-list-procedure - argument and body of the procedure

        (nlet <name> ([<binding>]...) [<expr>]...)  NAMED LET

                   macro:  (def-macro nlet (name args . body)
                              `(flet ([,name ,(map car args) ,@body])
                                 (,name ,@(map cadr args))))


        (catch <sym> [<expr>]...)  EVALUATE EXPRESSIONS AND CATCH THROWS
            <sym>       the catch tag
            <expr>      expressions to evaluate
            returns     the value of the last expression the throw expression

        (throw <sym> [<expr>])  THROW TO A CATCH
            <sym>       the catch tag
            <expr>      the value for the catch to return (defaults to nil)
            returns     never returns



    LOOPING CONSTRUCTS

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

        (dolist (<sym> <expr> [<rexpr>]) [<expr>]...)  LOOP THROUGH A LIST
            <sym>       the symbol to bind to each list element
            <expr>      the list expression
            <rexpr>     the result expression (the default is nil)
            <expr>      the body of the loop (treated like an implicit prog)

        (dotimes (<sym> <expr> [<rexpr>]) [<expr>]...)  LOOP FROM ZERO TO N-1
            <sym>       the symbol to bind to each value from 0 to n-1
            <expr>      the number of times to loop
            <rexpr>     the result expression (the default is nil)
            <expr>      the body of the loop (treated like an implicit prog)



    THE PROGRAM FEATURE

        (tag-block ...)      is Common Lisp's tagbody

        (special-block ...)  is Common Lisp's progv

        (goto <sym>)  GO TO A TAG WITHIN A PROG CONSTRUCT
            <sym>       the tag (quoted)
            returns     never returns

        (return [<expr>])  CAUSE A PROG CONSTRUCT TO RETURN A VALUE
            <expr>      the value (defaults to nil)
            returns     never returns

        (begin [<expr>]...)  EXECUTE EXPRESSIONS SEQUENTIALLY
            <expr>      the expressions to evaluate
            returns     the value of the last expression (or nil)



    DEBUGGING AND ERROR HANDLING

        (error <emsg> [<arg>])  SIGNAL A NON-CORRECTABLE ERROR
            <emsg>      the error message string
            <arg>       the argument expression (printed after the message)
            returns     never returns

        (error-break <cmsg> <emsg> [<arg>])  SIGNAL A CORRECTABLE ERROR
            <cmsg>      the continue message string
            <emsg>      the error message string
            <arg>       the argument expression (printed after the message)
            returns     nil when continued from the break loop

        (break [<bmsg> [<arg>]])  ENTER A BREAK LOOP
            <bmsg>      the break message string (defaults to "**BREAK**")
            <arg>       the argument expression (printed after the message)
            returns     nil when continued from the break loop

        (clean-up)  CLEAN-UP AFTER AN ERROR
            returns     never returns

        (top-level)  CLEAN-UP AFTER AN ERROR AND RETURN TO THE TOP LEVEL
            returns     never returns

        (continue)  CONTINUE FROM A CORRECTABLE ERROR
            returns     never returns

        (errset <expr> [<pflag>])  TRAP ERRORS
            <expr>      the expression to execute
            <pflag>     flag to control printing of the error message
            returns     the value of the last expression consed with nil
                        or nil on error

        (backtrace [<n>])  PRINT N LEVELS OF TRACE BACK INFORMATION
            <n>         the number of levels (defaults to all levels)
            returns     nil



    ARITHMETIC PROCEDURES

        (truncate <expr>)  TRUNCATES A FLOATING POINT NUMBER TO AN INTEGER
            <expr>      the number
            returns     the result of truncating the number

        (float <expr>)  CONVERTS AN INTEGER TO A FLOATING POINT NUMBER
            <expr>      the number
            returns     the result of floating the integer

        (+ <expr>...)  ADD A LIST OF NUMBERS
            <expr>      the numbers
            returns     the result of the addition

        (- <expr>...)  SUBTRACT A LIST OF NUMBERS OR NEGATE A SINGLE NUMBER
            <expr>      the numbers
            returns     the result of the subtraction

        (* <expr>...)  MULTIPLY A LIST OF NUMBERS
            <expr>      the numbers
            returns     the result of the multiplication

        (/ <expr>...)  DIVIDE A LIST OF NUMBERS
            <expr>      the numbers
            returns     the result of the division

        (inc <expr>)  ADD ONE TO A NUMBER
            <expr>      the number
            returns     the number plus one

        (dec <expr>)  SUBTRACT ONE FROM A NUMBER
            <expr>      the number
            returns     the number minus one

        (remainder n1 n2)  REMAINDER OF n1 divided by n2
            <expr>      the numbers
            returns     the result of the remainder operation

        (min <expr>...)  THE SMALLEST OF A LIST OF NUMBERS
            <expr>      the expressions to be checked
            returns     the smallest number in the list

        (max <expr>...)  THE LARGEST OF A LIST OF NUMBERS
            <expr>      the expressions to be checked
            returns     the largest number in the list

        (abs <expr>)  THE ABSOLUTE VALUE OF A NUMBER
            <expr>      the number
            returns     the absolute value of the number

        (random <n>)  COMPUTE A RANDOM NUMBER BETWEEN 1 and N-1
            <n>         the upper bound (integer)
            returns     a random number

        (sin <expr>)  COMPUTE THE SINE OF A NUMBER
            <expr>      the floating point number
            returns     the sine of the number

        (cos <expr>)  COMPUTE THE COSINE OF A NUMBER
            <expr>      the floating point number
            returns     the cosine of the number

        (tan <expr>)  COMPUTE THE TANGENT OF A NUMBER
            <expr>      the floating point number
            returns     the tangent of the number

        (expt <x-expr> <y-expr>)  COMPUTE X TO THE Y POWER
            <x-expr>    the floating point number
            <y-expr>    the floating point exponent
            returns     x to the y power

        (exp <x-expr>)  COMPUTE E TO THE X POWER
            <x-expr>    the floating point number
            returns     e to the x power

        (sqrt <expr>)  COMPUTE THE SQUARE ROOT OF A NUMBER
            <expr>      the floating point number
            returns     the square root of the number



    BITWISE LOGICAL PROCEDURES

        (logand <expr>...)  THE BITWISE AND OF A LIST OF NUMBERS
            <expr>      the numbers
            returns     the result of the and operation

        (logior <expr>...)  THE BITWISE INCLUSIVE OR OF A LIST OF NUMBERS
            <expr>      the numbers
            returns     the result of the inclusive or operation

        (logxor <expr>...)  THE BITWISE EXCLUSIVE OR OF A LIST OF NUMBERS
            <expr>      the numbers
            returns     the result of the exclusive or operation

        (lognot <expr>)  THE BITWISE NOT OF A NUMBER
            <expr>      the number
            returns     the bitwise inversion of number



    RELATIONAL PROCEDURES

        The relational functions can be used to compare integers,
        floating point numbers or strings.

        (< <e1> <e2>)  TEST FOR LESS THAN
            <e1>        the left operand of the comparison
            <e2>        the right operand of the comparison
            returns     the result of comparing <e1> with <e2>

        (<= <e1> <e2>)  TEST FOR LESS THAN OR EQUAL TO
            <e1>        the left operand of the comparison
            <e2>        the right operand of the comparison
            returns     the result of comparing <e1> with <e2>

        (= <e1> <e2>)  TEST FOR EQUAL TO
            <e1>        the left operand of the comparison
            <e2>        the right operand of the comparison
            returns     the result of comparing <e1> with <e2>

        (/= <e1> <e2>)  TEST FOR NOT EQUAL TO
            <e1>        the left operand of the comparison
            <e2>        the right operand of the comparison
            returns     the result of comparing <e1> with <e2>

        (>= <e1> <e2>)  TEST FOR GREATER THAN OR EQUAL TO
            <e1>        the left operand of the comparison
            <e2>        the right operand of the comparison
            returns     the result of comparing <e1> with <e2>

        (> <e1> <e2>)  TEST FOR GREATER THAN
            <e1>        the left operand of the comparison
            <e2>        the right operand of the comparison
            returns     the result of comparing <e1> with <e2>



    STRING PROCEDURES

        (string <expr>)  MAKE A STRING FROM AN INTEGER ASCII VALUE
            <expr>      the integer
            returns     a one character string

        (strlen <expr>)  RETURNS STRING LENGTH
            <expr>      the string
            returns     the number of characters in the string
            synonym:    string-length

        (strcat [<expr>]...)  CONCATENATE STRINGS
            <expr>      the strings to concatenate
            returns     the result of concatenating the strings
            synonym:    string-append

        (substr <expr> <start> [<length>]) EXTRACT A SUBSTRING
            <expr>      the string
            <start>     the starting position
            <length>    the length (default is rest of string)
            returns     substring starting at <sexpr> for <length>
            synonym:    string-ncopy

        (string-lowercase <string>)  CONVERTS STRING TO LOWERCASE

        (string-uppercase <string>)  CONVERTS STRING TO UPPERCASE



    CHARACTER PROCEDURES

        (char <string> <index>)  EXTRACT A CHARACTER FROM A STRING
            <string>    the string
            <index>     the string index (zero relative)
            returns     the ascii code of the character

        (lowercase? <chr>)  IS THIS A LOWER CASE CHARACTER?
            <chr>       the character
            returns     true if the character is lower case, nil otherwise

        (uppercase? <chr>)  IS THIS AN UPPER CASE CHARACTER?
            <chr>       the character
            returns     true if the character is upper case, nil otherwise

        (char-lowercase <chr>)  CONVERT A CHARACTER TO LOWER CASE
            <chr>       the character
            returns     the lower case character

        (char-uppercase <chr>)  CONVERT A CHARACTER TO UPPER CASE
            <chr>       the character
            returns     the upper case character


    INPUT/OUTPUT PROCEDURES

        (read [<source> [<eof> [<rflag>]]])  READ AN nLisp EXPRESSION
            <source>    the input source (default is standard input)
            <eof>       the value to return on end of file (default is nil)
            <rflag>     recursive read flag (default is nil)
            returns     the expression read

        (print <expr> [<sink>])  PRINT A LIST OF VALUES ON A NEW LINE
            <expr>      the expressions to be printed
            <sink>      the output sink (default is standard output)
            returns     the expression

        (display <expr> [<sink>])  PRINT A LIST OF VALUES WITHOUT QUOTING
            <expr>      the expressions to be printed
            <sink>      the output sink (default is standard output)
            returns     the expression

        (newline [<sink>])  MAKE A NEWLINE
            <sink>      the output sink (default is standard output)
            returns     nil

        (flatsize <expr>)  LENGTH OF PRINTED REPRESENTATION USING PRIN1
            <expr>      the expression
            returns     the length

        (flatc <expr>)  LENGTH OF PRINTED REPRESENTATION USING PRINC
            <expr>      the expression
            returns     the length



    FILE I/O PROCEDURES

        (open-input-file <fname>)  OPEN AN INPUT FILE
            <fname>     the file name string or symbol
            returns     a file port

        (open-output-file <fname>)  OPEN AN OUTPUT FILE
            <fname>     the file name string or symbol
            returns     a file port

        (close <fp>)  CLOSE A FILE
            <fp>        the file port
            returns     true

        (read-char [<source>])  READ A CHARACTER FROM A FILE
            <source>    the input source (default is standard input)
            returns     the character (integer)

        (peek-char [<flag> [<source>]])  PEEK AT THE NEXT CHARACTER
            <flag>      flag for skipping white space (default is nil)
            <source>    the input source (default is standard input)
            returns     the character (integer)

        (write-char <ch> [<sink>])  WRITE A CHARACTER TO A FILE
            <ch>        the character to put (integer)
            <sink>      the output sink (default is standard output)
            returns     the character (integer)

        (read-line [<source>])  READ A LINE FROM A FILE
            <source>    the input source (default is standard input)
            returns     the input string

        (open-input-string <string>)  MAKES AN INPUT STRING STREAM
            <string     the input string which is stored internally
                        as a character list.
            returns     the string stream port

        (get-output-string  <sp>   GETS THE STRING STORE BY
                                   OPEN-INPUT-STRING
            <sp>        the string stream port
            returns     the stored string

                example:  (set ss (open-input-string "onetwo"))
                          (get-output-string ss) => "onetwo"


    SYSTEM PROCEDURES

        (load <fname> [<vflag> [<pflag>]])  LOAD AN nLisp SOURCE FILE
            <fname>     the filename string or symbol
            <vflag>     the verbose flag (default is t)
            <pflag>     the print flag (default is nil)
            returns     the filename

        (transcript [<fname>])  CREATE A FILE WITH A TRANSCRIPT OF A SESSION
            <fname>     file name string or symbol
                        (if missing, close current transcript)
            returns     t if the transcript is opened, nil if it is closed

        (gc)  FORCE GARBAGE COLLECTION
            returns     nil

        (expand <num>)  EXPAND MEMORY BY ADDING SEGMENTS
            <num>       the number of segments to add
            returns     the number of segments added

        (alloc <num>)  CHANGE NUMBER OF NODES TO ALLOCATE IN EACH SEGMENT
            <num>       the number of nodes to allocate
            returns     the old number of nodes to allocate

        (mem)  SHOW MEMORY ALLOCATION STATISTICS
            returns     nil

        (type-of <expr>)  RETURNS THE TYPE OF THE EXPRESSION
            <expr>      the expression to return the type of
            returns     nil if the value is nil otherwise one of the symbols:
                          :SYMBOL for symbols
                          :OBJECT for objects
                          :CONS   for conses
                          :PRIMITIVE  for built-ins with evaluated arguments
                          :SPECIAL    for built-ins with unevaluated arguments
                          :STRING for strings
                          :INTEGER for integers
                          :REAL for floating point numbers
                          :FILE   for file pointers
                          :VECTOR  for one dimensional arrays

        (peek <addrs>)  PEEK AT A LOCATION IN MEMORY
            <addrs>     the address to peek at (integer)
            returns     the value at the specified address (integer)

        (poke <addrs> <value>)  POKE A VALUE INTO MEMORY
            <addrs>     the address to poke (integer)
            <value>     the value to poke into the address (integer)
            returns     the value

        (address-of <expr>)  GET THE ADDRESS OF AN nLisp NODE
            <expr>      the node
            returns     the address of the node (integer)

	(command-line)  returns the command line (string)

        (exit)  EXIT nLisp
            returns     never returns

    
FILE I/O PROCEDURES Input from a File nLisp provides two functions for opening files. To open a file for input, use the OPEN-INPUT-FILE function. To open a file for output, use the OPEN-OUTPUT-FILE function. Both of these functions take a single argument which is the name of the file to be opened. This name can be in the form of a string or a symbol. Both open functions return an object of type :FILE as their result if they succeed in opening the specified file. They return the value NIL if they are not successful. In order to manipulate the file, it is necessary to save the value returned by the open function. This is usually done by assigning it to a variable with the SET special form or by binding it using LET or LET*. Here is an example: (set fp (open-input-file "init.lsp")) Evaluating this expression will result in the file "init.lsp" being opened. The file object that will be returned by the OPEN-INPUT-FILE function will be assigned to the variable "fp". It is now possible to use the file for input. To read an expression from the file, just supply the value of the "fp" variable as the optional "stream" argument to READ. (read fp) Evaluating this expression will result in reading the first expression from the file "init.lsp". The expression will be returned as the result of the READ function. More expressions can be read from the file using further calls to the READ function. When there are no more expressions to read, the READ function will return NIL (or whatever value was supplied as the second argument to READ). Once you are done reading from the file, you should close it. To close the file, use the following expression: (close fp) Evaluating this expression will cause the file to be closed. Output to a File 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 OPEN-OUTPUT-FILE function to indicate that you will do output to the file. For example: (set fp (open-output-file "test.dat")) Evaluating this expression will open the file "test.dat" 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 :FILE object will be returned by the OPEN-OUTPUT-FILE function. This file object will be assigned to the "fp" variable. It is now possible to write to this file by supplying the value of the "fp" variable as the optional "stream" parameter in the PRINT function. (print "Hello there" fp) Evaluating this expression will result in the string "Hello there" being written to the file "test.dat". More data can be written to the file using a similar technique. Once you are done writing to the file, you should close it. Closing an output file is just like closing an input file. (close fp) Evaluating this expression will close the output file and make it permanent. A Slightly More Complicated File Example 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 "stream" argument to the READ function. (do* ((fp (open-input-file "test.dat")) (ex (read fp) (read fp))) ((null ex) nil) (print ex))