Version 2.0February 6, 1988
by
David Michael Betz
127 Taylor Road
Peterborough, NH 03458(603) 924-6936 (home)
Copyright (c) 1988, by David Michael Betz
All Rights Reserved
Permission is granted for unrestricted non-commercial use
XLISP is an experimental programming language combining some of the features of Common Lisp with an object-oriented extension capability. It was implemented to allow experimentation with object-oriented programming on small computers.
There are currently implementations of XLISP running on the IBM- PC and clones under MS-DOS, on the Macintosh, the Atari-ST and the Amiga. It is completely written in the programming language C and is easily extended with user written built-in functions and classes. It is available in source form to non-commercial users.
Many Common Lisp functions are built into XLISP. In addition, XLISP defines the objects Object and Class as primitives. Object is the only class that has no superclass and hence is the root of the class hierarchy tree. Class is the class of which all classes are instances (it is the only object that is an instance of itself).
This document is a brief description of XLISP. It assumes some knowledge of LISP and some understanding of the concepts of object-oriented programming.
I recommend the book Lisp by Winston and Horn and published by Addison Wesley for learning Lisp. The first edition of this book is based on MacLisp and the second edition is based on Common Lisp. XLISP will continue to migrate towards compatibility with Common Lisp.
You will probably also need a copy of Common Lisp: The Language by Guy L. Steele, Jr., published by Digital Press to use as a reference for some of the Common Lisp functions that are described only briefly in this document.
        A Note From The Author
        If you have any problems with XLISP, feel free to contact me [me being David Betz - RBD] for
        help or advice.  Please remember that since XLISP is available
        in source form in a high level language, many users [e.g. that Dannenberg fellow - RBD] have been
        making versions available on a variety of machines.  If you call
        to report a problem with a specific version, I may not be able
        to help you if that version runs on a machine to which I don't
        have access.  Please have the version number of the version that
        you are running readily accessible before calling me.
