Article-I.D.: cwruecmp.1380
Posted: Sat Jan 18 14:58:57 1986
Date-Received: Mon, 20-Jan-86 05:18:07 EST
Organization: CWRU Dept. Computer Eng., Cleveland, OH
Lines: 1432

#!/bin/sh
# This is a shell archive, meaning:
# 1. Remove everything above the #!/bin/sh line.
# 2. Save the resulting text in a file.
# 3. Execute the file with /bin/sh (not csh) to create the files:
#	xlisp.doc
#	read.me
# This archive created: Sat Jan 18 14:32:17 1986
# By:	Jwahar R. Bammi ()
export PATH; PATH=/bin:$PATH
echo shar: extracting "'xlisp.doc'" '(53933 characters)'
if test -f 'xlisp.doc'
then
	echo shar: over-writing existing file "'xlisp.doc'"
fi
sed 's/^X//' << \SHAR_EOF > 'xlisp.doc'
X
X
X
X
X
X                 XLISP: An Experimental Object Oriented Language
X
X                                   Version 1.5
X
X                                  May 27, 1985
X
X
X                                        by
X                                David Michael Betz
X                                114 Davenport Ave.
X                              Manchester, NH  03103
X
X                              (603) 625-4691 (home)
X
X                    Copyright (c) 1985, by David Michael Betz
X                               All Rights Reserved
X            Permission is granted for unrestricted non-commercial use
X
X
X      XLISP: An Experimental Object Oriented Language                 Page 2
X      TABLE OF CONTENTS
X
X
X                                         CONTENTS
X
X              1       INTRODUCTION . . . . . . . . . . . . . . . . . . . . 3
X              2       A NOTE FROM THE AUTHOR . . . . . . . . . . . . . . . 4
X              3       XLISP COMMAND LOOP   . . . . . . . . . . . . . . . . 5
X              4       BREAK COMMAND LOOP   . . . . . . . . . . . . . . . . 6
X              5       DATA TYPES . . . . . . . . . . . . . . . . . . . . . 7
X              6       THE EVALUATOR  . . . . . . . . . . . . . . . . . . . 8
X              7       LEXICAL CONVENTIONS  . . . . . . . . . . . . . . . . 9
X              8       OBJECTS  . . . . . . . . . . . . . . . . . . . . .  10
X              8.1       THE 'Object' CLASS . . . . . . . . . . . . . . .  11
X              8.2       THE 'Class' CLASS  . . . . . . . . . . . . . . .  12
X              9       SYMBOLS  . . . . . . . . . . . . . . . . . . . . .  13
X              10      FUNCTION DEFINITIONS . . . . . . . . . . . . . . .  14
X              10.1      EVALUATION FUNCTIONS . . . . . . . . . . . . . .  14
X              10.2      SYMBOL FUNCTIONS . . . . . . . . . . . . . . . .  15
X              10.3      PROPERTY LIST FUNCTIONS  . . . . . . . . . . . .  17
X              10.4      LIST FUNCTIONS . . . . . . . . . . . . . . . . .  18
X              10.5      DESTRUCTIVE LIST FUNCTIONS . . . . . . . . . . .  21
X              10.6      PREDICATE FUNCTIONS  . . . . . . . . . . . . . .  22
X              10.7      CONTROL FUNCTIONS  . . . . . . . . . . . . . . .  24
X              10.8      LOOPING FUNCTIONS  . . . . . . . . . . . . . . .  25
X              10.9      THE PROGRAM FEATURE  . . . . . . . . . . . . . .  26
X              10.10     DEBUGGING AND ERROR HANDLING . . . . . . . . . .  27
X              10.11     ARITHMETIC FUNCTIONS . . . . . . . . . . . . . .  28
X              10.12     BITWISE LOGICAL FUNCTIONS  . . . . . . . . . . .  30
X              10.13     RELATIONAL FUNCTIONS . . . . . . . . . . . . . .  31
X              10.14     STRING FUNCTIONS . . . . . . . . . . . . . . . .  32
X              10.15     INPUT/OUTPUT FUNCTIONS . . . . . . . . . . . . .  33
X              10.16     FILE I/O FUNCTIONS . . . . . . . . . . . . . . .  34
X              10.17     SYSTEM FUNCTIONS . . . . . . . . . . . . . . . .  35
X
X
X      XLISP: An Experimental Object Oriented Language                 Page 3
X      INTRODUCTION
X
X
X      1  INTRODUCTION
X
X      XLISP is an experimental programming language combining  some  of  the
X      features of LISP with an object oriented extension capability.  It was
X      implemented to allow experimentation with object oriented  programming
X      on  small  computers.   There are currently implementations running on
X      the the VAX under VAX/VMS and  Berkeley  VAX/UNIX,  on  the  8088/8086
X      under  CP/M-86  and  MS-DOS,  on  the  68000 under CP/M-68K and on the
X      Macintosh.  It is completely written in the programming  language  'C'
X      and  is  easily  extended  with  user  written  built-in functions and
X      classes.   It  is  available  in  source  form  free  of   charge   to
X      non-commercial users.
X
X      Many traditional LISP functions are built into  XLISP.   In  addition,
X      XLISP   defines  the  objects  'Object'  and  'Class'  as  primitives.
X      'Object' is the only class that has no superclass  and  hence  is  the
X      root  of  the class heirarchy tree.  'Class' is the class of which all
X      classes are instances (it is the only object that is  an  instance  of
X      itself).
X
X      This document is a  brief  description  of  XLISP.   It  assumes  some
X      knowledge   of   LISP  and  some  understanding  of  the  concepts  of
X      object-oriented programming.
X
X      A recommended text for learning LISP programming is the book "LISP" by
X      Winston  and  Horn and published by Addison Wesley.  The first edition
X      of this book is based on MacLisp and the second edition  is  based  on
X      Common  Lisp.   Future  versions  of  XLISP  will  continue to migrate
X      towards compatibility with Common Lisp.
X
X
X      XLISP: An Experimental Object Oriented Language                 Page 4
X      A NOTE FROM THE AUTHOR
X
X
X      2  A NOTE FROM THE AUTHOR
X
X      If you have any problems with XLISP, feel free to contact me for  help
X      or  advice.   Please  remember that since XLISP is available in source
X      form in a high level language, many users have  been  making  versions
X      available  on  a variety of machines.  If you call to report a problem
X      with a specific version, I may not be able to help you if that version
X      runs  on  a  machine  to  which  I don't have access.  Please have the
X      version number of the version that you are running readily  accessible
X      before calling me.
X
X      If you find a bug in XLISP, first try to fix the  bug  yourself  using
X      the  source  code  provided.  If you are successful in fixing the bug,
X      send the bug report along with the fix  to  me.   If  you  don't  have
X      access to a C compiler or are unable to fix a bug, please send the bug
X      report to me and I'll try to fix it.
X
X      Any suggestions for improvements  will  be  welcomed.   Feel  free  to
X      extend the language in whatever way suits your needs.  However, PLEASE
X      DO NOT RELEASE ENHANCED VERSIONS WITHOUT CHECKING WITH ME  FIRST!!   I
X      would  like  to be the clearing house for new features added to XLISP.
X      If you want to add features for your own personal use, go ahead.  But,
X      if  you  want  to  distribute your enhanced version, contact me first.
X      Please remember that the goal of XLISP is to  provide  a  language  to
X      learn  and  experiment  with  LISP  and object-oriented programming on
X      small computers.  I don't want it to  get  so  big  that  it  requires
X      megabytes of memory to run.
X
X
X      XLISP: An Experimental Object Oriented Language                 Page 5
X      XLISP COMMAND LOOP
X
X
X      3  XLISP COMMAND LOOP
X
X      When XLISP is started, it first tries  to  load  "init.lsp"  from  the
X      default directory.  It then loads any files named as parameters on the
X      command line (after appending ".lsp" to their names).  It then  issues
X      the following prompt:
X
X      >
X
X      This indicates that XLISP is waiting for an expression  to  be  typed.
X      When  an  incomplete expression has been typed (one where the left and
X      right parens don't match) XLISP changes its prompt to:
X
X      n>
X
X      where n is an integer indicating how many levels of left parens remain
X      unclosed.
X
X      When a  complete  expression  has  been  entered,  XLISP  attempts  to
X      evaluate  that  expression.  If the expression evaluates successfully,
X      XLISP prints the result of the evaluation  and  then  returns  to  the
X      initial prompt waiting for another expression to be typed.
X
X      Input can be aborted at any time by typing the CONTROL-G key  (it  may
X      be necessary to follow CONTROL-G by RETURN).
X
X
X      XLISP: An Experimental Object Oriented Language                 Page 6
X      BREAK COMMAND LOOP
X
X
X      4  BREAK COMMAND LOOP
X
X      When XLISP encounters an error  while  evaluating  an  expression,  it
X      attempts to handle the error in the following way:
X
X      If the symbol '*breakenable*' is true, the  message  corresponding  to
X      the  error  is  printed.   If the error is correctable, the correction
X      message is printed.  If the symbol '*tracenable*'  is  true,  a  trace
X      back  is  printed.  The number of entries printed depends on the value
X      of the symbol '*tracelimit*'.  If this  symbol  is  set  to  something
X      other  than  a  number, the entire trace back stack is printed.  XLISP
X      then enters a read/eval/print loop to allow the user  to  examine  the
X      state  of  the  interpreter  in  the  context of the error.  This loop
X      differs from the normal top-leval read/eval/print loop in that if  the
X      user   invokes the function 'continue'  XLISP  will  continue  from  a
X      correctable error.  If the user invokes the function 'quit' XLISP will
X      abort  the  break  loop  and return to the top level or the next lower
X      numbered break loop.  When in a break loop, XLISP prefixes  the  break
X      level to the normal prompt.
X
X      If the symbol '*breakenable*' is nil, XLISP looks  for  a  surrounding
X      errset  function.   If  one  is found, XLISP examines the value of the
X      print flag.  If this flag is true, the error message is  printed.   In
X      any case, XLISP causes the errset function call to return nil.
X
X      If there is no surrounding errset function,  XLISP  prints  the  error
X      message and returns to the top level.
X
X
X      XLISP: An Experimental Object Oriented Language                 Page 7
X      DATA TYPES
X
X
X      5  DATA TYPES
X
X      There are several different data types available to XLISP programmers.
X
X
X            o  lists
X
X            o  symbols
X
X            o  strings
X
X            o  integers
X
X            o  floats
X
X            o  objects
X
X            o  file pointers
X
X            o  subrs (built-in functions)
X
X            o  fsubrs (special forms)
X
X      Another data type is the stream.  A stream is a list  node  whose  car
X      points  to  the head of a list of integers and whose cdr points to the
X      last list node of the list.  An empty stream is a list node whose  car
X      and  cdr  are  nil.   Each  of  the  integers in the list represents a
X      character in the stream.  When a character is read from a stream,  the
X      first integer from the head of the list is removed and returned.  When
X      a character is written to  a  stream,  the  integer  representing  the
X      character  code  of  the character is appended to the end of the list.
X      When a  function  indicates  that  it  takes  an  input  source  as  a
X      parameter,  this  parameter  can  either be an input file pointer or a
X      stream.  Similarly, when a function indicates that it takes an  output
X      sink  as  a  parameter,  this  parameter  can either be an output file
X      pointer or a stream.
X
X
X      XLISP: An Experimental Object Oriented Language                 Page 8
X      THE EVALUATOR
X
X
X      6  THE EVALUATOR
X
X      The process of evaluation in XLISP:
X
X            o  Integers, floats, strings, file pointers, subrs,  fsubrs  and
X               objects evaluate to themselves
X
X            o  Symbols evaluate to the value associated with  their  current
X               binding
X
X            o  Lists are evaluated by evaluating the first  element  of  the
X               list and then taking one of the following actions:
X
X                o  If  it  is  a  subr,  the  remaining  list  elements  are
X                   evaluated  and  the  subr  is called with these evaluated
X                   expressions as arguments.
X
X                o  If it  is  an  fsubr,  the  fsubr  is  called  using  the
X                   remaining list elements as arguments (unevaluated)
X
X                o  If it is a list:
X
X                   1.  If the list is a function closure (a list  whose  car
X                       is   a   lambda   expression  and  whose  cdr  is  an
X                       environment list), the car of the list is used as the
X                       function  to  be  applied  and the cdr is used as the
X                       environment  to  be  extended  with   the   parameter
X                       bindings.
X
X                   2.  If the list  is  a  lambda  expression,  the  current
X                       environment is used for the function application.
X
X                   3.  In either of the above two cases, the remaining  list
X                       elements  are evaluated and the resulting expressions
X                       are bound to  the  formal  arguments  of  the  lambda
X                       expression.   The  body  of  the function is executed
X                       within this new binding environment.
X
X
X                o  If it is a list and the car of the list is  'macro',  the
X                   remaining list elements are bound to the formal arguments
X                   of the macro expression.  The body  of  the  function  is
X                   executed within this new binding environment.  The result
X                   of this evaluation is  considered  the  macro  expansion.
X                   This  result  is  then evaluated in place of the original
X                   expression.
X
X                o  If it is an object, the second list element is  evaluated
X                   and  used  as  a message selector.  The message formed by
X                   combining the selector with the values of  the  remaining
X                   list elements is sent to the object.
X
X
X
X
X      XLISP: An Experimental Object Oriented Language                 Page 9
X      LEXICAL CONVENTIONS
X
X
X      7  LEXICAL CONVENTIONS
X
X      The following conventions are followed when entering XLISP programs:
X
X      Comments in XLISP code begin with a semi-colon character and  continue
X      to the end of the line.
X
X      Symbol names in  XLISP  can  consist  of  any  sequence  of  non-blank
X      printable characters except the following:
X
X              ( ) ' ` , " ;
X
X      Uppercase and lowercase characters are not distinguished within symbol
X      names.  All lowercase characters are mapped to uppercase on input.
X
X      Integer literals consist of a sequence of digits optionally  beginning
X      with  a  '+'  or '-'.  The range of values an integer can represent is
X      limited by the size of a C 'long' on the machine  on  which  XLISP  is
X      running.
X
X      Floating  point  literals  consist  of a sequence of digits optionally
X      beginning with a '+' or '-' and including an embedded  decimal  point.
X      The  range  of values a floating point number can represent is limited
X      by the size  of  a  C  'float'  ('double'  on  machines  with  32  bit
X      addresses) on the machine on which XLISP is running.
X
X      Literal strings are  sequences  of  characters  surrounded  by  double
X      quotes.   Within  quoted  strings  the  '\' character is used to allow
X      non-printable characters to be included.  The codes recognized are:
X
X              \\      means the character '\'
X              \n      means newline
X              \t      means tab
X              \r      means return
X              \e      means escape
X              \nnn    means the character whose octal code is nnn
X
X      XLISP defines several useful read macros:
X
X              '  == (quote )
X              #' == (function )
X              `  == (backquote )
X              ,  == (comma )
X              ,@ == (comma-at )
X
X
X      XLISP: An Experimental Object Oriented Language                Page 10
X      OBJECTS
X
X
X      8  OBJECTS
X
X      Definitions:
X
X            o  selector - a symbol used to select an appropriate method
X
X            o  message - a selector and a list of actual arguments
X
X            o  method - the code that implements a message
X
X      Since XLISP was created to provide a simple  basis  for  experimenting
X      with  object  oriented  programming,  one  of the primitive data types
X      included is  'object'.   In  XLISP,  an  object  consists  of  a  data
X      structure containing a pointer to the object's class as well as a list
X      containing the values of the object's instance variables.
X
X      Officially, there is no way to see  inside  an  object  (look  at  the
X      values  of  its instance variables).  The only way to communicate with
X      an object is by sending  it  a  message.   When  the  XLISP  evaluator
X      evaluates  a  list  the  value of whose first element is an object, it
X      interprets the value of the second element of the list (which must  be
X      a symbol) as the message selector.  The evaluator determines the class
X      of the receiving object and attempts to find a method corresponding to
X      the  message  selector  in the set of messages defined for that class.
X      If the message is not found in the object's class and the class has  a
X      super-class,  the  search continues by looking at the messages defined
X      for the super-class.  This process continues from one  super-class  to
X      the  next  until  a  method for the message is found.  If no method is
X      found, an error occurs.
X
X      When a method is found, the evaluator binds the  receiving  object  to
X      the  symbol  'self',  binds the class in which the method was found to
X      the symbol 'msgclass', and evaluates the method  using  the  remaining
X      elements  of  the  original  list  as  arguments to the method.  These
X      arguments  are  always  evaluated  prior  to  being  bound  to   their
X      corresponding  formal  arguments.  The result of evaluating the method
X      becomes the result of the expression.
X
X
X      XLISP: An Experimental Object Oriented Language                Page 11
X      OBJECTS
X
X
X      8.1  THE 'Object' CLASS
X
X      Classes:
X
X      Object  THE TOP OF THE CLASS HEIRARCHY
X
X          Messages:
X
X              :show  SHOW AN OBJECT'S INSTANCE VARIABLES
X                  returns     the object
X
X              :class  RETURN THE CLASS OF AN OBJECT
X                  returns     the class of the object
X
X              :isnew  THE DEFAULT OBJECT INITIALIZATION ROUTINE
X                  returns     the object
X
X              :sendsuper  []...  SEND SUPERCLASS A MESSAGE
X                         the message selector
X                        the message arguments
X                  returns     the result of sending the message
X
X
X      XLISP: An Experimental Object Oriented Language                Page 12
X      OBJECTS
X
X
X      8.2  THE 'Class' CLASS
X
X      Class   THE CLASS OF ALL OBJECT CLASSES (including itself)
X
X          Messages:
X
X              :new  CREATE A NEW INSTANCE OF A CLASS
X                  returns     the new class object
X
X              :isnew  [[]]  INITIALIZE A NEW CLASS
X                       the list of instance variables
X                       the list of class variables (default is nil)
X                       the superclass (default is Object)
X                  returns     the new class object
X
X              :answer     ADD A MESSAGE TO A CLASS
X                         the message symbol
X                       the formal argument list
X                                this list is of the form:
X                                  ([]...
X                                   [&optional []...]
X                                   [&rest ]
X                                   [&aux []...])
X                                where
X                                     a formal argument
X                                     an optional argument (default is nil)
X                                     bound to the rest of the arguments
X                                      a auxiliary variable (set to nil)
X                        a list of executable expressions
X                  returns     the object
X
X
X      When  a  new  instance  of  a  class is created by sending the message
X      ':new' to an existing class, the message ':isnew' followed by whatever
X      parameters were passed to the ':new' message  is  sent  to  the  newly
X      created object.
X
X      When  a  new  class  is  created  by sending the ':new' message to the
X      object 'Class', an optional parameter may be specified indicating  the
X      superclass of the new class.  If this parameter is  omitted,  the  new
X      class  will  be a subclass of 'Object'.  A class inherits all instance
X      variables, class variables, and methods from its super-class.
X
X
X      XLISP: An Experimental Object Oriented Language                Page 13
X      SYMBOLS
X
X
X      9  SYMBOLS
X
X
X            o  self - the current object (within a message context)
X
X            o  msgclass - the class in which the current method was found
X
X            o  *oblist* - the object list
X
X            o  *keylist* - the keyword list
X
X            o  *standard-input* - the standard input file
X
X            o  *standard-output* - the standard output file
X
X            o  *breakenable* - flag controlling entering the break  loop  on
X               errors
X
X            o  *tracenable* - flag controlling trace back printout on errors
X               and breaks
X
X            o  *tracelimit*  -  maximum  number  of  levels  of  trace  back
X               information printed on errors and breaks
X
X            o  *evalhook* - user substitute for the evaluator function
X
X            o  *applyhook* - (not yet implemented)
X
X            o  *unbound* - indicator for unbound symbols
X
X
X
X      XLISP: An Experimental Object Oriented Language                Page 14
X      FUNCTION DEFINITIONS
X
X
X      10  FUNCTION DEFINITIONS
X
X      10.1  EVALUATION FUNCTIONS
X
X      (eval )  EVALUATE AN XLISP EXPRESSION
X                the expression to be evaluated
X          returns     the result of evaluating the expression
X
X      (apply  )  APPLY A FUNCTION TO A LIST OF ARGUMENTS
X                 the function to apply (or function symbol)
X                the argument list
X          returns     the result of applying the function to the argument list
X
X      (funcall  []...)  CALL A FUNCTION WITH ARGUMENTS
X                 the function to call (or function symbol)
X                 arguments to pass to the function
X          returns     the result of calling the function with the arguments
X
X      (quote )  RETURN AN EXPRESSION UNEVALUATED
X                the expression to be quoted (quoted)
X          returns      unevaluated
X
X      (function )  QUOTE A FUNCTION
X                the function to be quoted (quoted)
X          returns     a function closure
X
X      (backquote )  FILL IN A TEMPLATE
X                the template
X          returns     a copy of the template with comma and comma-at expressions
X                      expanded (see the Common Lisp reference manual)
X
X
X      XLISP: An Experimental Object Oriented Language                Page 15
X      SYMBOL FUNCTIONS
X
X
X      10.2  SYMBOL FUNCTIONS
X
X      (set  )  SET THE VALUE OF A SYMBOL
X                 the symbol being set
X                the new value
X          returns     the new value
X
X      (setq [ ]...)  SET THE VALUE OF A SYMBOL
X                 the symbol being set (quoted)
X                the new value
X          returns     the new value
X
X      (setf [ ]...)  SET THE VALUE OF A FIELD
X               the field specifier (quoted):
X                                          set the value of a symbol
X                          (car )         set the car of a list node
X                          (cdr )         set the cdr of a list node
X                          (get  )   set the value of a property
X                          (symbol-value ) set the value of a symbol
X                          (symbol-plist ) set the property list of a symbol
X               the new value
X          returns     the new value
X
X      (defun   []...)  DEFINE A FUNCTION
X      (defmacro   []...)  DEFINE A MACRO
X                 symbol being defined (quoted)
X               list of formal arguments (quoted)
X                        this list is of the form:
X                          ([]...
X                           [&optional []...]
X                           [&rest ]
X                           [&aux []...])
X                        where
X                                is a formal argument
X                                is an optional argument (default is nil)
X                                bound to the rest of the arguments
X                                 is an auxiliary variable (set to nil)
X                expressions constituting the body of the
X                      function (quoted)
X          returns     the function symbol
X
X      (gensym [])  GENERATE A SYMBOL
X                 string or number
X          returns     the new symbol
X
X      (intern )  MAKE AN INTERNED SYMBOL
X               the symbol's print name string
X          returns     the new symbol
X
X      (make-symbol )  MAKE AN UNINTERNED SYMBOL
X               the symbol's print name string
X          returns     the new symbol
X
X
X      XLISP: An Experimental Object Oriented Language                Page 16
X      SYMBOL FUNCTIONS
X
X
X      (symbol-name )  GET THE PRINT NAME OF A SYMBOL
X                 the symbol
X          returns     the symbol's print name
X
X      (symbol-value )  GET THE VALUE OF A SYMBOL
X                 the symbol
X          returns     the symbol's value
X
X      (symbol-plist )  GET THE PROPERTY LIST OF A SYMBOL
X                 the symbol
X          returns     the symbol's property list
X
X
X      XLISP: An Experimental Object Oriented Language                Page 17
X      PROPERTY LIST FUNCTIONS
X
X
X      10.3  PROPERTY LIST FUNCTIONS
X
X      (get  )  GET THE VALUE OF A PROPERTY
X                 the symbol
X                the property symbol
X          returns     the property value or nil
X
X      (putprop   )  PUT A PROPERTY ONTO THE PROPERTY LIST
X                 the symbol
X                 the property value
X                the property symbol
X          returns     nil
X
X      (remprop  )  REMOVE A PROPERTY
X                 the symbol
X                the property symbol
X
X
X      XLISP: An Experimental Object Oriented Language                Page 18
X      LIST FUNCTIONS
X
X
X      10.4  LIST FUNCTIONS
X
X      (car )  RETURN THE CAR OF A LIST NODE
X                the list node
X          returns     the car of the list node
X
X      (cdr )  RETURN THE CDR OF A LIST NODE
X                the list node
X          returns     the cdr of the list node
X
X      (caar ) == (car (car ))
X      (cadr ) == (car (cdr ))
X      (cdar ) == (cdr (car ))
X      (cddr ) == (cdr (cdr ))
X
X      (cons  )  CONSTRUCT A NEW LIST NODE
X               the car of the new list node
X               the cdr of the new list node
X          returns     the new list node
X
X      (list []...)  CREATE A LIST OF VALUES
X                expressions to be combined into a list
X          returns     the new list
X
X      (append []...)  APPEND LISTS
X                lists whose elements are to be appended
X          returns     the new list
X
X      (reverse )  REVERSE A LIST
X                the list to reverse
X          returns     a new list in the reverse order
X
X      (last )  RETURN THE LAST LIST NODE OF A LIST
X                the list
X          returns     the last list node in the list
X
X      (member   [ ])  FIND AN EXPRESSION IN A LIST
X                the expression to find
X                the list to search
X                 the keyword :test or :test-not
X                the test function (defaults to eql)
X          returns     the remainder of the list starting with the expression
X
X      (assoc   [ ])  FIND AN EXPRESSION IN AN A-LIST
X                the expression to find
X               the association list
X                 the keyword :test or :test-not
X                the test function (defaults to eql)
X          returns     the alist entry or nil
X
X
X      XLISP: An Experimental Object Oriented Language                Page 19
X      LIST FUNCTIONS
X
X
X      (remove   [ ])  REMOVE AN EXPRESSION FROM A LIST
X                the expression to delete
X                the list
X                 the keyword :test or :test-not
X                the test function (defaults to eql)
X          returns     the list with the matching expressions deleted
X
X      (length )  FIND THE LENGTH OF A LIST OR STRING
X                the list or string
X          returns     the length of the list or string
X
X      (nth  )  RETURN THE NTH ELEMENT OF A LIST
X                   the number of the element to return (zero origin)
X                the list
X          returns     the nth element or nil if the list isn't that long
X
X      (nthcdr  )  RETURN THE NTH CDR OF A LIST
X                   the number of the element to return (zero origin)
X                the list
X          returns     the nth cdr or nil if the list isn't that long
X
X      (mapc   []...)  APPLY FUNCTION TO SUCCESSIVE CARS
X                 the function or function name
X               a list for each argument of the function
X          returns     the first list of arguments
X
X      (mapcar   []...)  APPLY FUNCTION TO SUCCESSIVE CARS
X                 the function or function name
X               a list for each argument of the function
X          returns     the list of values returned by each function invocation
X
X      (mapl   []...)  APPLY FUNCTION TO SUCCESSIVE CDRS
X                 the function or function name
X               a list for each argument of the function
X          returns     the first list of arguments
X
X      (maplist   []...)  APPLY FUNCTION TO SUCCESSIVE CDRS
X                 the function or function name
X               a list for each argument of the function
X          returns     the list of values returned by each function invocation
X
X
X      XLISP: An Experimental Object Oriented Language                Page 20
X      LIST FUNCTIONS
X
X
X      (subst    [ ])  SUBSTITUTE EXPRESSIONS
X                  the new expression
X                the old expression
X                the expression in which to do the substitutions
X                 the keyword :test or :test-not
X                the test function (defaults to eql)
X          returns     the expression with substitutions
X
X      (sublis   [ ])  SUBSTITUTE USING AN A-LIST
X               the association list
X                the expression in which to do the substitutions
X                 the keyword :test or :test-not
X                the test function (defaults to eql)
X          returns     the expression with substitutions
X
X
X      XLISP: An Experimental Object Oriented Language                Page 21
X      DESTRUCTIVE LIST FUNCTIONS
X
X
X      10.5  DESTRUCTIVE LIST FUNCTIONS
X
X      (rplaca  )  REPLACE THE CAR OF A LIST NODE
X                the list node
X                the new value for the car of the list node
X          returns     the list node after updating the car
X
X      (rplacd  )  REPLACE THE CDR OF A LIST NODE
X                the list node
X                the new value for the cdr of the list node
X          returns     the list node after updating the cdr
X
X      (nconc []...)  DESTRUCTIVELY CONCATENATE LISTS
X                lists to concatenate
X          returns     the result of concatenating the lists
X
X      (delete   [ ])  DELETE AN EXPRESSION FROM A LIST
X                the expression to delete
X                the list
X                 the keyword :test or :test-not
X                the test function (defaults to eql)
X          returns     the list with the matching expressions deleted
X
X
X      XLISP: An Experimental Object Oriented Language                Page 22
X      PREDICATE FUNCTIONS
X
X
X      10.6  PREDICATE FUNCTIONS
X
X      (atom )  IS THIS AN ATOM?
X                the expression to check
X          returns     t if the value is an atom, nil otherwise
X
X      (symbolp )  IS THIS A SYMBOL?
X                the expression to check
X          returns     t if the expression is a symbol, nil otherwise
X
X      (numberp )  IS THIS A NUMBER?
X                the expression to check
X          returns     t if the expression is a number, nil otherwise
X
X      (null )  IS THIS AN EMPTY LIST?
X                the list to check
X          returns     t if the list is empty, nil otherwise
X
X      (not )  IS THIS FALSE?
X                the expression to check
X          return      t if the expression is nil, nil otherwise
X
X      (listp )  IS THIS A LIST?
X                the expression to check
X          returns     t if the value is a list node or nil, nil otherwise
X
X      (consp )  IS THIS A NON-EMPTY LIST?
X                the expression to check
X          returns     t if the value is a list node, nil otherwise
X
X      (boundp )  IS THIS A BOUND SYMBOL?
X                 the symbol
X          returns     t if a value is bound to the symbol, nil otherwise
X
X
X      XLISP: An Experimental Object Oriented Language                Page 23
X      PREDICATE FUNCTIONS
X
X
X      (minusp )  IS THIS NUMBER NEGATIVE?
X                the number to test
X          returns     t if the number is negative, nil otherwise
X
X      (zerop )  IS THIS NUMBER ZERO?
X                the number to test
X          returns     t if the number is zero, nil otherwise
X
X      (plusp )  IS THIS NUMBER POSITIVE?
X                the number to test
X          returns     t if the number is positive, nil otherwise
X
X      (evenp )  IS THIS NUMBER EVEN?
X                the number to test
X          returns     t if the number is even, nil otherwise
X
X      (oddp )  IS THIS NUMBER ODD?
X                the number to test
X          returns     t if the number is odd, nil otherwise
X
X      (eq  )  ARE THE EXPRESSIONS IDENTICAL?
X               the first expression
X               the second expression
X          returns     t if they are equal, nil otherwise
X
X      (eql  )  ARE THE EXPRESSIONS IDENTICAL?
X                              (WORKS WITH NUMBERS AND STRINGS)
X               the first expression
X               the second expression
X          returns     t if they are equal, nil otherwise
X
X      (equal  )  ARE THE EXPRESSIONS EQUAL?
X               the first expression
X               the second expression
X          returns     t if they are equal, nil otherwise
X
X
X      XLISP: An Experimental Object Oriented Language                Page 24
X      CONTROL FUNCTIONS
X
X
X      10.7  CONTROL FUNCTIONS
X
X      (cond []...)  EVALUATE CONDITIONALLY
X                pair consisting of:
X                          ( []...)
X                        where
X                                is a predicate expression
X                                evaluated if the predicate
X                                      is not nil
X          returns     the value of the first expression whose predicate
X                      is not nil
X
X      (and []...)  THE LOGICAL AND OF A LIST OF EXPRESSIONS
X                the expressions to be ANDed
X          returns     nil if any expression evaluates to nil,
X                      otherwise the value of the last expression
X                      (evaluation of expressions stops after the first
X                       expression that evaluates to nil)
X
X      (or []...)  THE LOGICAL OR OF A LIST OF EXPRESSIONS
X                the expressions to be ORed
X          returns     nil if all expressions evaluate to nil,
X                      otherwise the value of the first non-nil expression
X                      (evaluation of expressions stops after the first
X                       expression that does not evaluate to nil)
X
X      (if   [])  EXECUTE EXPRESSIONS CONDITIONALLY
X               the test expression
X               the expression to be evaluated if texpr is non-nil
X               the expression to be evaluated if texpr is nil
X          returns     the value of the selected expression
X
X      (let ([]...) []...)  BIND SYMBOLS AND EVALUATE EXPRESSIONS
X      (let* ([]...) []...)  LET WITH SEQUENTIAL BINDING
X             the variable bindings each of which is either:
X                      1)  a symbol (which is initialized to nil)
X                      2)  a list whose car is a symbol and whose cadr
X                              is an initialization expression
X                the expressions to be evaluated
X          returns     the value of the last expression
X
X      (catch  []...)  EVALUATE EXPRESSIONS AND CATCH THROWS
X                 the catch tag
X                expressions to evaluate
X          returns     the value of the last expression the throw expression
X
X      (throw  [])  THROW TO A CATCH
X                 the catch tag
X                the value for the catch to return (defaults to nil)
X          returns     never returns
X
X
X      XLISP: An Experimental Object Oriented Language                Page 25
X      LOOPING FUNCTIONS
X
X
X      10.8  LOOPING FUNCTIONS
X
X      (do ([]...) ( []...) []...)
X      (do* ([]...) ( []...) []...)
X             the variable bindings each of which is either:
X                      1)  a symbol (which is initialized to nil)
X                      2)  a list of the form: (  [])
X                          where:
X                                is the symbol to bind
X                               is the initial value of the symbol
X                               is a step expression
X               the termination test expression
X               result expressions (the default is nil)
X                the body of the loop (treated like an implicit prog)
X          returns     the value of the last result expression
X
X      (dolist (  []) []...)  LOOP THROUGH A LIST
X                 the symbol to bind to each list element
X                the list expression
X               the result expression (the default is nil)
X                the body of the loop (treated like an implicit prog)
X
X      (dotimes (  []) []...)  LOOP FROM ZERO TO N-1
X                 the symbol to bind to each value from 0 to n-1
X                the number of times to loop
X               the result expression (the default is nil)
X                the body of the loop (treated like an implicit prog)
X
X
X      XLISP: An Experimental Object Oriented Language                Page 26
X      THE PROGRAM FEATURE
X
X
X      10.9  THE PROGRAM FEATURE
X
X      (prog ([]...) []...)  THE PROGRAM FEATURE
X      (prog* ([]...) []...)  PROG WITH SEQUENTIAL BINDING
X             the variable bindings each of which is either:
X                      1)  a symbol (which is initialized to nil)
X                      2)  a list whose car is a symbol and whose cadr
X                              is an initialization expression
X                expressions to evaluate or tags (symbols)
X          returns     nil or the argument passed to the return function
X
X      (go )  GO TO A TAG WITHIN A PROG CONSTRUCT
X                 the tag (quoted)
X          returns     never returns
X
X      (return [])  CAUSE A PROG CONSTRUCT TO RETURN A VALUE
X                the value (defaults to nil)
X          returns     never returns
X
X      (prog1  []...)  EXECUTE EXPRESSIONS SEQUENTIALLY
X               the first expression to evaluate
X                the remaining expressions to evaluate
X          returns     the value of the first expression
X
X      (prog2   []...)  EXECUTE EXPRESSIONS SEQUENTIALLY
X               the first expression to evaluate
X               the second expression to evaluate
X                the remaining expressions to evaluate
X          returns     the value of the second expression
X
X      (progn []...)  EXECUTE EXPRESSIONS SEQUENTIALLY
X                the expressions to evaluate
X          returns     the value of the last expression (or nil)
X
X
X      XLISP: An Experimental Object Oriented Language                Page 27
X      DEBUGGING AND ERROR HANDLING
X
X
X      10.10  DEBUGGING AND ERROR HANDLING
X
X      (error  [])  SIGNAL A NON-CORRECTABLE ERROR
X                the error message string
X                 the argument expression (printed after the message)
X          returns     never returns
X
X      (cerror   [])  SIGNAL A CORRECTABLE ERROR
X                the continue message string
X                the error message string
X                 the argument expression (printed after the message)
X          returns     nil when continued from the break loop
X
X      (break [ []])  ENTER A BREAK LOOP
X                the break message string (defaults to "**BREAK**")
X                 the argument expression (printed after the message)
X          returns     nil when continued from the break loop
X
X      (clean-up)  CLEAN-UP AFTER AN ERROR
X          returns     never returns
X
X      (continue)  CONTINUE FROM A CORRECTABLE ERROR
X          returns     never returns
X
X      (errset  [])  TRAP ERRORS
X                the expression to execute
X               flag to control printing of the error message
X          returns     the value of the last expression consed with nil
X                      or nil on error
X
X      (baktrace [])  PRINT N LEVELS OF TRACE BACK INFORMATION
X                   the number of levels (defaults to all levels)
X          returns     nil
X
X      (evalhook   )  EVALUATE AN EXPRESSION WITH HOOKS
X                the expression to evaluate
X               the value for *evalhook*
X               the value for *applyhook*
X          returns     the result of evaluating the expression
X
X
X      XLISP: An Experimental Object Oriented Language                Page 28
X      ARITHMETIC FUNCTIONS
X
X
X      10.11  ARITHMETIC FUNCTIONS
X
X      (truncate )  TRUNCATES A FLOATING POINT NUMBER TO AN INTEGER
X                the number
X          returns     the result of truncating the number
X
X      (float )  CONVERTS AN INTEGER TO A FLOATING POINT NUMBER
X                the number
X          returns     the result of floating the integer
X
X      (+ ...)  ADD A LIST OF NUMBERS
X                the numbers
X          returns     the result of the addition
X
X      (- ...)  SUBTRACT A LIST OF NUMBERS OR NEGATE A SINGLE NUMBER
X                the numbers
X          returns     the result of the subtraction
X
X      (* ...)  MULTIPLY A LIST OF NUMBERS
X                the numbers
X          returns     the result of the multiplication
X
X      (/ ...)  DIVIDE A LIST OF NUMBERS
X                the numbers
X          returns     the result of the division
X
X      (1+ )  ADD ONE TO A NUMBER
X                the number
X          returns     the number plus one
X
X      (1- )  SUBTRACT ONE FROM A NUMBER
X                the number
X          returns     the number minus one
X
X      (rem ...)  REMAINDER OF A LIST OF NUMBERS
X                the numbers
X          returns     the result of the remainder operation
X
X      (min ...)  THE SMALLEST OF A LIST OF NUMBERS
X                the expressions to be checked
X          returns     the smallest number in the list
X
X      (max ...)  THE LARGEST OF A LIST OF NUMBERS
X                the expressions to be checked
X          returns     the largest number in the list
X
X      (abs )  THE ABSOLUTE VALUE OF A NUMBER
X                the number
X          returns     the absolute value of the number
X
X
X      XLISP: An Experimental Object Oriented Language                Page 29
X      ARITHMETIC FUNCTIONS
X
X
X      (sin )  COMPUTE THE SINE OF A NUMBER
X                the floating point number
X          returns     the sine of the number
X
X      (cos )  COMPUTE THE COSINE OF A NUMBER
X                the floating point number
X          returns     the cosine of the number
X
X      (tan )  COMPUTE THE TANGENT OF A NUMBER
X                the floating point number
X          returns     the tangent of the number
X
X      (expt  )  COMPUTE X TO THE Y POWER
X              the floating point number
X              the floating point exponent
X          returns     x to the y power
X
X      (exp )  COMPUTE E TO THE X POWER
X              the floating point number
X          returns     e to the x power
X
X      (sqrt )  COMPUTE THE SQUARE ROOT OF A NUMBER
X                the floating point number
X          returns     the square root of the number
X
X
X      XLISP: An Experimental Object Oriented Language                Page 30
X      BITWISE LOGICAL FUNCTIONS
X
X
X      10.12  BITWISE LOGICAL FUNCTIONS
X
X      (bit-and ...)  THE BITWISE AND OF A LIST OF NUMBERS
X                the numbers
X          returns     the result of the and operation
X
X      (bit-ior ...)  THE BITWISE INCLUSIVE OR OF A LIST OF NUMBERS
X                the numbers
X          returns     the result of the inclusive or operation
X
X      (bit-xor ...)  THE BITWISE EXCLUSIVE OR OF A LIST OF NUMBERS
X                the numbers
X          returns     the result of the exclusive or operation
X
X      (bit-not )  THE BITWISE NOT OF A NUMBER
X                the number
X          returns     the bitwise inversion of number
X
X
X      XLISP: An Experimental Object Oriented Language                Page 31
X      RELATIONAL FUNCTIONS
X
X
X      10.13  RELATIONAL FUNCTIONS
X
X      The relational functions can be used  to  compare  integers,  floating
X      point numbers or strings.
X
X      (<  )  TEST FOR LESS THAN
X                  the left operand of the comparison
X                  the right operand of the comparison
X          returns     the result of comparing  with 
X
X      (<=  )  TEST FOR LESS THAN OR EQUAL TO
X                  the left operand of the comparison
X                  the right operand of the comparison
X          returns     the result of comparing  with 
X
X      (=  )  TEST FOR EQUAL TO
X                  the left operand of the comparison
X                  the right operand of the comparison
X          returns     the result of comparing  with 
X
X      (/=  )  TEST FOR NOT EQUAL TO
X                  the left operand of the comparison
X                  the right operand of the comparison
X          returns     the result of comparing  with 
X
X      (>=  )  TEST FOR GREATER THAN OR EQUAL TO
X                  the left operand of the comparison
X                  the right operand of the comparison
X          returns     the result of comparing  with 
X
X      (>  )  TEST FOR GREATER THAN
X                  the left operand of the comparison
X                  the right operand of the comparison
X          returns     the result of comparing  with 
X
X
X      XLISP: An Experimental Object Oriented Language                Page 32
X      STRING FUNCTIONS
X
X
X      10.14  STRING FUNCTIONS
X
X      (char  )  EXTRACT A CHARACTER FROM A STRING
X              the string
X               the string index (zero relative)
X          returns     the ascii code of the first character
X
X      (string )  MAKE A STRING FROM AN INTEGER ASCII VALUE
X                the numeric expression
X          returns     a one character string whose first character is 
X
X      (strcat []...)  CONCATENATE STRINGS
X                the strings to concatenate
X          returns     the result of concatenating the strings
X
X      (substr   []) EXTRACT A SUBSTRING
X                the string
X               the starting position
X               the length (default is rest of string)
X          returns     substring starting at  for 
X
X
X      XLISP: An Experimental Object Oriented Language                Page 33
X      INPUT/OUTPUT FUNCTIONS
X
X
X      10.15  INPUT/OUTPUT FUNCTIONS
X
X      (read [ []])  READ AN XLISP EXPRESSION
X              the input source (default is standard input)
X                 the value to return on end of file (default is nil)
X          returns     the expression read
X
X      (print  [])  PRINT A LIST OF VALUES ON A NEW LINE
X                the expressions to be printed
X                the output sink (default is standard output)
X          returns     the expression
X
X      (prin1  [])  PRINT A LIST OF VALUES
X                the expressions to be printed
X                the output sink (default is standard output)
X          returns     the expression
X
X      (princ  [])  PRINT A LIST OF VALUES WITHOUT QUOTING
X                the expressions to be printed
X                the output sink (default is standard output)
X          returns     the expression
X
X      (terpri [])  TERMINATE THE CURRENT PRINT LINE
X                the output sink (default is standard output)
X          returns     nil
X
X      (flatsize )  LENGTH OF PRINTED REPRESENTATION USING PRIN1
X                the expression
X          returns     the length
X
X      (flatc )  LENGTH OF PRINTED REPRESENTATION USING PRINC
X                the expression
X          returns     the length
X
X
X
X      XLISP: An Experimental Object Oriented Language                Page 34
X      FILE I/O FUNCTIONS
X
X
X      10.16  FILE I/O FUNCTIONS
X
X      (openi )  OPEN AN INPUT FILE
X               the file name string
X          returns     a file pointer
X
X      (openo )  OPEN AN OUTPUT FILE
X               the file name string
X          returns     a file pointer
X
X      (close )  CLOSE A FILE
X                  the file pointer
X          returns     nil
X
X      (read-char [])  READ A CHARACTER FROM A FILE OR STREAM
X              the input source (default is standard input)
X          returns     the character (integer)
X
X      (peek-char [ []])  PEEK AT THE NEXT CHARACTER
X                flag for skipping white space (default is nil)
X              the input source (default is standard input)
X          returns     the character (integer)
X
X      (write-char  [])  WRITE A CHARACTER TO A FILE OR STREAM
X                  the character to put (integer)
X                the output sink (default is standard output)
X          returns     the character (integer)
X
X      (read-line [])  READ A LINE FROM A FILE OR STREAM
X              the input source (default is standard input)
X          returns     the input string
X
X
X      XLISP: An Experimental Object Oriented Language                Page 35
X      SYSTEM FUNCTIONS
X
X
X      10.17  SYSTEM FUNCTIONS
X
X      (load  [ []])  LOAD AN XLISP SOURCE FILE
X               the filename string (in double quotes)
X               the verbose flag (default is t)
X               the print flag (default is nil)
X          returns     the filename
X
X      (gc)  FORCE GARBAGE COLLECTION
X          returns     nil
X
X      (expand )  EXPAND MEMORY BY ADDING SEGMENTS
X                 the number of segments to add
X          returns     the number of segments added
X
X      (alloc )  CHANGE NUMBER OF NODES TO ALLOCATE IN EACH SEGMENT
X                 the number of nodes to allocate
X          returns     the old number of nodes to allocate
X
X      (mem)  SHOW MEMORY ALLOCATION STATISTICS
X          returns     nil
X
X      (type-of )  RETURNS THE TYPE OF THE EXPRESSION
X                the expression to return the type of
X          returns     nil if the value is nil otherwise one of the symbols:
X                          :SYMBOL   for symbols
X                          :OBJECT   for objects
X                          :CONS     for list nodes
X                          :SUBR     for subroutines with evaluated arguments
X                          :FSUBR    for subroutines with unevaluated arguments
X                          :STRING   for string nodes
X                          :FIXNUM   for integer nodes
X                          :FLONUM   for floating point nodes
X                          :FILE     for file pointer nodes
X
X      (exit)  EXIT XLISP
X          returns     never returns
SHAR_EOF
if test 53933 -ne "`wc -c 'xlisp.doc'`"
then
	echo shar: error transmitting "'xlisp.doc'" '(should have been 53933 characters)'
fi
echo shar: extracting "'read.me'" '(2236 characters)'
if test -f 'read.me'
then
	echo shar: over-writing existing file "'read.me'"
fi
sed 's/^X//' << \SHAR_EOF > 'read.me'
XThis distribution of xlisp contains the following files:
X
Xread.me		This file
Xxlisp.doc	The documentation
X
Xinit.lsp	Required initialization file. Automatically loaded by
X		xlisp on startup. Must be in the same folder
X		(directory) as xlisp.ttp, unless INITPATH is defined
X		in xlisp.h. (INITPATH if the filename for init.lsp
X		not the directory name ie. "mypath\\init.lsp" and NOT
X		just "mypath\\".
X
X		Sample xlisp programs:
Xart.lsp example.lsp fact.lsp fib.lsp hanoi.lsp hdwr.lsp ifthen.lsp
Xprolog.lsp queens.lsp queens2.lsp
X
Xmakefile	To make xlisp on the Vax (unix) (also see xlisp.h)
X
Xctype.h math.h setjmp.h:
X		These .h files are for the St only. When making xlisp
X		on the Vax (unix) hide these files by moving them to
X		another directory.
X
X
Xxlisp.h		Edit first line in the file for system type (ST or Unix)
X
X	Source
Xststuff.c xlbfun.c xlcont.c xldbug.c xldmem.c xleval.c xlfio.c xlftab1.c
Xxlftab2.c xlglob.c xlinit.c xlio.c xlisp.c xljump.c xllist.c xlmath.c
Xxlobj.c xlprin.c xlread.c xlstr.c xlsubr.c xlsym.c xlsys.c
X		The file ststuff.c is St specific and is not used
X		by the Vax (unix) version.
X
X
Xxlisp.bat xlisp.inp:
X	Batch file to link and relmod xlisp on the St
X
XHow to Make xlisp on the ST
X	Compile all the .c files after editing xlisp.h appropriately.
XThen link using xlisp.bat. (You will probably have to edit xlisp.bat
Xto set up the drive designator appropriately for your system). Rename
Xxlisp.prg to xlisp.ttp.
X
XTo invoke xlisp from the desktop on the ST double click xlisp.ttp. In the
Xdialog box enter the name(s) of the file(s) you want loaded (don't enter
Xthe .lsp extention). You may ofcourse choose to supply no filenames in
Xthe dialog box, in which case simply hit . xlisp.ttp will
Xautomatically load init.lsp, and then the file(s).
X
XTo load a file from the interpreter issue:
X(load "filename.lsp")
XNotice the ".lsp" extention is required to be entered here.
X
XHow to Make xlisp on a Vax
X	Edit xlisp.h and makefile appropriately and then issue the
Xcommand:
X	make install
X
XQuestions: Send electronic mail to the address below.
X				
X				enjoy
X
X					Jwahar R. Bammi
X			       Usenet:  .....!decvax!cwruecmp!bammi
X			        CSnet:  bammi@case
X				 Arpa:  bammi%case@csnet-relay
X			   CompuServe:  71515,155
SHAR_EOF
if test 2236 -ne "`wc -c 'read.me'`"
then
	echo shar: error transmitting "'read.me'" '(should have been 2236 characters)'
fi
#	End of shell archive
exit 0
-- 
					Jwahar R. Bammi
			       Usenet:  .....!decvax!cwruecmp!bammi
			        CSnet:  bammi@case
				 Arpa:  bammi%case@csnet-relay
			   CompuServe:  71515,155