mLisp

Reference Manual

Version 0.3
2018 July 8

Modifications of original documention from Xlisp-1.7
by David Betz
	





                                    mLisp
                                    -----
				    

                               Table of Contents


                TABLE OF CONTENTS

                mlisp COMMAND LOOP
                BREAK COMMAND LOOP
                DATA TYPES
                THE EVALUATOR
                LEXICAL CONVENTIONS
                READTABLES

                SYMBOLS

                EVALUATION FUNCTIONS

                SYMBOL FUNCTIONS

                PROPERTY LIST FUNCTIONS

                ARRAY FUNCTIONS

                LIST FUNCTIONS

                DESTRUCTIVE LIST FUNCTIONS

                PREDICATE FUNCTIONS
                CONTROL CONSTRUCTS
                LOOPING CONSTRUCTS 
                THE PROGRAM FEATURE
                DEBUGGING AND ERROR HANDLING

                ARITHMETIC FUNCTIONS

                BITWISE LOGICAL FUNCTIONS

                RELATIONAL FUNCTIONS

                STRING FUNCTIONS

                INPUT/OUTPUT FUNCTIONS

                FILE I/O FUNCTIONS

                SYSTEM FUNCTIONS

                EXAMPLES









        mlisp COMMAND LOOP

        When mlisp is started, it first tries to load "init.lsp" from
        the default directory.  It then loads any files named as
        parameters on the command line (after appending ".lsp" to their
        names).  It then issues the following prompt:

        >

        This indicates that mlisp 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) mlisp 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, mlisp attempts to
        evaluate that expression.  If the expression evaluates
        successfully, mlisp prints the result of the evaluation and then
        returns to the initial prompt waiting for another expression to
        be typed.





        BREAK COMMAND LOOP

        When mlisp 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.  mlisp 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', mlisp will continue from a correctable
        error.  If the user invokes the function 'clean-up', mlisp will
        abort the break loop and return to the top level or the next
        lower numbered break loop.  When in a break loop, mlisp prefixes
        the break level to the normal prompt.

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

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





        DATA TYPES

        There are several different data types available to mlisp
        programmers.

            o lists
            o symbols
            o strings
            o integers
            o floats
            o objects
            o arrays
            o file pointers
            o subrs (built-in functions)
            o fsubrs (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 mlisp:

        Integers, floats, strings, file pointers, subrs, fsubrs, objects
        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 subr, the remaining list elements are evaluated
            and the subr is called with these evaluated expressions as
            arguments.

            If it is an fsubr, the fsubr 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.

                If it is an object, the second list element is evaluated
                and used as a message selector.  The message formed by
                combining the selector with the values of the remaining
                list elements is sent to the object.







        LEXICAL CONVENTIONS

        The following conventions must be followed when entering mlisp
        programs:

        Comments in mlisp code begin with a semi-colon character and
        continue to the end of the line.

        Symbol names in mlisp can consist of any sequence of non-blank
        printable characters except the following:

                ( ) ' ` , " ;

        Uppercase and lowercase characters are not distinguished within
        symbol names.  All lowercase characters are mapped to uppercase
        on input.

        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 mlisp 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 mlisp 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

        mlisp defines several useful read macros:

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







        READTABLES

        The behaviour of the reader is controlled by a data structure
        called a "readtable".  The reader uses the symbol *READTABLE* 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:

                NIL             Indicating an invalid character
                :CONSTITUENT    Indicating a symbol constituent
                :WHITE-SPACE    Indicating a whitespace character
                (:TMACRO . fun) Terminating readmacro
                (:NMACRO . fun) Non-terminating readmacro

        In the case of the last two forms, the "fun" component is a
        function definition.  This can either be a pointer to 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 character is passed as an integer.  The
        readmacro function should return NIL to indicate that the
        character should be treated as white space or a value consed
        with NIL to indicate that the readmacro should be treated as an
        occurance of the specified value.  Of course, the readmacro code
        is free to read additional characters from the input stream.






        SYMBOLS

            o *obarray* - 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 *tracelimit* - number of levels of trace back information
            o *readtable* - the current readtable
            o *unbound* - indicator for unbound symbols
            o *gc-flag* - controls the printing of gc messages




        EVALUATION FUNCTIONS

        (eval )  EVALUATE AN mlisp EXPRESSION
                  the expression to be evaluated
            returns     the result of evaluating the expression

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

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

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

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





        SYMBOL FUNCTIONS

        (set  )  SET THE VALUE OF A SYMBOL
                   the symbol being set
                  the new value
            returns     the new value

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

        (setf [ ]...)  SET THE VALUE OF A FIELD
                 the field specifier (quoted):
                                            set value of a symbol
                            (car )         set car of a list node
                            (cdr )         set cdr of a list node
                            (nth  )     set nth car of a list
                            (aref  )    set nth element of an array
                            (get  )   set value of a property
                            (symbol-value ) set value of a symbol
                            (symbol-plist ) set property list of a symbol
                 the new value
            returns     the new value

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

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

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

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


        (symbol-name )  GET THE PRINT NAME OF A SYMBOL
                   the symbol
            returns     the symbol's print name

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

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

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





        PROPERTY LIST FUNCTIONS

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

        (putprop   )  PUT A PROPERTY ONTO A PROPERTY LIST
                   the symbol
                   the property value
                  the property symbol
            returns     the property value

        (remprop  )  REMOVE A PROPERTY
                   the symbol
                  the property symbol
            returns     nil





        VECTOR FUNCTIONS

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

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

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

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




        LIST FUNCTIONS

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

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

        (cxxr )  ALL CxxR COMBINATIONS
        (cxxxr )  ALL CxxxR COMBINATIONS
        (cxxxxr )  ALL CxxxxR COMBINATIONS

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

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

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

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

        (last )  RETURN THE LAST LIST NODE OF A LIST
                  the list
            returns     the last list node in the list

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

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




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

        (length )  FIND THE LENGTH OF A LIST OR STRING
                  the list or string
            returns     the length of the list or string

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

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

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

        (mapcar   []...)  APPLY FUNCTION TO SUCCESSIVE CARS
                   the function or function name
                 a list for each argument of the function
            returns     a list of the values returned

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

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



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

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






        DESTRUCTIVE LIST FUNCTIONS

        (set-car!  )  REPLACE THE CAR OF A LIST NODE
                  the list node
                  the new value for the car of the list node
            returns     the list node after updating the car

        (set-cdr!  )  REPLACE THE CDR OF A LIST NODE
                  the list node
                  the new value for the cdr of the list node
            returns     the list node after updating the cdr

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

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








        PREDICATE FUNCTIONS

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

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

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

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

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

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

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

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


        (minusp )  IS THIS NUMBER NEGATIVE?
                  the number to test
            returns     t if the number is negative, nil otherwise

        (zerop )  IS THIS NUMBER ZERO?
                  the number to test
            returns     t if the number is zero, nil otherwise

        (plusp )  IS THIS NUMBER POSITIVE?
                  the number to test
            returns     t if the number is positive, nil otherwise

        (evenp )  IS THIS NUMBER EVEN?
                  the number to test
            returns     t if the number is even, nil otherwise

        (oddp )  IS THIS NUMBER ODD?
                  the number to test
            returns     t if the number is odd, nil otherwise

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

        (eql  )  ARE THE EXPRESSIONS IDENTICAL?
                                (WORKS WITH NUMBERS AND STRINGS)
                 the first expression
                 the second expression
            returns     t if they are equal, nil otherwise

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










        CONTROL CONSTRUCTS

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

        (and []...)  THE LOGICAL AND OF A LIST OF EXPRESSIONS
                  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 []...)  THE LOGICAL OR OF A LIST OF EXPRESSIONS
                  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   [])  EXECUTE EXPRESSIONS CONDITIONALLY
                 the test expression
                 the expression to be evaluated if texpr is non-nil
                 the expression to be evaluated if texpr is nil
            returns     the value of the selected expression

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

        (let ([]...) []...)  CREATE LOCAL BINDINGS
        (let* ([]...) []...)  LET WITH SEQUENTIAL 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
                  the expressions to be evaluated
            returns     the value of the last expression

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

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







        LOOPING CONSTRUCTS

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

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

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










        THE PROGRAM FEATURE

        (prog ([]...) []...)  THE PROGRAM FEATURE
        (prog* ([]...) []...)  PROG WITH SEQUENTIAL 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
                  expressions to evaluate or tags (symbols)
            returns     nil or the argument passed to the return function

        (go )  GO TO A TAG WITHIN A PROG CONSTRUCT
                   the tag (quoted)
            returns     never returns

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

        (prog1  []...)  EXECUTE EXPRESSIONS SEQUENTIALLY
                 the first expression to evaluate
                  the remaining expressions to evaluate
            returns     the value of the first expression

        (prog2   []...)  EXECUTE EXPRESSIONS SEQUENTIALLY
                 the first expression to evaluate
                 the second expression to evaluate
                  the remaining expressions to evaluate
            returns     the value of the second expression

        (progn []...)  EXECUTE EXPRESSIONS SEQUENTIALLY
                  the expressions to evaluate
            returns     the value of the last expression (or nil)







        DEBUGGING AND ERROR HANDLING

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

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

        (break [ []])  ENTER A BREAK LOOP
                  the break message string (defaults to "**BREAK**")
                   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  [])  TRAP ERRORS
                  the expression to execute
                 flag to control printing of the error message
            returns     the value of the last expression consed with nil
                        or nil on error

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

        (evalhook    [])  EVALUATE WITH HOOKS
                  the expression to evaluate
                 the value for *evalhook*
                 the value for *applyhook*
                   the environment (default is nil)
            returns     the result of evaluating the expression







        ARITHMETIC FUNCTIONS

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

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

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

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

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

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

        (1+ )  ADD ONE TO A NUMBER
                  the number
            returns     the number plus one

        (1- )  SUBTRACT ONE FROM A NUMBER
                  the number
            returns     the number minus one

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

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

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

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

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

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

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

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

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

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

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







        BITWISE LOGICAL FUNCTIONS

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

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

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

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








        RELATIONAL FUNCTIONS

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

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

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

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

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

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

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









        STRING FUNCTIONS

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

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

        (strcat []...)  CONCATENATE STRINGS
                  the strings to concatenate
            returns     the result of concatenating the strings

        (substr   []) EXTRACT A SUBSTRING
                  the string
                 the starting position
                 the length (default is rest of string)
            returns     substring starting at  for 









        INPUT/OUTPUT FUNCTIONS

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

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

        (prin1  [])  PRINT A LIST OF VALUES
                  the expressions to be printed
                  the output sink (default is standard output)
            returns     the expression

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

        (terpri [])  TERMINATE THE CURRENT PRINT LINE
                  the output sink (default is standard output)
            returns     nil

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

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









        FILE I/O FUNCTIONS

        (openi )  OPEN AN INPUT FILE
                 the file name string or symbol
            returns     a file pointer

        (openo )  OPEN AN OUTPUT FILE
                 the file name string or symbol
            returns     a file pointer

        (close )  CLOSE A FILE
                    the file pointer
            returns     nil

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

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

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

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










        SYSTEM FUNCTIONS

        (load  [ []])  LOAD AN mlisp SOURCE FILE
                 the filename string or symbol
                 the verbose flag (default is t)
                 the print flag (default is nil)
            returns     the filename

        (transcript [])  CREATE A FILE WITH A TRANSCRIPT OF A SESSION
                 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 )  EXPAND MEMORY BY ADDING SEGMENTS
                   the number of segments to add
            returns     the number of segments added

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

        (mem)  SHOW MEMORY ALLOCATION STATISTICS
            returns     nil

        (type-of )  RETURNS THE TYPE OF THE EXPRESSION
                  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
                          :SUBR   for built-ins with evaluated arguments
                          :FSUBR  for built-ins with unevaluated arguments
                          :STRING for strings
                          :FIXNUM for integers
                          :FLONUM for floating point numbers
                          :FILE   for file pointers
                          :ARRAY  for arrays

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

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

        (address-of )  GET THE ADDRESS OF AN mlisp NODE
                  the node
            returns     the address of the node (integer)

        (exit)  EXIT mlisp
            returns     never returns








        FILE I/O FUNCTIONS

        Input from a File

        mlisp provides two functions for opening files.  To open a file
        for input, use the OPENI function.  To open a file for output,
        use the OPENO 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 SETQ
        special form or by binding it using LET or LET*.  Here is an
        example:

            (setq fp (openi "init.lsp"))

        Evaluating this expression will result in the file "init.lsp"
        being opened.  The file object that will be returned by the
        OPENI 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
        OPENO function to indicate that you will do output to the file.
        For example:

            (setq fp (openo "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 OPENO
        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 (openi "test.dat"))
                  (ex (read fp) (read fp)))
                 ((null ex) nil)
              (print ex))