If you find a bug in XLISP, first try to fix the bug yourself using the source code provided. If you are successful in fixing the bug, send the bug report along with the fix to me. If you don't have access to a C compiler or are unable to fix a bug, please send the bug report to me and I'll try to fix it.
Any suggestions for improvements will be welcomed. Feel free to extend the language in whatever way suits your needs. However, PLEASE DO NOT RELEASE ENHANCED VERSIONS WITHOUT CHECKING WITH ME FIRST!! I would like to be the clearing house for new features added to XLISP. If you want to add features for your own personal use, go ahead. But, if you want to distribute your enhanced version, contact me first. Please remember that the goal of XLISP is to provide a language to learn and experiment with LISP and object-oriented programming on small computers. I don't want it to get so big that it requires megabytes of memory to run.
         
        Then XLISP attempts to load  
        XLISP then issues the following prompt:
 
        When a complete expression has been entered, XLISP attempts to
        evaluate that expression.  If the expression evaluates
        successfully, XLISP prints the result and then returns to the
        initial prompt waiting for another expression to be typed.
 
         
        If the symbol  
        If the symbol  
        XLISP then enters a read/eval/print loop to allow the user to
        examine the state of the interpreter in the context of the
        error.  This loop differs from the normal top-level
        read/eval/print loop in that if the user invokes the function
         
        If the symbol  
        If there is no surrounding errset function, XLISP prints the
        error message and returns to the top level.
 
         
 
 
 
        Comments in XLISP code begin with a semi-colon character and
        continue to the end of the line.
 
        Symbol names in XLISP 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  
        Floating point literals consist of a sequence of digits
        optionally beginning with a  
        Literal strings are sequences of characters surrounded by double
        quotes.  Within quoted strings the `` 
 
        In the case of  
        XLISP defines several useful read macros:
 
        The lambda list starts with required arguments.  Required
        arguments must be specified in every call to the function.
 
        The required arguments are followed by the &optional arguments.
        Optional arguments may be provided or omitted in a call.  An
        initialization expression may be specified to provide a default
        value for an &optional argument if it is omitted from a call.
        If no initialization expression is specified, an omitted
        argument is initialized to  
        The &optional arguments are followed by the &rest argument.  The
        &rest argument gets bound to the remainder of the argument list
        after the required and &optional arguments have been removed.
 
        The &rest argument is followed by the &key arguments.  When a
        keyword argument is passed to a function, a pair of values
        appears in the argument list.  The first expression in the pair
        should evaluate to a keyword symbol (a symbol that begins with a
        `` 
        The &key arguments are followed by the &aux variables.  These
        are local variables that are bound during the evaluation of the
        function body.  It is possible to have initialization
        expressions for the &aux variables.
 
    Here is the complete syntax for lambda lists:
 
            where:
 
                rarg is a required argument symbol 
 
        Officially, there is no way to see inside an object (look at the
        values of its instance variables).  The only way to communicate
        with an object is by sending it a message.
 
        You can send a message to an object using the  
        The  
        A message can also be sent from the body of a method by using
        the current object, but the method lookup starts with the
        object's superclass rather than its class.  This allows a
        subclass to invoke a standard method in its parent class even
        though it overrides that method with its own specialized
        version.
 
        When a method is found, the evaluator binds the receiving object
        to the symbol  
 
Messages:
 
 
            Messages:
 
 
        When a new instance of a class is created by sending the message
         
        When a new class is created by sending the  
 
 
        There are several symbols maintained by the read/eval/print
        loop.  The symbols  
 
 
 
 
An unnamed input stream is setup with the 
  
 
 
 
        It is now possible to use the file for input.  To read an
        expression from the file, just supply the value of the  
        Once you are done reading from the file, you should close it.
        To close the file, use the following expression:
 
 
        It is now possible to write to this file by supplying the value
        of the  
        Once you are done writing to the file, you should close it.
        Closing an output file is just like closing an input file.
 
 
XLISP Command Loop
        When XLISP is started, it first tries to load the workspace
        xlisp.wks from the current directory.  If that file doesn't
        exist, XLISP builds an initial workspace, empty except for the
        built-in functions and symbols.
init.lsp from the current
        directory.  It then loads any files named as parameters on the
        command line (after appending .lsp to their names).
        >
        This indicates that XLISP is waiting for an expression to be
        typed.
Break Command Loop
        When XLISP encounters an error while evaluating an expression,
        it attempts to handle the error in the following way:
*breakenable* is true, the message corresponding
        to the error is printed.  If the error is correctable, the
        correction message is printed.
*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.
continue, XLISP will continue from a correctable error.  If
        the user invokes the function clean-up, XLISP will abort the
        break loop and return to the top level or the next lower
        numbered break loop.  When in a break loop, XLISP prefixes the
        break level to the normal prompt.
*breakenable* is nil, XLISP looks for a
        surrounding errset function.  If one is found, XLISP examines
        the value of the print flag.  If this flag is true, the error
        message is printed.  In any case, XLISP causes the errset
        function call to return nil.
Data Types
        There are several different data types available to XLISP
        programmers.
The Evaluator
        The process of evaluation in XLISP:
Then, the value produced by the previous step is examined:
Lexical Conventions
        The following conventions must be followed when entering XLISP
        programs:
                ( ) ' ` , " ;
        Uppercase and lowercase characters are not distinguished within
        symbol names.  All lowercase characters are mapped to uppercase
        on input.
+ or -.  The range of values an integer can
        represent is limited by the size of a C long on the machine on
        which XLISP is running.
+ 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 XLISP is
        running.
\'' 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
Readtables
        The behavior 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
:SESCAPE -       Single escape character ('\')
:MESCAPE -       Multiple escape character ('|')
:TMACRO and :NMACRO, the fun component is a
        function.  This can either be a built-in readmacro function or a
        lambda expression.  The function should take two parameters.
        The first is the input stream and the second is the character
        that caused the invocation of the readmacro.  The readmacro
        function should return 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 occurence of the
        specified value.  Of course, the readmacro code is free to read
        additional characters from the input stream.
Lambda Lists
        There are several forms in XLISP that require that a ``lambda
        list'' be specified.  A lambda list is a definition of the
        arguments accepted by a function.  There are four different
        types of arguments.
NIL.  It is also possible to provide
        the name of a supplied-p variable that can be used to
        determine if a call provided a value for the argument or if the
        initialization expression was used.  If specified, the supplied-
        p variable will be bound to T if a value was specified in the
        call and NIL if the default value was used.
:'').  The value of the second expression is the value of the
        keyword argument.  Like &optional arguments, &key arguments can
        have initialization expressions and supplied-p variables.  In
        addition, it is possible to specify the keyword to be used in a
        function call.  If no keyword is specified, the keyword obtained
        by adding a ``:'' to the beginning of the keyword argument symbol
        is used.  In other words, if the keyword argument symbol is
        foo, the keyword will be ':foo.
                (rarg...
                 [&optional [oarg | (oarg [init [svar]])]...]
                 [&rest rarg]
                 [&key
                   [karg | ([karg | (key karg)] [init [svar]])]...
                   &allow-other-keys]
                 [&aux
                   [aux | (aux [init])]...])
                oarg is an &optional argument symbol
                rarg is the &rest argument symbol
                karg is a &key argument symbol
                key is a keyword symbol
                aux is an auxiliary variable symbol
                init is an initialization expression
                svar is a supplied-p variable symbol
Objects
        Definitions:
Since XLISP was created to provide a simple basis for
        experimenting with object-oriented programming, one of the
        primitive data types included is object.  In XLISP, an object
        consists of a data structure containing a pointer to the
        object's class as well as an array containing the values of the
        object's instance variables.send function.
        This function takes the object as its first argument, the
        message selector as its second argument (which must be a symbol)
        and the message arguments as its remaining arguments.
send function determines the class of the receiving object
        and attempts to find a method corresponding to the message
        selector in the set of messages defined for that class.  If the
        message is not found in the object's class and the class has a
        super-class, the search continues by looking at the messages
        defined for the super-class.  This process continues from one
        super-class to the next until a method for the message is found.
        If no method is found, an error occurs.
self and evaluates the method using the
        remaining elements of the original list as arguments to the
        method.  These arguments are always evaluated prior to being
        bound to their corresponding formal arguments.  The result of
        evaluating the method becomes the result of the expression.
The ``Object'' Class
Object - the top of the class hierarchy.
:show - show an object's instance variables.
:class - return the class of an object
:isnew - the default object initialization routine
:sendsuper sel args... - send superclass a message
args - the message arguments
returns -  the result of sending the message
The ``Class'' Class
Class - class of all object classes (including itself)
                    cvars -    the list of class variable symbols
                    super -    the superclass (default is object)
                    returns -    the new class object
                fargs -    the formal argument list (lambda list)
                    code -     a list of executable expressions
                    returns -    the object
:new to an existing class, the message :isnew followed by
        whatever parameters were passed to the :new message is sent to
        the newly created object.
:new message to the
        object Class, an optional parameter may be specified
        indicating the superclass of the new class.  If this parameter
        is omitted, the new class will be a subclass of Object.  A
        class inherits all instance variables, class variables, and
        methods from its super-class.
Profiling
The Xlisp 2.0 release has been extended with a profiling facility, which counts how many times and where eval is executed.  A separate count is maintained for each named function, closure, or macro, and a count indicates an eval in the immediately (lexically) enclosing named function, closure, or macro.  Thus, the count gives an indication of the amount of time spent in a function, not counting nested function calls.  The list of all functions executed is maintained on the global *profile* variable.  These functions in turn have *profile* properties, which maintain the counts.  The profile system merely increments counters and puts symbols on the *profile* list.  It is up to the user to initialize data and gather results.  Profiling is turned on or off with the profile function.  Unfortunately, methods cannot be profiled with this facility.
SYMBOLS
self - the current object (within a method context)
*obarray* - the object hash table
*standard-input* - the standard input stream
*standard-output* - the standard output stream
*error-output* - the error output stream
*trace-output* - the trace output stream
*debug-io* - the debug i/o stream
*breakenable* - flag controlling entering break loop on errors
*tracelist* - list of names of functions to trace
*tracenable* - enable trace back printout on errors
*tracelimit* - number of levels of trace back information
*evalhook* - user substitute for the evaluator function
*applyhook* - (not yet implemented)
*readtable* - the current readtable
*unbound* - indicator for unbound symbols
*gc-flag* - controls the printing of gc messages
*gc-hook* - function to call after garbage collection
*integer-format* - format for printing integers (``%d'' or ``%ld'')
*float-format* - format for printing floats (``%g'')
*print-case* - symbol output case (:upcase or :downcase)
+, ++, and +++ are bound to the most
        recent three input expressions.  The symbols *, ** and ***
        are bound to the most recent three results.  The symbol - is
        bound to the expression currently being evaluated.  It becomes
        the value of + at the end of the evaluation.
Evaluation Functions
            returns -     the result of evaluating the expression
            args -     the argument list
            returns -    the result of applying the function to the arguments
            arg -      arguments to pass to the function
            returns -    the result of calling the function with the arguments
            returns   -  expr unevaluated
            returns  -   the functional interpretation
            returns  -   a copy of the template with comma and comma-at
             expressions expanded
            expr -     expressions of the function body
            returns  -   the function closure
            returns  -   the original lambda expression
            returns  -   the macro expansion
            returns  -   the macro expansion
Symbol Functions
            expr -     the new value
            returns  -   the new value
            expr -     the new value
            returns  -   the new value
            expr -     the new value
            returns  -   the new value
expr -     the new value
  (car expr)  -          set car of a cons node
  (cdr expr)  -          set cdr of a cons node
  (nth n expr) -       set nth car of a list
  (aref expr n) -       set nth element of an array
  (get sym prop) -      set value of a property
  (symbol-value sym) -   set value of a symbol
  (symbol-function sym) - set functional value of a symbol
  (symbol-plist sym) -    set property list of a symbol
        returns  -   the new value
        (defmacro sym fargs expr...) -  define a macro
            fargs -     formal argument list (lambda list) (quoted)
            expr  -    expressions constituting the body of the
                        function (quoted)
            returns   -  the function symbol
            returns   -  the new symbol
            returns   -  the new symbol
            returns   -  the new symbol
            returns   -  the symbol's print name
            returns   -  the symbol's value
            returns   -  the symbol's functional value
            returns   -  the symbol's property list
            n     -    the table size (integer)
            returns   -  the hash index (integer)
Property List Functions
            prop  -    the property symbol
            returns   -  the property value or nil
            val   -    the property value
            prop  -    the property symbol
            returns   -  the property value
            prop  -    the property symbol
            returns   -  nil
Array Functions
            n     -    the array index (integer)
            returns   -  the value of the array element
            returns   -  the new array
            returns   -  the new vector
List Functions
            returns   -  the car of the list node
            returns   -  the cdr of the list node
            expr2 -    the cdr of the new list node
            returns   -  the new list node
            returns   -  the new list
            returns   -  the new list
            returns   -  a new list in the reverse order
            returns   -  the last list node in the list
            list  -    the list to search
            :test     -  the test function (defaults to eql)
            :test-not -  the test function (sense inverted)      
            returns   -  the remainder of the list starting with the expression
            alist -    the association list
            :test     -  the test function (defaults to eql)
            :test-not -  the test function (sense inverted)      
            returns   -  the alist entry or nil
            list  -    the list
            :test     -  the test function (defaults to eql)
            :test-not -  the test function (sense inverted)      
            returns   -  copy of list with matching expressions removed
            list  -    the list
            returns   -  copy of list with matching elements removed
            list  -    the list
            returns   -  copy of list with non-matching elements removed
            returns   -  the length of the list, vector or string
            list  -    the list
            returns   -  the nth element or nil if the list isn't that long
            list  -    the list
            returns   -  the nth cdr or nil if the list isn't that long
            listn -    a list for each argument of the function
            returns   -  the first list of arguments
            listn -    a list for each argument of the function
            returns   -  a list of the values returned
            listn -    a list for each argument of the function
            returns   -  the first list of arguments
            listn -    a list for each argument of the function
            returns   -  a list of the values returned
            from  -    the old expression
            expr  -    the expression in which to do the substitutions
            :test     -  the test function (defaults to eql)
            :test-not -  the test function (sense inverted)      
            returns   -  the expression with substitutions
            expr  -    the expression in which to do the substitutions
            :test     -  the test function (defaults to eql)
            :test-not -  the test function (sense inverted)      
            returns   -  the expression with substitutions
Destructive List Functions
            expr -     the new value for the car of the list node
            returns  -   the list node after updating the car
            expr -     the new value for the cdr of the list node
            returns  -   the list node after updating the cdr
            returns  -   the result of concatenating the lists
            list -     the list
            :test    -   the test function (defaults to eql)
            :test-not -   the test function (sense inverted)      
            returns   -  the list with the matching expressions deleted
            list  -    the list
            returns   -  the list with matching elements deleted
            list  -    the list
            returns   -  the list with non-matching elements deleted
            test  -    the comparison function
            returns   -  the sorted list
Predicate Functions
            returns   - t if the value is an atom, nil otherwise
            returns   - t if the expression is a symbol, nil otherwise
            returns   - t if the expression is a number, nil otherwise
            returns   - t if the list is empty, nil otherwise
            return    - t if the value is nil, nil otherwise
            returns   - t if the value is a cons or nil, nil otherwise
            returns   - t if the value is nil, nil otherwise
            returns   - t if the value is a cons, nil otherwise
            returns   - t if the value is an integer, nil otherwise
            returns   - t if the value is a float, nil otherwise
            returns   - t if the value is a string, nil otherwise
            returns   - t if the value is a character, nil otherwise
            returns   - t if the value is an array, nil otherwise
            returns   - t if the value is a stream, nil otherwise
            returns   - t if the value is an object, nil otherwise
            returns   - t if a value is bound to the symbol, nil otherwise
            returns   - t if a functional value is bound to the symbol,
                        nil otherwise
            returns   - t if the number is negative, nil otherwise
            returns   - t if the number is zero, nil otherwise
            returns   - t if the number is positive, nil otherwise
            returns   - t if the integer is even, nil otherwise
            returns   - t if the integer is odd, nil otherwise
            expr2 -    the second expression
            returns   - t if they are equal, nil otherwise
            expr2 -    the second expression
            returns   - t if they are equal, nil otherwise
            expr2 -    the second expression
            returns   - t if they are equal, nil otherwise
Control Constructs
where:
returns  -   the value of the first expression whose predicate is not
                            expr -     evaluated if the predicate
 is not nil
nil
            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)
            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)
            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
            expr  -    the expression(s) to be evaluated if texpr is non-nil
            returns - the value of the last expression or nil
            expr  -    the expression(s) to be evaluated if texpr is nil
            returns   -  the value of the last expression or nil
            case  -    pair consisting of:
where:
returns -     the value of the last expression of the matching case
                            expr  -    are expressions to execute if the
                                        case matches
        (let* (binding...) expr...)  - let with sequential binding
expr -     the expressions to be evaluatednil)
                        2)  a list whose car is a symbol and whose cadr
                                is an initialization expression
            returns  -   the value of the last expression
        (labels (binding...) expr...) -  flet with recursive functions
        (macrolet (binding...) expr...) -  create local macros
where:
expr -     the expressions to be evaluated
                            fargs -     formal argument list (lambda list)
                            expr  -    expressions constituting the body of
                                        the function/macro
            returns  -   the value of the last expression
            expr -     expressions to evaluate
            returns  -   the value of the last expression the throw expression
            expr -     the value for the catch to return (defaults to nil)
            returns  -   never returns
            cexpr -     the cleanup expressions
            returns   -  the value of the expression
          Note:  unwind-protect guarantees to execute the cleanup expressions
                 even if a non-local exit terminates the evaluation of the
                 protected expression
Looping Constructs
            returns  -   never returns (must use non-local exit)
        (do* (binding...) (texpr rexpr...) expr...)
texpr -    the termination test expressionnil)
                        2)  a list of the form: (sym init [step])
                            where:
                                init - is the initial value of the symbol
                                step - is a step 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
            expr  -    the list expression
            rexpr -    the result expression (the default is nil)
            expr  -    the body of the loop (treated like an implicit prog)
            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
(prog* (binding...) expr...)  - prog with sequential binding
expr  -    expressions to evaluate or tags (symbols)nil)
                        2)  a list whose car is a symbol and whose cadr
                                is an initialization expression
            returns   -  nil or the argument passed to the return function
            expr  -    the block body
            returns   -  the value of the last expression
nil)
            returns   -  never returns
            value -    the value to return (defaults to nil)
            returns   -  never returns
            returns   -  nil
            returns   -  never returns
            vlist -    list of values to bind to the symbols
            expr  -    expression(s) to evaluate
            returns   -  the value of the last expression
            expr  -    the remaining expressions to evaluate
            returns   -  the value of the first expression
            expr2 -    the second expression to evaluate
            expr  -    the remaining expressions to evaluate
            returns   -  the value of the second expression
            returns   -  the value of the last expression (or nil)
Debugging and Error Handling
            returns   -  the trace list
            returns   -  the trace list
            arg   -    the argument expression (printed after the message)
            returns   -  never returns
            emsg  -    the error message string
            arg   -    the argument expression (printed after the message)
            returns   -  nil when continued from the break loop
**break**)
            arg   -    the argument expression (printed after the message)
            returns   -  nil when continued from the break loop
            pflag -    flag to control printing of the error message
            returns   -  the value of the last expression consed with nil
                        or nil on error
            returns   -  nil
            ehook -    the value for *evalhook*
            ahook -    the value for *applyhook*
            env   -    the environment (default is nil)
            returns   -  the result of evaluating the expression
nil turns profiling off, otherwise on
            returns   -  the previous state of profiling.
Arithmetic Functions
            returns   -  the result of truncating the number
            returns   -  the result of floating the integer
            returns   -  the result of the addition
            returns   -  the result of the subtraction
            returns   -  the result of the multiplication
            returns   -  the result of the division
            returns   -  the number plus one
            returns   -  the number minus one
            returns   -  the result of the remainder operation
            returns   -  the smallest number in the list
            returns   -  the largest number in the list
            returns   -  the absolute value of the number
            n2    -    the second number(s) (integer)
            returns   -  the greatest common divisor
            returns   -  a random number
            returns   -  the sine of the number
            returns   -  the cosine of the number
            returns   -  the tangent of the number
            y-expr -   the floating point exponent
            returns    - x to the y power
            returns   -  e to the x power
            returns   -  the square root of the number
(<= n1 n2...) -  test for less than or equal to
(= n1 n2...)  - test for equal to
(/= n1 n2...) -  test for not equal to
(>= n1 n2...) -   test for greater than or equal to
(> n1 n2...) -   test for greater than
            n2    -    the second number to compare
returns   -  t if the results of comparing n1 with n2,
n2 with n3, etc., are all true.
Bitwise Logical Functions
            returns   -  the result of the and operation
            returns   -  the result of the inclusive or operation
            returns   -  the result of the exclusive or operation
            returns   -  the bitwise inversion of number
String Functions
            returns   -  a one character string
            str   -    the string to be searched
            :start    -  the starting offset in str
            :end      -  the ending offset + 1
            returns   -  index of pat in str or NIL if not found
            str   -    the string to trim
            returns   -  a trimed copy of the string
            str   -    the string to trim
            returns   -  a trimed copy of the string
            str   -    the string to trim
            returns   -  a trimed copy of the string
            :start    -  the starting offset
            :end      -  the ending offset + 1
            returns   -  a converted copy of the string
            :start    -  the starting offset
            :end      -  the ending offset + 1
            returns   -  a converted copy of the string
            :start    -  the starting offset
            :end      -  the ending offset + 1
            returns   -  the converted string (not a copy)
            :start    -  the starting offset
            :end      -  the ending offset + 1
            returns  -   the converted string (not a copy)
            returns  -   the result of concatenating the strings
            start  -   the starting position (zero origin)
            end    -   the ending position + 1 (defaults to end)
            returns    - substring between start and end
        (string<= str1 str2 &key :start1 :end1 :start2 :end2)
        (string= str1 str2 &key :start1 :end1 :start2 :end2)
        (string/= str1 str2 &key :start1 :end1 :start2 :end2)
        (string>= str1 str2 &key :start1 :end1 :start2 :end2)
        (string> str1 str2 &key :start1 :end1 :start2 :end2)
            str2 -     the second string to compare
            :start1  -   first substring starting offset
            :end1    -   first substring ending offset + 1
            :start2  -   second substring starting offset
            :end2    -   second substring ending offset + 1
            returns  -   t if predicate is true, nil otherwise
          Note: case is significant with these comparison functions.
(string-not-greaterp str1 str2 &key :start1 :end1 :start2 :end2)
(string-equalp str1 str2 &key :start1 :end1 :start2 :end2)
(string-not-equalp str1 str2 &key :start1 :end1 :start2 :end2)
(string-not-lessp str1 str2 &key :start1 :end1 :start2 :end2)
(string-greaterp str1 str2 &key :start1 :end1 :start2 :end2)
            str2 -     the second string to compare
            :start1  -   first substring starting offset
            :end1    -   first substring ending offset + 1
            :start2  -   second substring starting offset
            :end2    -   second substring ending offset + 1
    returns  -   t if predicate is true, nil otherwise
          Note: case is not significant with these comparison functions.
Character Functions
            index  -   the string index (zero relative)
            returns    - the ascii code of the character
            returns -    t if the character is upper case, nil otherwise
            returns -    t if the character is lower case, nil otherwise
            returns -    t if the character is alphabetic, nil otherwise
            returns -    the digit weight if character is a digit, nil otherwise
            returns -    the ascii character code (integer)
            returns  -   the character with that code or nil
            returns  -   the upper case character
            returns  -   the lower case character
            returns  -   the digit character or nil
            returns  -   the ascii character code
            returns  -   the character with that code
        (char<= chr1 chr2...)
        (char= chr1 chr2...)
        (char/= chr1 chr2...)
        (char>= chr1 chr2...)
        (char> chr1 chr2...)
            chr2 -     the second character(s) to compare
            returns  -   t if predicate is true, nil otherwise
          Note: case is significant with these comparison functions.
(char-not-greaterp chr1 chr2...)
(char-equalp chr1 chr2...)
(char-not-equalp chr1 chr2...)
(char-not-lessp chr1 chr2...)
(char-greaterp chr1 chr2...)
chr2 -     the second string(s) to compare
returns  -   t if predicate is true, nil otherwise
Input/Output Functions
            eof    -   the value to return on end of file (default is nil)
            rflag  -   recursive read flag (default is nil)
            returns    - the expression read
            stream -   the output stream (default is standard output)
            returns    - the expression
            stream -   the output stream (default is standard output)
            returns    - the expression
            stream -   the output stream (default is standard output)
            returns   -  the expression
            stream -   the output stream (default is standard output)
            returns -    the expression
            returns   -  nil
            returns  -   the length
            returns  -   the length
The Format Function
       The format string can contain characters that should be copied
        directly to the output and formatting directives.  The
        formatting directives are:
~A - print next argument using princ
~S - print next argument using prin1
~% - start a new line
~~ - print a tilde character
File I/O Functions
Note that files are ordinarily opened as text. Binary files (such as standard midi files) must be opened with open-binary on non-unix systems.
            :direction - :input or :output (default is :input)
            returns   -  a stream
            :direction - :input or :output (default is :input)
            returns   -  a stream
            returns    - nil
            returns   -  the character
nil)
            stream -    the input stream (default is standard input)
            returns   -  the character (integer)
            stream -   the output stream (default is standard output)
            returns   -  the character
            length - the length of the integer in bytes (default is 4)
            returns   -  the integer
Note: Integers are assumed to be big-endian (high-order byte first) and 
signed, regardless of the platform. To read little-endian format, use a
negative number for the length, e.g. -4 indicates a 4-bytes, low-order
byte first. The file should be opened in binary mode.
            stream -   the output stream (default is standard output)
            length - the length of the integer in bytes (default is 4)
            returns   -  the integer
Note: Integers are assumed to be big-endian (high-order byte first) and 
signed, regardless of the platform. To write in little-endian format, use a
negative number for the length, e.g. -4 indicates a 4-bytes, low-order
byte first. The file should be opened in binary mode.
            length - the length of the float in bytes (default is 4, legal values are -4, -8, 4, and 8)
            returns   -  the integer
Note: Floats are assumed to be big-endian (high-order byte first) and 
signed, regardless of the platform. To read little-endian format, use a
negative number for the length, e.g. -4 indicates a 4-bytes, low-order
byte first. The file should be opened in binary mode.
            stream -   the output stream (default is standard output)
            length - the length of the float in bytes (default is 4, legal values are -4, -8, 4, and 8)
            returns   -  the integer
Note: Floats are assumed to be big-endian (high-order byte first) and 
signed, regardless of the platform. To write in little-endian format, use a
negative number for the length, e.g. -4 indicates a 4-bytes, low-order
byte first. The file should be opened in binary mode.
            returns   -  the string
            returns    - the byte (integer)
            stream -   the output stream (default is standard output)
            returns    - the byte (integer)
String Stream Functions
        These functions operate on unnamed streams.  An unnamed output
        stream collects characters sent to it when it is used as the
        destination of any output function.  The functions 
get-output-stream-string and string or a list of characters.
make-string-input-stream function and returns each character of the string when
        it is used as the source of any input function.
            start  -   the starting offset
            end    -   the ending offset + 1
            returns    - an unnamed stream that reads from the string
            returns    - the output so far as a string
          Note:  the output stream is emptied by this function
            returns   -  the output so far as a list
          Note:  the output stream is emptied by this function
System Functions
Note: the load function first tries to load a file from the current directory. A .lsp extension is added if there is not already an alphanumeric extension following  a period.  If that fails, XLisp searches the path, which is obtained from the XLISPPATH environment variable in Unix and  HKEY_LOCAL_MACHINE\SOFTWARE\CMU\Nyquist\XLISPPATH under Win32. (The Macintosh version has no search path.)
            :verbose  -  the verbose flag (default is t)
            :print    -  the print flag (default is nil)
            returns   -  the filename
            returns   - t if workspace was written, nil otherwise
            returns   -  nil on failure, otherwise never returns
            returns   - t if the transcript is opened, nil if it is closed
nil
            returns -    the number of segments added
            returns -    the old number of nodes to allocate
nil
            returns  -   nil if the value is nil otherwise one of the symbols:
                          OBJECT      -    for objects
                          CONS        -    for conses
                          SUBR        -    for built-in functions
                          FSUBR       -    for special forms
                          CLOSURE     -    for defined functions
                          STRING      -    for strings
                          FIXNUM      -    for integers
                          FLONUM      -    for floating point numbers
                          CHARACTER   -    for characters
                          FILE-STREAM -    for file pointers
                          UNNAMED-STREAM - for unnamed streams
                          ARRAY          - for arrays
            returns    - the value at the specified address (integer)
            value  -   the value to poke into the address (integer)
            returns    - the value
            returns    - the address of the node (integer)
Note: Under Windows, Nyquist normally starts up in a medium-sized console window with black text and a white background, with a window title of ``Nyquist.'' This is normally accomplished by calling setup-console in system.lsp. In Nyquist, you can avoid this behavior by setting *setup-console* to NIL in your init.lsp file. If setup-console is not called, Nyquist uses standard input and output as is. This is what you want if you are running Nyquist inside of emacs, for example.
File I/O Functions
Input from a File
To open a file for input, use the open function with the keyword
argument :direction set to :input.  To open a file for output,
use the open function with the keyword argument :direction set
to :output.  The open function takes a single required argument which
is the name of the file to be opened.  This name can be in the form of a
string or a symbol.  The open function returns an object of type
FILE-STREAM if it succeeds in opening the specified file.  It returns the
value nil if it fails.  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 (open "init.lsp" :direction :input))
        Evaluating this expression will result in the file init.lsp
        being opened.  The file object that will be returned by the open
        function will be assigned to the variable fp.
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).
(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 function to indicate that you will do output to the file.
        For example:
(setq fp (open "test.dat" :direction :output))
        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-STREAM object will be returned by the OPEN
        function.  This file object will be assigned to the fp
        variable.
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 the same technique.
(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 "test.dat" :direction :input))
      (ex (read fp) (read fp)))
     ((null ex) nil)
  (print ex))
Previous Section | Next Section (Index) | Table of Contents | Title Page