home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / EFFO / forum3.lzh / DOC / xlisp.man < prev   
Text File  |  1987-10-23  |  63KB  |  2,968 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                 XLISP: An Experimental Object-oriented Language
  11.  
  12.                                   Version 1.7
  13.  
  14.                                   June 2, 1986
  15.  
  16.  
  17.                                        by
  18.                                David Michael Betz
  19.                                114 Davenport Ave.
  20.                              Manchester, NH  03103
  21.  
  22.                              (603) 625-4691 (home)
  23.  
  24.                    Copyright (c) 1986, by David Michael Betz
  25.                               All Rights Reserved
  26.            Permission is granted for unrestricted non-commercial use
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.         XLISP                  TABLE OF CONTENTS                  Page 2
  77.  
  78.  
  79.                                Table of Contents
  80.  
  81.  
  82.                 TABLE OF CONTENTS                        2
  83.  
  84.                 INTRODUCTION                             4
  85.  
  86.                 A NOTE FROM THE AUTHOR                   5
  87.  
  88.                 XLISP COMMAND LOOP                       6
  89.  
  90.                 BREAK COMMAND LOOP                       7
  91.  
  92.                 DATA TYPES                               8
  93.  
  94.                 THE EVALUATOR                            9
  95.  
  96.                 LEXICAL CONVENTIONS                     10
  97.  
  98.                 READTABLES                              11
  99.  
  100.                 OBJECTS                                 12
  101.  
  102.                 SYMBOLS                                 15
  103.  
  104.                 EVALUATION FUNCTIONS                    16
  105.  
  106.                 SYMBOL FUNCTIONS                        17
  107.  
  108.                 PROPERTY LIST FUNCTIONS                 19
  109.  
  110.                 ARRAY FUNCTIONS                         20
  111.  
  112.                 LIST FUNCTIONS                          21
  113.  
  114.                 DESTRUCTIVE LIST FUNCTIONS              24
  115.  
  116.                 PREDICATE FUNCTIONS                     25
  117.  
  118.                 CONTROL CONSTRUCTS                      27
  119.  
  120.                 LOOPING CONSTRUCTS                      29
  121.  
  122.                 THE PROGRAM FEATURE                     30
  123.  
  124.                 DEBUGGING AND ERROR HANDLING            31
  125.  
  126.                 ARITHMETIC FUNCTIONS                    32
  127.  
  128.                 BITWISE LOGICAL FUNCTIONS               34
  129.  
  130.                 RELATIONAL FUNCTIONS                    35
  131.  
  132.                 STRING FUNCTIONS                        36
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.         XLISP                  TABLE OF CONTENTS                  Page 3
  146.  
  147.  
  148.                 INPUT/OUTPUT FUNCTIONS                  37
  149.  
  150.                 FILE I/O FUNCTIONS                      38
  151.  
  152.                 SYSTEM FUNCTIONS                        39
  153.  
  154.                 EXAMPLES                                41
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.         XLISP                     INTRODUCTION                    Page 4
  215.  
  216.  
  217.         INTRODUCTION
  218.  
  219.         XLISP is an experimental programming language combining some of
  220.         the features of LISP with an object-oriented extension
  221.         capability.  It was implemented to allow experimentation with
  222.         object-oriented programming on small computers.  There are
  223.         currently implementations running on the the VAX under VAX/VMS,
  224.         on the 8088/8086 under MS-DOS, on the 68000 under CP/M-68K, on
  225.         the Macintosh, on the Atari 520ST and on the Amiga.  It is
  226.         completely written in the programming language 'C' and is easily
  227.         extended with user written built-in functions and classes.  It
  228.         is available in source form free of charge to non-commercial
  229.         users.
  230.  
  231.         Many traditional LISP functions are built into XLISP.  In
  232.         addition, XLISP defines the objects 'Object' and 'Class' as
  233.         primitives.  'Object' is the only class that has no superclass
  234.         and hence is the root of the class heirarchy tree.  'Class' is
  235.         the class of which all classes are instances (it is the only
  236.         object that is an instance of itself).
  237.  
  238.         This document is a brief description of XLISP.  It assumes some
  239.         knowledge of LISP and some understanding of the concepts of
  240.         object-oriented programming.
  241.  
  242.         A recommended text for learning LISP programming is the book
  243.         "LISP" by Winston and Horn and published by Addison Wesley.  The
  244.         first edition of this book is based on MacLisp and the second
  245.         edition is based on Common Lisp.  Future versions of XLISP will
  246.         continue to migrate towards compatibility with Common Lisp.
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.         XLISP                A NOTE FROM THE AUTHOR               Page 5
  284.  
  285.  
  286.         A NOTE FROM THE AUTHOR
  287.  
  288.         If you have any problems with XLISP, feel free to contact me for
  289.         help or advice.  Please remember that since XLISP is available
  290.         in source form in a high level language, many users have been
  291.         making versions available on a variety of machines.  If you call
  292.         to report a problem with a specific version, I may not be able
  293.         to help you if that version runs on a machine to which I don't
  294.         have access.  Please have the version number of the version that
  295.         you are running readily accessible before calling me.
  296.  
  297.         If you find a bug in XLISP, first try to fix the bug yourself
  298.         using the source code provided.  If you are successful in fixing
  299.         the bug, send the bug report along with the fix to me.  If you
  300.         don't have access to a C compiler or are unable to fix a bug,
  301.         please send the bug report to me and I'll try to fix it.
  302.  
  303.         Any suggestions for improvements will be welcomed.  Feel free to
  304.         extend the language in whatever way suits your needs.  However,
  305.         PLEASE DO NOT RELEASE ENHANCED VERSIONS WITHOUT CHECKING WITH ME
  306.         FIRST!!  I would like to be the clearing house for new features
  307.         added to XLISP.  If you want to add features for your own
  308.         personal use, go ahead.  But, if you want to distribute your
  309.         enhanced version, contact me first.  Please remember that the
  310.         goal of XLISP is to provide a language to learn and experiment
  311.         with LISP and object-oriented programming on small computers.  I
  312.         don't want it to get so big that it requires megabytes of memory
  313.         to run.
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.         XLISP                 XLISP COMMAND LOOP                  Page 6
  353.  
  354.  
  355.         XLISP COMMAND LOOP
  356.  
  357.         When XLISP is started, it first tries to load "init.lsp" from
  358.         the default directory.  It then loads any files named as
  359.         parameters on the command line (after appending ".lsp" to their
  360.         names).  It then issues the following prompt:
  361.  
  362.         >
  363.  
  364.         This indicates that XLISP is waiting for an expression to be
  365.         typed.  When an incomplete expression has been typed (one where
  366.         the left and right parens don't match) XLISP changes its prompt
  367.         to:
  368.  
  369.         n>
  370.  
  371.         where n is an integer indicating how many levels of left parens
  372.         remain unclosed.
  373.  
  374.         When a complete expression has been entered, XLISP attempts to
  375.         evaluate that expression.  If the expression evaluates
  376.         successfully, XLISP prints the result of the evaluation and then
  377.         returns to the initial prompt waiting for another expression to
  378.         be typed.
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.         XLISP                 BREAK COMMAND LOOP                  Page 7
  422.  
  423.  
  424.         BREAK COMMAND LOOP
  425.  
  426.         When XLISP encounters an error while evaluating an expression,
  427.         it attempts to handle the error in the following way:
  428.  
  429.         If the symbol '*breakenable*' is true, the message corresponding
  430.         to the error is printed.  If the error is correctable, the
  431.         correction message is printed.  If the symbol '*tracenable*' is
  432.         true, a trace back is printed.  The number of entries printed
  433.         depends on the value of the symbol '*tracelimit*'.  If this
  434.         symbol is set to something other than a number, the entire trace
  435.         back stack is printed.  XLISP then enters a read/eval/print loop
  436.         to allow the user to examine the state of the interpreter in the
  437.         context of the error.  This loop differs from the normal top-
  438.         level read/eval/print loop in that if the user invokes the
  439.         function 'continue', XLISP will continue from a correctable
  440.         error.  If the user invokes the function 'clean-up', XLISP will
  441.         abort the break loop and return to the top level or the next
  442.         lower numbered break loop.  When in a break loop, XLISP prefixes
  443.         the break level to the normal prompt.
  444.  
  445.         If the symbol '*breakenable*' is nil, XLISP looks for a
  446.         surrounding errset function.  If one is found, XLISP examines
  447.         the value of the print flag.  If this flag is true, the error
  448.         message is printed.  In any case, XLISP causes the errset
  449.         function call to return nil.
  450.  
  451.         If there is no surrounding errset function, XLISP prints the
  452.         error message and returns to the top level.
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.         XLISP                      DATA TYPES                     Page 8
  491.  
  492.  
  493.         DATA TYPES
  494.  
  495.         There are several different data types available to XLISP
  496.         programmers.
  497.  
  498.             o lists
  499.             o symbols
  500.             o strings
  501.             o integers
  502.             o floats
  503.             o objects
  504.             o arrays
  505.             o file pointers
  506.             o subrs (built-in functions)
  507.             o fsubrs (special forms)
  508.  
  509.         Another data type is the stream.  A stream is a list node whose
  510.         car points to the head of a list of integers and whose cdr
  511.         points to the last list node of the list.  An empty stream is a
  512.         list node whose car and cdr are nil.  Each of the integers in
  513.         the list represents a character in the stream.  When a character
  514.         is read from a stream, the first integer from the head of the
  515.         list is removed and returned.  When a character is written to a
  516.         stream, the integer representing the character code of the
  517.         character is appended to the end of the list.  When a function
  518.         indicates that it takes an input source as a parameter, this
  519.         parameter can either be an input file pointer or a stream.
  520.         Similarly, when a function indicates that it takes an output
  521.         sink as a parameter, this parameter can either be an output file
  522.         pointer or a stream.
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.         XLISP                    THE EVALUATOR                    Page 9
  560.  
  561.  
  562.         THE EVALUATOR
  563.  
  564.         The process of evaluation in XLISP:
  565.  
  566.         Integers, floats, strings, file pointers, subrs, fsubrs, objects
  567.         and arrays evaluate to themselves
  568.  
  569.         Symbols evaluate to the value associated with their current
  570.         binding
  571.  
  572.         Lists are evaluated by evaluating the first element of the list
  573.         and then taking one of the following actions:
  574.  
  575.             If it is a subr, the remaining list elements are evaluated
  576.             and the subr is called with these evaluated expressions as
  577.             arguments.
  578.  
  579.             If it is an fsubr, the fsubr is called using the remaining
  580.             list elements as arguments (unevaluated)
  581.  
  582.             If it is a list:
  583.  
  584.                 If the list is a function closure (a list whose car is a
  585.                 lambda expression and whose cdr is an environment list),
  586.                 the car of the list is used as the function to be
  587.                 applied and the cdr is used as the environment to be
  588.                 extended with the parameter bindings.
  589.  
  590.                 If the list is a lambda expression, the current
  591.                 environment is used for the function application.
  592.  
  593.                     In either of the above two cases, the remaining list
  594.                     elements are evaluated and the resulting expressions
  595.                     are bound to the formal arguments of the lambda
  596.                     expression.  The body of the function is executed
  597.                     within this new binding environment.
  598.  
  599.                 If it is a list and the car of the list is 'macro', the
  600.                 remaining list elements are bound to the formal
  601.                 arguments of the macro expression.  The body of the
  602.                 function is executed within this new binding
  603.                 environment.  The result of this evaluation is
  604.                 considered the macro expansion.  This result is then
  605.                 evaluated in place of the original expression.
  606.  
  607.                 If it is an object, the second list element is evaluated
  608.                 and used as a message selector.  The message formed by
  609.                 combining the selector with the values of the remaining
  610.                 list elements is sent to the object.
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.         XLISP                 LEXICAL CONVENTIONS                Page 10
  629.  
  630.  
  631.         LEXICAL CONVENTIONS
  632.  
  633.         The following conventions must be followed when entering XLISP
  634.         programs:
  635.  
  636.         Comments in XLISP code begin with a semi-colon character and
  637.         continue to the end of the line.
  638.  
  639.         Symbol names in XLISP can consist of any sequence of non-blank
  640.         printable characters except the following:
  641.  
  642.                 ( ) ' ` , " ;
  643.  
  644.         Uppercase and lowercase characters are not distinguished within
  645.         symbol names.  All lowercase characters are mapped to uppercase
  646.         on input.
  647.  
  648.         Integer literals consist of a sequence of digits optionally
  649.         beginning with a '+' or '-'.  The range of values an integer can
  650.         represent is limited by the size of a C 'long' on the machine on
  651.         which XLISP is running.
  652.  
  653.         Floating point literals consist of a sequence of digits
  654.         optionally beginning with a '+' or '-' and including an embedded
  655.         decimal point.  The range of values a floating point number can
  656.         represent is limited by the size of a C 'float' ('double' on
  657.         machines with 32 bit addresses) on the machine on which XLISP is
  658.         running.
  659.  
  660.         Literal strings are sequences of characters surrounded by double
  661.         quotes.  Within quoted strings the '' character is used to allow
  662.         non-printable characters to be included.  The codes recognized
  663.         are:
  664.  
  665.                 \\        means the character '\'
  666.                 \n       means newline
  667.                 \t       means tab
  668.                 \r       means return
  669.                 \f       means form feed
  670.                 \nnn     means the character whose octal code is nnn
  671.  
  672.         XLISP defines several useful read macros:
  673.  
  674.                 '<expr>         == (quote <expr>)
  675.                 #'<expr>        == (function <expr>)
  676.                 #(<expr>...)    == an array of the specified expressions
  677.                 #x<hdigits>     == a hexadecimal number
  678.                 #\<char> == the ASCII code of the character
  679.                 `<expr>         == (backquote <expr>)
  680.                 ,<expr>         == (comma <expr>)
  681.                 ,@<expr>        == (comma-at <expr>)
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.         XLISP                      READTABLES                    Page 11
  698.  
  699.  
  700.         READTABLES
  701.  
  702.         The behaviour of the reader is controlled by a data structure
  703.         called a "readtable".  The reader uses the symbol *READTABLE* to
  704.         locate the current readtable.  This table controls the
  705.         interpretation of input characters.  It is an array with 128
  706.         entries, one for each of the ASCII character codes.  Each entry
  707.         contains one of the following things:
  708.  
  709.                 NIL             Indicating an invalid character
  710.                 :CONSTITUENT    Indicating a symbol constituent
  711.                 :WHITE-SPACE    Indicating a whitespace character
  712.                 (:TMACRO . fun) Terminating readmacro
  713.                 (:NMACRO . fun) Non-terminating readmacro
  714.  
  715.         In the case of the last two forms, the "fun" component is a
  716.         function definition.  This can either be a pointer to a built-in
  717.         readmacro function or a lambda expression.  The function should
  718.         take two parameters.  The first is the input stream and the
  719.         second is the character that caused the invocation of the
  720.         readmacro.  The character is passed as an integer.  The
  721.         readmacro function should return NIL to indicate that the
  722.         character should be treated as white space or a value consed
  723.         with NIL to indicate that the readmacro should be treated as an
  724.         occurance of the specified value.  Of course, the readmacro code
  725.         is free to read additional characters from the input stream.
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.  
  754.  
  755.  
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.         XLISP                       OBJECTS                      Page 12
  767.  
  768.  
  769.         OBJECTS
  770.  
  771.         Definitions:
  772.  
  773.             o selector - a symbol used to select an appropriate method
  774.             o message - a selector and a list of actual arguments
  775.             o method - the code that implements a message
  776.  
  777.         Since XLISP was created to provide a simple basis for
  778.         experimenting with object-oriented programming, one of the
  779.         primitive data types included is 'object'.  In XLISP, an object
  780.         consists of a data structure containing a pointer to the
  781.         object's class as well as an array containing the values of the
  782.         object's instance variables.
  783.  
  784.         Officially, there is no way to see inside an object (look at the
  785.         values of its instance variables).  The only way to communicate
  786.         with an object is by sending it a message.  When the XLISP
  787.         evaluator evaluates a list the value of whose first element is
  788.         an object, it interprets the value of the second element of the
  789.         list (which must be a symbol) as the message selector.  The
  790.         evaluator determines the class of the receiving object and
  791.         attempts to find a method corresponding to the message selector
  792.         in the set of messages defined for that class.  If the message
  793.         is not found in the object's class and the class has a super-
  794.         class, the search continues by looking at the messages defined
  795.         for the super-class.  This process continues from one super-
  796.         class to the next until a method for the message is found.  If
  797.         no method is found, an error occurs.
  798.  
  799.         When a method is found, the evaluator binds the receiving object
  800.         to the symbol 'self', binds the class in which the method was
  801.         found to the symbol 'msgclass', and evaluates the method using
  802.         the remaining elements of the original list as arguments to the
  803.         method.  These arguments are always evaluated prior to being
  804.         bound to their corresponding formal arguments.  The result of
  805.         evaluating the method becomes the result of the expression.
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.         XLISP                       OBJECTS                      Page 13
  836.  
  837.  
  838.         THE 'Object' CLASS
  839.  
  840.         Classes:
  841.  
  842.         Object  THE TOP OF THE CLASS HEIRARCHY
  843.  
  844.             Messages:
  845.  
  846.                 :show  SHOW AN OBJECT'S INSTANCE VARIABLES
  847.                     returns     the object
  848.  
  849.                 :class  RETURN THE CLASS OF AN OBJECT
  850.                     returns     the class of the object
  851.  
  852.                 :isnew  THE DEFAULT OBJECT INITIALIZATION ROUTINE
  853.                     returns     the object
  854.  
  855.                 :sendsuper <sel> [<args>]...  SEND SUPERCLASS A MESSAGE
  856.                     <sel>       the message selector
  857.                     <args>      the message arguments
  858.                     returns     the result of sending the message
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.         XLISP                       OBJECTS                      Page 14
  905.  
  906.  
  907.         THE 'Class' CLASS
  908.  
  909.         Class   THE CLASS OF ALL OBJECT CLASSES (including itself)
  910.  
  911.             Messages:
  912.  
  913.                 :new  CREATE A NEW INSTANCE OF A CLASS
  914.                     returns     the new class object
  915.  
  916.                 :isnew <ivars> [<cvars>[<super>]]  INITIALIZE A NEW CLASS
  917.                     <ivars>     the list of instance variable symbols
  918.                     <cvars>     the list of class variable symbols
  919.                     <super>     the superclass (default is Object)
  920.                     returns     the new class object
  921.  
  922.                 :answer <msg> <fargs> <code>  ADD A MESSAGE TO A CLASS
  923.                     <msg>       the message symbol
  924.                     <fargs>     the formal argument list
  925.                                   this list is of the form:
  926.                                     ([<farg>]...
  927.                                      [&optional [<oarg>]...]
  928.                                      [&rest <rarg>]
  929.                                      [&aux [<aux>]...])
  930.                                   where
  931.                                     <farg>   a formal argument
  932.                                     <oarg>   an optional argument
  933.                                     <rarg>   bound to rest of the arguments
  934.                                     <aux>    a auxiliary variable
  935.                     <code>      a list of executable expressions
  936.                     returns     the object
  937.  
  938.  
  939.         When a new instance of a class is created by sending the message
  940.         ':new' to an existing class, the message ':isnew' followed by
  941.         whatever parameters were passed to the ':new' message is sent to
  942.         the newly created object.
  943.  
  944.         When a new class is created by sending the ':new' message to the
  945.         object 'Class', an optional parameter may be specified
  946.         indicating the superclass of the new class.  If this parameter
  947.         is omitted, the new class will be a subclass of 'Object'.  A
  948.         class inherits all instance variables, class variables, and
  949.         methods from its super-class.
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.         XLISP                       SYMBOLS                      Page 15
  974.  
  975.  
  976.         SYMBOLS
  977.  
  978.             o self - the current object (within a message context)
  979.             o msgclass - the class in which the current method was found
  980.             o *obarray* - the object hash table
  981.             o *standard-input* - the standard input file
  982.             o *standard-output* - the standard output file
  983.             o *breakenable* - flag controlling entering break loop on errors
  984.             o *tracenable* - enable baktrace on errors
  985.             o *tracelimit* - number of levels of trace back information
  986.             o *evalhook* - user substitute for the evaluator function
  987.             o *applyhook* - (not yet implemented)
  988.             o *readtable* - the current readtable
  989.             o *unbound* - indicator for unbound symbols
  990.             o *gc-flag* - controls the printing of gc messages
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.         XLISP                 EVALUATION FUNCTIONS               Page 16
  1043.  
  1044.  
  1045.         EVALUATION FUNCTIONS
  1046.  
  1047.         (eval <expr>)  EVALUATE AN XLISP EXPRESSION
  1048.             <expr>      the expression to be evaluated
  1049.             returns     the result of evaluating the expression
  1050.  
  1051.         (apply <fun> <args>)  APPLY A FUNCTION TO A LIST OF ARGUMENTS
  1052.             <fun>       the function to apply (or function symbol)
  1053.             <args>      the argument list
  1054.             returns     the result of applying the function to the arguments
  1055.  
  1056.         (funcall <fun> [<arg>]...)  CALL A FUNCTION WITH ARGUMENTS
  1057.             <fun>       the function to call (or function symbol)
  1058.             <arg>       arguments to pass to the function
  1059.             returns     the result of calling the function with the arguments
  1060.  
  1061.         (quote <expr>)  RETURN AN EXPRESSION UNEVALUATED
  1062.             <expr>      the expression to be quoted (quoted)
  1063.             returns     <expr> unevaluated
  1064.  
  1065.         (function <expr>)  QUOTE A FUNCTION
  1066.             <expr>      the function to be quoted (quoted)
  1067.             returns     a function closure
  1068.  
  1069.         (backquote <expr>)  FILL IN A TEMPLATE
  1070.             <expr>      the template
  1071.             returns     a copy of the template with comma and comma-at
  1072.                         expressions expanded
  1073.  
  1074.         (lambda <args> [<expr>]...)  MAKE A FUNCTION CLOSURE
  1075.             <args>      the argument list (quoted)
  1076.             <expr>      expressions of the function body
  1077.             returns     the function closure
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.         XLISP                   SYMBOL FUNCTIONS                 Page 17
  1112.  
  1113.  
  1114.         SYMBOL FUNCTIONS
  1115.  
  1116.         (set <sym> <expr>)  SET THE VALUE OF A SYMBOL
  1117.             <sym>       the symbol being set
  1118.             <expr>      the new value
  1119.             returns     the new value
  1120.  
  1121.         (setq [<sym> <expr>]...)  SET THE VALUE OF A SYMBOL
  1122.             <sym>       the symbol being set (quoted)
  1123.             <expr>      the new value
  1124.             returns     the new value
  1125.  
  1126.         (setf [<place> <expr>]...)  SET THE VALUE OF A FIELD
  1127.             <place>     the field specifier (quoted):
  1128.                             <sym>                set value of a symbol
  1129.                             (car <expr>)         set car of a list node
  1130.                             (cdr <expr>)         set cdr of a list node
  1131.                             (nth <n> <expr>)     set nth car of a list
  1132.                             (aref <expr> <n>)    set nth element of an array
  1133.                             (get <sym> <prop>)   set value of a property
  1134.                             (symbol-value <sym>) set value of a symbol
  1135.                             (symbol-plist <sym>) set property list of a symbol
  1136.             <value>     the new value
  1137.             returns     the new value
  1138.  
  1139.         (defun <sym> <fargs> [<expr>]...)  DEFINE A FUNCTION
  1140.         (defmacro <sym> <fargs> [<expr>]...)  DEFINE A MACRO
  1141.             <sym>       symbol being defined (quoted)
  1142.             <fargs>     list of formal arguments (quoted)
  1143.                           this list is of the form:
  1144.                             ([<farg>]...
  1145.                              [&optional [<oarg>]...]
  1146.                              [&rest <rarg>]
  1147.                              [&aux [<aux>]...])
  1148.                           where
  1149.                             <farg>      is a formal argument
  1150.                             <oarg>      is an optional argument
  1151.                             <rarg>      bound to the rest of the arguments
  1152.                             <aux>       is an auxiliary variable
  1153.             <expr>      expressions constituting the body of the
  1154.                         function (quoted)
  1155.             returns     the function symbol
  1156.  
  1157.         (gensym [<tag>])  GENERATE A SYMBOL
  1158.             <tag>       string or number
  1159.             returns     the new symbol
  1160.  
  1161.         (intern <pname>)  MAKE AN INTERNED SYMBOL
  1162.             <pname>     the symbol's print name string
  1163.             returns     the new symbol
  1164.  
  1165.         (make-symbol <pname>)  MAKE AN UNINTERNED SYMBOL
  1166.             <pname>     the symbol's print name string
  1167.             returns     the new symbol
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.         XLISP                   SYMBOL FUNCTIONS                 Page 18
  1181.  
  1182.  
  1183.         (symbol-name <sym>)  GET THE PRINT NAME OF A SYMBOL
  1184.             <sym>       the symbol
  1185.             returns     the symbol's print name
  1186.  
  1187.         (symbol-value <sym>)  GET THE VALUE OF A SYMBOL
  1188.             <sym>       the symbol
  1189.             returns     the symbol's value
  1190.  
  1191.         (symbol-plist <sym>)  GET THE PROPERTY LIST OF A SYMBOL
  1192.             <sym>       the symbol
  1193.             returns     the symbol's property list
  1194.  
  1195.         (hash <sym> <n>)  COMPUTE THE HASH INDEX FOR A SYMBOL
  1196.             <sym>       the symbol or string
  1197.             <n>         the table size (integer)
  1198.             returns     the hash index (integer)
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.         XLISP               PROPERTY LIST FUNCTIONS              Page 19
  1250.  
  1251.  
  1252.         PROPERTY LIST FUNCTIONS
  1253.  
  1254.         (get <sym> <prop>)  GET THE VALUE OF A PROPERTY
  1255.             <sym>       the symbol
  1256.             <prop>      the property symbol
  1257.             returns     the property value or nil
  1258.  
  1259.         (putprop <sym> <val> <prop>)  PUT A PROPERTY ONTO A PROPERTY LIST
  1260.             <sym>       the symbol
  1261.             <val>       the property value
  1262.             <prop>      the property symbol
  1263.             returns     the property value
  1264.  
  1265.         (remprop <sym> <prop>)  REMOVE A PROPERTY
  1266.             <sym>       the symbol
  1267.             <prop>      the property symbol
  1268.             returns     nil
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.         XLISP                   ARRAY FUNCTIONS                  Page 20
  1319.  
  1320.  
  1321.         ARRAY FUNCTIONS
  1322.  
  1323.         (aref <array> <n>)  GET THE NTH ELEMENT OF AN ARRAY
  1324.             <array>     the array
  1325.             <n>         the array index (integer)
  1326.             returns     the value of the array element
  1327.  
  1328.         (make-array <size>)  MAKE A NEW ARRAY
  1329.             <size>      the size of the new array (integer)
  1330.             returns     the new array
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.         XLISP                    LIST FUNCTIONS                  Page 21
  1388.  
  1389.  
  1390.         LIST FUNCTIONS
  1391.  
  1392.         (car <expr>)  RETURN THE CAR OF A LIST NODE
  1393.             <expr>      the list node
  1394.             returns     the car of the list node
  1395.  
  1396.         (cdr <expr>)  RETURN THE CDR OF A LIST NODE
  1397.             <expr>      the list node
  1398.             returns     the cdr of the list node
  1399.  
  1400.         (cxxr <expr>)  ALL CxxR COMBINATIONS
  1401.         (cxxxr <expr>)  ALL CxxxR COMBINATIONS
  1402.         (cxxxxr <expr>)  ALL CxxxxR COMBINATIONS
  1403.  
  1404.         (cons <expr1> <expr2>)  CONSTRUCT A NEW LIST NODE
  1405.             <expr1>     the car of the new list node
  1406.             <expr2>     the cdr of the new list node
  1407.             returns     the new list node
  1408.  
  1409.         (list [<expr>]...)  CREATE A LIST OF VALUES
  1410.             <expr>      expressions to be combined into a list
  1411.             returns     the new list
  1412.  
  1413.         (append [<expr>]...)  APPEND LISTS
  1414.             <expr>      lists whose elements are to be appended
  1415.             returns     the new list
  1416.  
  1417.         (reverse <expr>)  REVERSE A LIST
  1418.             <expr>      the list to reverse
  1419.             returns     a new list in the reverse order
  1420.  
  1421.         (last <list>)  RETURN THE LAST LIST NODE OF A LIST
  1422.             <list>      the list
  1423.             returns     the last list node in the list
  1424.  
  1425.         (member <expr> <list> [<key> <test>])  FIND AN EXPRESSION IN A LIST
  1426.             <expr>      the expression to find
  1427.             <list>      the list to search
  1428.             <key>       the keyword :test or :test-not
  1429.             <test>      the test function (defaults to eql)
  1430.             returns     the remainder of the list starting with the expression
  1431.  
  1432.         (assoc <expr> <alist> [<key> <test>])  FIND AN EXPRESSION IN AN A-LIST
  1433.             <expr>      the expression to find
  1434.             <alist>     the association list
  1435.             <key>       the keyword :test or :test-not
  1436.             <test>      the test function (defaults to eql)
  1437.             returns     the alist entry or nil
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.         XLISP                    LIST FUNCTIONS                  Page 22
  1457.  
  1458.  
  1459.         (remove <expr> <list> [<key> <test>])  REMOVE AN EXPRESSION
  1460.             <expr>      the expression to delete
  1461.             <list>      the list
  1462.             <key>       the keyword :test or :test-not
  1463.             <test>      the test function (defaults to eql)
  1464.             returns     the list with the matching expressions deleted
  1465.  
  1466.         (length <expr>)  FIND THE LENGTH OF A LIST OR STRING
  1467.             <expr>      the list or string
  1468.             returns     the length of the list or string
  1469.  
  1470.         (nth <n> <list>)  RETURN THE NTH ELEMENT OF A LIST
  1471.             <n>         the number of the element to return (zero origin)
  1472.             <list>      the list
  1473.             returns     the nth element or nil if the list isn't that long
  1474.  
  1475.         (nthcdr <n> <list>)  RETURN THE NTH CDR OF A LIST
  1476.             <n>         the number of the element to return (zero origin)
  1477.             <list>      the list
  1478.             returns     the nth cdr or nil if the list isn't that long
  1479.  
  1480.         (mapc <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CARS
  1481.             <fcn>       the function or function name
  1482.             <listn>     a list for each argument of the function
  1483.             returns     the first list of arguments
  1484.  
  1485.         (mapcar <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CARS
  1486.             <fcn>       the function or function name
  1487.             <listn>     a list for each argument of the function
  1488.             returns     a list of the values returned
  1489.  
  1490.         (mapl <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CDRS
  1491.             <fcn>       the function or function name
  1492.             <listn>     a list for each argument of the function
  1493.             returns     the first list of arguments
  1494.  
  1495.         (maplist <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CDRS
  1496.             <fcn>       the function or function name
  1497.             <listn>     a list for each argument of the function
  1498.             returns     a list of the values returned
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.         XLISP                    LIST FUNCTIONS                  Page 23
  1526.  
  1527.  
  1528.         (subst <to> <from> <expr> [<key> <test>])  SUBSTITUTE EXPRESSIONS
  1529.             <to>        the new expression
  1530.             <from>      the old expression
  1531.             <expr>      the expression in which to do the substitutions
  1532.             <key>       the keyword :test or :test-not
  1533.             <test>      the test function (defaults to eql)
  1534.             returns     the expression with substitutions
  1535.  
  1536.         (sublis <alist> <expr> [<key> <test>])  SUBSTITUTE WITH AN A-LIST
  1537.             <alist>     the association list
  1538.             <expr>      the expression in which to do the substitutions
  1539.             <key>       the keyword :test or :test-not
  1540.             <test>      the test function (defaults to eql)
  1541.             returns     the expression with substitutions
  1542.  
  1543.  
  1544.  
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.  
  1593.  
  1594.         XLISP              DESTRUCTIVE LIST FUNCTIONS            Page 24
  1595.  
  1596.  
  1597.         DESTRUCTIVE LIST FUNCTIONS
  1598.  
  1599.         (rplaca <list> <expr>)  REPLACE THE CAR OF A LIST NODE
  1600.             <list>      the list node
  1601.             <expr>      the new value for the car of the list node
  1602.             returns     the list node after updating the car
  1603.  
  1604.         (rplacd <list> <expr>)  REPLACE THE CDR OF A LIST NODE
  1605.             <list>      the list node
  1606.             <expr>      the new value for the cdr of the list node
  1607.             returns     the list node after updating the cdr
  1608.  
  1609.         (nconc [<list>]...)  DESTRUCTIVELY CONCATENATE LISTS
  1610.             <list>      lists to concatenate
  1611.             returns     the result of concatenating the lists
  1612.  
  1613.         (delete <expr> <list> [<key> <test>])  DELETE AN EXPRESSION FROM A LIST
  1614.             <expr>      the expression to delete
  1615.             <list>      the list
  1616.             <key>       the keyword :test or :test-not
  1617.             <test>      the test function (defaults to eql)
  1618.             returns     the list with the matching expressions deleted
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.  
  1627.  
  1628.  
  1629.  
  1630.  
  1631.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.  
  1656.  
  1657.  
  1658.  
  1659.  
  1660.  
  1661.  
  1662.  
  1663.         XLISP                 PREDICATE FUNCTIONS                Page 25
  1664.  
  1665.  
  1666.         PREDICATE FUNCTIONS
  1667.  
  1668.         (atom <expr>)  IS THIS AN ATOM?
  1669.             <expr>      the expression to check
  1670.             returns     t if the value is an atom, nil otherwise
  1671.  
  1672.         (symbolp <expr>)  IS THIS A SYMBOL?
  1673.             <expr>      the expression to check
  1674.             returns     t if the expression is a symbol, nil otherwise
  1675.  
  1676.         (numberp <expr>)  IS THIS A NUMBER?
  1677.             <expr>      the expression to check
  1678.             returns     t if the expression is a number, nil otherwise
  1679.  
  1680.         (null <expr>)  IS THIS AN EMPTY LIST?
  1681.             <expr>      the list to check
  1682.             returns     t if the list is empty, nil otherwise
  1683.  
  1684.         (not <expr>)  IS THIS FALSE?
  1685.             <expr>      the expression to check
  1686.             return      t if the expression is nil, nil otherwise
  1687.  
  1688.         (listp <expr>)  IS THIS A LIST?
  1689.             <expr>      the expression to check
  1690.             returns     t if the value is a list node or nil, nil otherwise
  1691.  
  1692.         (consp <expr>)  IS THIS A NON-EMPTY LIST?
  1693.             <expr>      the expression to check
  1694.             returns     t if the value is a list node, nil otherwise
  1695.  
  1696.         (boundp <sym>)  IS THIS A BOUND SYMBOL?
  1697.             <sym>       the symbol
  1698.             returns     t if a value is bound to the symbol, nil otherwise
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.  
  1724.  
  1725.  
  1726.  
  1727.  
  1728.  
  1729.  
  1730.  
  1731.  
  1732.         XLISP                 PREDICATE FUNCTIONS                Page 26
  1733.  
  1734.  
  1735.         (minusp <expr>)  IS THIS NUMBER NEGATIVE?
  1736.             <expr>      the number to test
  1737.             returns     t if the number is negative, nil otherwise
  1738.  
  1739.         (zerop <expr>)  IS THIS NUMBER ZERO?
  1740.             <expr>      the number to test
  1741.             returns     t if the number is zero, nil otherwise
  1742.  
  1743.         (plusp <expr>)  IS THIS NUMBER POSITIVE?
  1744.             <expr>      the number to test
  1745.             returns     t if the number is positive, nil otherwise
  1746.  
  1747.         (evenp <expr>)  IS THIS NUMBER EVEN?
  1748.             <expr>      the number to test
  1749.             returns     t if the number is even, nil otherwise
  1750.  
  1751.         (oddp <expr>)  IS THIS NUMBER ODD?
  1752.             <expr>      the number to test
  1753.             returns     t if the number is odd, nil otherwise
  1754.  
  1755.         (eq <expr1> <expr2>)  ARE THE EXPRESSIONS IDENTICAL?
  1756.             <expr1>     the first expression
  1757.             <expr2>     the second expression
  1758.             returns     t if they are equal, nil otherwise
  1759.  
  1760.         (eql <expr1> <expr2>)  ARE THE EXPRESSIONS IDENTICAL?
  1761.                                 (WORKS WITH NUMBERS AND STRINGS)
  1762.             <expr1>     the first expression
  1763.             <expr2>     the second expression
  1764.             returns     t if they are equal, nil otherwise
  1765.  
  1766.         (equal <expr1> <expr2>)  ARE THE EXPRESSIONS EQUAL?
  1767.             <expr1>     the first expression
  1768.             <expr2>     the second expression
  1769.             returns     t if they are equal, nil otherwise
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.  
  1792.  
  1793.  
  1794.  
  1795.  
  1796.  
  1797.  
  1798.  
  1799.  
  1800.  
  1801.         XLISP                  CONTROL CONSTRUCTS                Page 27
  1802.  
  1803.  
  1804.         CONTROL CONSTRUCTS
  1805.  
  1806.         (cond [<pair>]...)  EVALUATE CONDITIONALLY
  1807.             <pair>      pair consisting of:
  1808.                             (<pred> [<expr>]...)
  1809.                           where
  1810.                             <pred>      is a predicate expression
  1811.                             <expr>      evaluated if the predicate
  1812.                                         is not nil
  1813.             returns     the value of the first expression whose predicate
  1814.                         is not nil
  1815.  
  1816.         (and [<expr>]...)  THE LOGICAL AND OF A LIST OF EXPRESSIONS
  1817.             <expr>      the expressions to be ANDed
  1818.             returns     nil if any expression evaluates to nil,
  1819.                         otherwise the value of the last expression
  1820.                         (evaluation of expressions stops after the first
  1821.                          expression that evaluates to nil)
  1822.  
  1823.         (or [<expr>]...)  THE LOGICAL OR OF A LIST OF EXPRESSIONS
  1824.             <expr>      the expressions to be ORed
  1825.             returns     nil if all expressions evaluate to nil,
  1826.                         otherwise the value of the first non-nil expression
  1827.                         (evaluation of expressions stops after the first
  1828.                          expression that does not evaluate to nil)
  1829.  
  1830.         (if <texpr> <expr1> [<expr2>])  EXECUTE EXPRESSIONS CONDITIONALLY
  1831.             <texpr>     the test expression
  1832.             <expr1>     the expression to be evaluated if texpr is non-nil
  1833.             <expr2>     the expression to be evaluated if texpr is nil
  1834.             returns     the value of the selected expression
  1835.  
  1836.         (case <expr> [<case>]...)  SELECT BY CASE
  1837.             <expr>      the selection expression
  1838.             <case>      pair consisting of:
  1839.                             (<value> [<expr>]...)
  1840.                           where:
  1841.                             <value>     is a single expression or a list of
  1842.                                         expressions (unevaluated)
  1843.                             <expr>      are expressions to execute if the
  1844.                                         case matches
  1845.             returns     the value of the last expression of the matching case
  1846.  
  1847.         (let ([<binding>]...) [<expr>]...)  CREATE LOCAL BINDINGS
  1848.         (let* ([<binding>]...) [<expr>]...)  LET WITH SEQUENTIAL BINDING
  1849.             <binding>   the variable bindings each of which is either:
  1850.                         1)  a symbol (which is initialized to nil)
  1851.                         2)  a list whose car is a symbol and whose cadr
  1852.                                 is an initialization expression
  1853.             <expr>      the expressions to be evaluated
  1854.             returns     the value of the last expression
  1855.  
  1856.         (catch <sym> [<expr>]...)  EVALUATE EXPRESSIONS AND CATCH THROWS
  1857.             <sym>       the catch tag
  1858.  
  1859.  
  1860.  
  1861.  
  1862.  
  1863.  
  1864.  
  1865.  
  1866.  
  1867.  
  1868.  
  1869.  
  1870.         XLISP                  CONTROL CONSTRUCTS                Page 28
  1871.  
  1872.  
  1873.             <expr>      expressions to evaluate
  1874.             returns     the value of the last expression the throw expression
  1875.  
  1876.         (throw <sym> [<expr>])  THROW TO A CATCH
  1877.             <sym>       the catch tag
  1878.             <expr>      the value for the catch to return (defaults to nil)
  1879.             returns     never returns
  1880.  
  1881.  
  1882.  
  1883.  
  1884.  
  1885.  
  1886.  
  1887.  
  1888.  
  1889.  
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.  
  1920.  
  1921.  
  1922.  
  1923.  
  1924.  
  1925.  
  1926.  
  1927.  
  1928.  
  1929.  
  1930.  
  1931.  
  1932.  
  1933.  
  1934.  
  1935.  
  1936.  
  1937.  
  1938.  
  1939.         XLISP                  LOOPING CONSTRUCTS                Page 29
  1940.  
  1941.  
  1942.         LOOPING CONSTRUCTS
  1943.  
  1944.         (do ([<binding>]...) (<texpr> [<rexpr>]...) [<expr>]...)
  1945.         (do* ([<binding>]...) (<texpr> [<rexpr>]...) [<expr>]...)
  1946.             <binding>   the variable bindings each of which is either:
  1947.                         1)  a symbol (which is initialized to nil)
  1948.                         2)  a list of the form: (<sym> <init> [<step>])
  1949.                             where:
  1950.                                 <sym>  is the symbol to bind
  1951.                                 <init> is the initial value of the symbol
  1952.                                 <step> is a step expression
  1953.             <texpr>     the termination test expression
  1954.             <rexpr>     result expressions (the default is nil)
  1955.             <expr>      the body of the loop (treated like an implicit prog)
  1956.             returns     the value of the last result expression
  1957.  
  1958.         (dolist (<sym> <expr> [<rexpr>]) [<expr>]...)  LOOP THROUGH A LIST
  1959.             <sym>       the symbol to bind to each list element
  1960.             <expr>      the list expression
  1961.             <rexpr>     the result expression (the default is nil)
  1962.             <expr>      the body of the loop (treated like an implicit prog)
  1963.  
  1964.         (dotimes (<sym> <expr> [<rexpr>]) [<expr>]...)  LOOP FROM ZERO TO N-1
  1965.             <sym>       the symbol to bind to each value from 0 to n-1
  1966.             <expr>      the number of times to loop
  1967.             <rexpr>     the result expression (the default is nil)
  1968.             <expr>      the body of the loop (treated like an implicit prog)
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.  
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.  
  1986.  
  1987.  
  1988.  
  1989.  
  1990.  
  1991.  
  1992.  
  1993.  
  1994.  
  1995.  
  1996.  
  1997.  
  1998.  
  1999.  
  2000.  
  2001.  
  2002.  
  2003.  
  2004.  
  2005.  
  2006.  
  2007.  
  2008.         XLISP                 THE PROGRAM FEATURE                Page 30
  2009.  
  2010.  
  2011.         THE PROGRAM FEATURE
  2012.  
  2013.         (prog ([<binding>]...) [<expr>]...)  THE PROGRAM FEATURE
  2014.         (prog* ([<binding>]...) [<expr>]...)  PROG WITH SEQUENTIAL BINDING
  2015.             <binding>   the variable bindings each of which is either:
  2016.                         1)  a symbol (which is initialized to nil)
  2017.                         2)  a list whose car is a symbol and whose cadr
  2018.                                 is an initialization expression
  2019.             <expr>      expressions to evaluate or tags (symbols)
  2020.             returns     nil or the argument passed to the return function
  2021.  
  2022.         (go <sym>)  GO TO A TAG WITHIN A PROG CONSTRUCT
  2023.             <sym>       the tag (quoted)
  2024.             returns     never returns
  2025.  
  2026.         (return [<expr>])  CAUSE A PROG CONSTRUCT TO RETURN A VALUE
  2027.             <expr>      the value (defaults to nil)
  2028.             returns     never returns
  2029.  
  2030.         (prog1 <expr1> [<expr>]...)  EXECUTE EXPRESSIONS SEQUENTIALLY
  2031.             <expr1>     the first expression to evaluate
  2032.             <expr>      the remaining expressions to evaluate
  2033.             returns     the value of the first expression
  2034.  
  2035.         (prog2 <expr1> <expr2> [<expr>]...)  EXECUTE EXPRESSIONS SEQUENTIALLY
  2036.             <expr1>     the first expression to evaluate
  2037.             <expr2>     the second expression to evaluate
  2038.             <expr>      the remaining expressions to evaluate
  2039.             returns     the value of the second expression
  2040.  
  2041.         (progn [<expr>]...)  EXECUTE EXPRESSIONS SEQUENTIALLY
  2042.             <expr>      the expressions to evaluate
  2043.             returns     the value of the last expression (or nil)
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.  
  2054.  
  2055.  
  2056.  
  2057.  
  2058.  
  2059.  
  2060.  
  2061.  
  2062.  
  2063.  
  2064.  
  2065.  
  2066.  
  2067.  
  2068.  
  2069.  
  2070.  
  2071.  
  2072.  
  2073.  
  2074.  
  2075.  
  2076.  
  2077.         XLISP             DEBUGGING AND ERROR HANDLING           Page 31
  2078.  
  2079.  
  2080.         DEBUGGING AND ERROR HANDLING
  2081.  
  2082.         (error <emsg> [<arg>])  SIGNAL A NON-CORRECTABLE ERROR
  2083.             <emsg>      the error message string
  2084.             <arg>       the argument expression (printed after the message)
  2085.             returns     never returns
  2086.  
  2087.         (cerror <cmsg> <emsg> [<arg>])  SIGNAL A CORRECTABLE ERROR
  2088.             <cmsg>      the continue message string
  2089.             <emsg>      the error message string
  2090.             <arg>       the argument expression (printed after the message)
  2091.             returns     nil when continued from the break loop
  2092.  
  2093.         (break [<bmsg> [<arg>]])  ENTER A BREAK LOOP
  2094.             <bmsg>      the break message string (defaults to "**BREAK**")
  2095.             <arg>       the argument expression (printed after the message)
  2096.             returns     nil when continued from the break loop
  2097.  
  2098.         (clean-up)  CLEAN-UP AFTER AN ERROR
  2099.             returns     never returns
  2100.  
  2101.         (top-level)  CLEAN-UP AFTER AN ERROR AND RETURN TO THE TOP LEVEL
  2102.             returns     never returns
  2103.  
  2104.         (continue)  CONTINUE FROM A CORRECTABLE ERROR
  2105.             returns     never returns
  2106.  
  2107.         (errset <expr> [<pflag>])  TRAP ERRORS
  2108.             <expr>      the expression to execute
  2109.             <pflag>     flag to control printing of the error message
  2110.             returns     the value of the last expression consed with nil
  2111.                         or nil on error
  2112.  
  2113.         (baktrace [<n>])  PRINT N LEVELS OF TRACE BACK INFORMATION
  2114.             <n>         the number of levels (defaults to all levels)
  2115.             returns     nil
  2116.  
  2117.         (evalhook <expr> <ehook> <ahook> [<env>])  EVALUATE WITH HOOKS
  2118.             <expr>      the expression to evaluate
  2119.             <ehook>     the value for *evalhook*
  2120.             <ahook>     the value for *applyhook*
  2121.             <env>       the environment (default is nil)
  2122.             returns     the result of evaluating the expression
  2123.  
  2124.  
  2125.  
  2126.  
  2127.  
  2128.  
  2129.  
  2130.  
  2131.  
  2132.  
  2133.  
  2134.  
  2135.  
  2136.  
  2137.  
  2138.  
  2139.  
  2140.  
  2141.  
  2142.  
  2143.  
  2144.  
  2145.  
  2146.         XLISP                 ARITHMETIC FUNCTIONS               Page 32
  2147.  
  2148.  
  2149.         ARITHMETIC FUNCTIONS
  2150.  
  2151.         (truncate <expr>)  TRUNCATES A FLOATING POINT NUMBER TO AN INTEGER
  2152.             <expr>      the number
  2153.             returns     the result of truncating the number
  2154.  
  2155.         (float <expr>)  CONVERTS AN INTEGER TO A FLOATING POINT NUMBER
  2156.             <expr>      the number
  2157.             returns     the result of floating the integer
  2158.  
  2159.         (+ <expr>...)  ADD A LIST OF NUMBERS
  2160.             <expr>      the numbers
  2161.             returns     the result of the addition
  2162.  
  2163.         (- <expr>...)  SUBTRACT A LIST OF NUMBERS OR NEGATE A SINGLE NUMBER
  2164.             <expr>      the numbers
  2165.             returns     the result of the subtraction
  2166.  
  2167.         (* <expr>...)  MULTIPLY A LIST OF NUMBERS
  2168.             <expr>      the numbers
  2169.             returns     the result of the multiplication
  2170.  
  2171.         (/ <expr>...)  DIVIDE A LIST OF NUMBERS
  2172.             <expr>      the numbers
  2173.             returns     the result of the division
  2174.  
  2175.         (1+ <expr>)  ADD ONE TO A NUMBER
  2176.             <expr>      the number
  2177.             returns     the number plus one
  2178.  
  2179.         (1- <expr>)  SUBTRACT ONE FROM A NUMBER
  2180.             <expr>      the number
  2181.             returns     the number minus one
  2182.  
  2183.         (rem <expr>...)  REMAINDER OF A LIST OF NUMBERS
  2184.             <expr>      the numbers
  2185.             returns     the result of the remainder operation
  2186.  
  2187.         (min <expr>...)  THE SMALLEST OF A LIST OF NUMBERS
  2188.             <expr>      the expressions to be checked
  2189.             returns     the smallest number in the list
  2190.  
  2191.         (max <expr>...)  THE LARGEST OF A LIST OF NUMBERS
  2192.             <expr>      the expressions to be checked
  2193.             returns     the largest number in the list
  2194.  
  2195.         (abs <expr>)  THE ABSOLUTE VALUE OF A NUMBER
  2196.             <expr>      the number
  2197.             returns     the absolute value of the number
  2198.  
  2199.         (random <n>)  COMPUTE A RANDOM NUMBER BETWEEN 1 and N-1
  2200.             <n>         the upper bound (integer)
  2201.             returns     a random number
  2202.  
  2203.  
  2204.  
  2205.  
  2206.  
  2207.  
  2208.  
  2209.  
  2210.  
  2211.  
  2212.  
  2213.  
  2214.  
  2215.         XLISP                 ARITHMETIC FUNCTIONS               Page 33
  2216.  
  2217.  
  2218.         (sin <expr>)  COMPUTE THE SINE OF A NUMBER
  2219.             <expr>      the floating point number
  2220.             returns     the sine of the number
  2221.  
  2222.         (cos <expr>)  COMPUTE THE COSINE OF A NUMBER
  2223.             <expr>      the floating point number
  2224.             returns     the cosine of the number
  2225.  
  2226.         (tan <expr>)  COMPUTE THE TANGENT OF A NUMBER
  2227.             <expr>      the floating point number
  2228.             returns     the tangent of the number
  2229.  
  2230.         (expt <x-expr> <y-expr>)  COMPUTE X TO THE Y POWER
  2231.             <x-expr>    the floating point number
  2232.             <y-expr>    the floating point exponent
  2233.             returns     x to the y power
  2234.  
  2235.         (exp <x-expr>)  COMPUTE E TO THE X POWER
  2236.             <x-expr>    the floating point number
  2237.             returns     e to the x power
  2238.  
  2239.         (sqrt <expr>)  COMPUTE THE SQUARE ROOT OF A NUMBER
  2240.             <expr>      the floating point number
  2241.             returns     the square root of the number
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.  
  2249.  
  2250.  
  2251.  
  2252.  
  2253.  
  2254.  
  2255.  
  2256.  
  2257.  
  2258.  
  2259.  
  2260.  
  2261.  
  2262.  
  2263.  
  2264.  
  2265.  
  2266.  
  2267.  
  2268.  
  2269.  
  2270.  
  2271.  
  2272.  
  2273.  
  2274.  
  2275.  
  2276.  
  2277.  
  2278.  
  2279.  
  2280.  
  2281.  
  2282.  
  2283.  
  2284.         XLISP              BITWISE LOGICAL FUNCTIONS             Page 34
  2285.  
  2286.  
  2287.         BITWISE LOGICAL FUNCTIONS
  2288.  
  2289.         (logand <expr>...)  THE BITWISE AND OF A LIST OF NUMBERS
  2290.             <expr>      the numbers
  2291.             returns     the result of the and operation
  2292.  
  2293.         (logior <expr>...)  THE BITWISE INCLUSIVE OR OF A LIST OF NUMBERS
  2294.             <expr>      the numbers
  2295.             returns     the result of the inclusive or operation
  2296.  
  2297.         (logxor <expr>...)  THE BITWISE EXCLUSIVE OR OF A LIST OF NUMBERS
  2298.             <expr>      the numbers
  2299.             returns     the result of the exclusive or operation
  2300.  
  2301.         (lognot <expr>)  THE BITWISE NOT OF A NUMBER
  2302.             <expr>      the number
  2303.             returns     the bitwise inversion of number
  2304.  
  2305.  
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.  
  2315.  
  2316.  
  2317.  
  2318.  
  2319.  
  2320.  
  2321.  
  2322.  
  2323.  
  2324.  
  2325.  
  2326.  
  2327.  
  2328.  
  2329.  
  2330.  
  2331.  
  2332.  
  2333.  
  2334.  
  2335.  
  2336.  
  2337.  
  2338.  
  2339.  
  2340.  
  2341.  
  2342.  
  2343.  
  2344.  
  2345.  
  2346.  
  2347.  
  2348.  
  2349.  
  2350.  
  2351.  
  2352.  
  2353.         XLISP                 RELATIONAL FUNCTIONS               Page 35
  2354.  
  2355.  
  2356.         RELATIONAL FUNCTIONS
  2357.  
  2358.         The relational functions can be used to compare integers,
  2359.         floating point numbers or strings.
  2360.  
  2361.         (< <e1> <e2>)  TEST FOR LESS THAN
  2362.             <e1>        the left operand of the comparison
  2363.             <e2>        the right operand of the comparison
  2364.             returns     the result of comparing <e1> with <e2>
  2365.  
  2366.         (<= <e1> <e2>)  TEST FOR LESS THAN OR EQUAL TO
  2367.             <e1>        the left operand of the comparison
  2368.             <e2>        the right operand of the comparison
  2369.             returns     the result of comparing <e1> with <e2>
  2370.  
  2371.         (= <e1> <e2>)  TEST FOR EQUAL TO
  2372.             <e1>        the left operand of the comparison
  2373.             <e2>        the right operand of the comparison
  2374.             returns     the result of comparing <e1> with <e2>
  2375.  
  2376.         (/= <e1> <e2>)  TEST FOR NOT EQUAL TO
  2377.             <e1>        the left operand of the comparison
  2378.             <e2>        the right operand of the comparison
  2379.             returns     the result of comparing <e1> with <e2>
  2380.  
  2381.         (>= <e1> <e2>)  TEST FOR GREATER THAN OR EQUAL TO
  2382.             <e1>        the left operand of the comparison
  2383.             <e2>        the right operand of the comparison
  2384.             returns     the result of comparing <e1> with <e2>
  2385.  
  2386.         (> <e1> <e2>)  TEST FOR GREATER THAN
  2387.             <e1>        the left operand of the comparison
  2388.             <e2>        the right operand of the comparison
  2389.             returns     the result of comparing <e1> with <e2>
  2390.  
  2391.  
  2392.  
  2393.  
  2394.  
  2395.  
  2396.  
  2397.  
  2398.  
  2399.  
  2400.  
  2401.  
  2402.  
  2403.  
  2404.  
  2405.  
  2406.  
  2407.  
  2408.  
  2409.  
  2410.  
  2411.  
  2412.  
  2413.  
  2414.  
  2415.  
  2416.  
  2417.  
  2418.  
  2419.  
  2420.  
  2421.  
  2422.         XLISP                   STRING FUNCTIONS                 Page 36
  2423.  
  2424.  
  2425.         STRING FUNCTIONS
  2426.  
  2427.         (char <string> <index>)  EXTRACT A CHARACTER FROM A STRING
  2428.             <string>    the string
  2429.             <index>     the string index (zero relative)
  2430.             returns     the ascii code of the character
  2431.  
  2432.         (string <expr>)  MAKE A STRING FROM AN INTEGER ASCII VALUE
  2433.             <expr>      the integer
  2434.             returns     a one character string
  2435.  
  2436.         (strcat [<expr>]...)  CONCATENATE STRINGS
  2437.             <expr>      the strings to concatenate
  2438.             returns     the result of concatenating the strings
  2439.  
  2440.         (substr <expr> <sexpr> [<lexpr>]) EXTRACT A SUBSTRING
  2441.             <expr>      the string
  2442.             <sexpr>     the starting position
  2443.             <lexpr>     the length (default is rest of string)
  2444.             returns     substring starting at <sexpr> for <lexpr>
  2445.  
  2446.  
  2447.  
  2448.  
  2449.  
  2450.  
  2451.  
  2452.  
  2453.  
  2454.  
  2455.  
  2456.  
  2457.  
  2458.  
  2459.  
  2460.  
  2461.  
  2462.  
  2463.  
  2464.  
  2465.  
  2466.  
  2467.  
  2468.  
  2469.  
  2470.  
  2471.  
  2472.  
  2473.  
  2474.  
  2475.  
  2476.  
  2477.  
  2478.  
  2479.  
  2480.  
  2481.  
  2482.  
  2483.  
  2484.  
  2485.  
  2486.  
  2487.  
  2488.  
  2489.  
  2490.  
  2491.         XLISP                INPUT/OUTPUT FUNCTIONS              Page 37
  2492.  
  2493.  
  2494.         INPUT/OUTPUT FUNCTIONS
  2495.  
  2496.         (read [<source> [<eof> [<rflag>]]])  READ AN XLISP EXPRESSION
  2497.             <source>    the input source (default is standard input)
  2498.             <eof>       the value to return on end of file (default is nil)
  2499.             <rflag>     recursive read flag (default is nil)
  2500.             returns     the expression read
  2501.  
  2502.         (print <expr> [<sink>])  PRINT A LIST OF VALUES ON A NEW LINE
  2503.             <expr>      the expressions to be printed
  2504.             <sink>      the output sink (default is standard output)
  2505.             returns     the expression
  2506.  
  2507.         (prin1 <expr> [<sink>])  PRINT A LIST OF VALUES
  2508.             <expr>      the expressions to be printed
  2509.             <sink>      the output sink (default is standard output)
  2510.             returns     the expression
  2511.  
  2512.         (princ <expr> [<sink>])  PRINT A LIST OF VALUES WITHOUT QUOTING
  2513.             <expr>      the expressions to be printed
  2514.             <sink>      the output sink (default is standard output)
  2515.             returns     the expression
  2516.  
  2517.         (terpri [<sink>])  TERMINATE THE CURRENT PRINT LINE
  2518.             <sink>      the output sink (default is standard output)
  2519.             returns     nil
  2520.  
  2521.         (flatsize <expr>)  LENGTH OF PRINTED REPRESENTATION USING PRIN1
  2522.             <expr>      the expression
  2523.             returns     the length
  2524.  
  2525.         (flatc <expr>)  LENGTH OF PRINTED REPRESENTATION USING PRINC
  2526.             <expr>      the expression
  2527.             returns     the length
  2528.  
  2529.  
  2530.  
  2531.  
  2532.  
  2533.  
  2534.  
  2535.  
  2536.  
  2537.  
  2538.  
  2539.  
  2540.  
  2541.  
  2542.  
  2543.  
  2544.  
  2545.  
  2546.  
  2547.  
  2548.  
  2549.  
  2550.  
  2551.  
  2552.  
  2553.  
  2554.  
  2555.  
  2556.  
  2557.  
  2558.  
  2559.  
  2560.         XLISP                  FILE I/O FUNCTIONS                Page 38
  2561.  
  2562.  
  2563.         FILE I/O FUNCTIONS
  2564.  
  2565.         (openi <fname>)  OPEN AN INPUT FILE
  2566.             <fname>     the file name string or symbol
  2567.             returns     a file pointer
  2568.  
  2569.         (openo <fname>)  OPEN AN OUTPUT FILE
  2570.             <fname>     the file name string or symbol
  2571.             returns     a file pointer
  2572.  
  2573.         (close <fp>)  CLOSE A FILE
  2574.             <fp>        the file pointer
  2575.             returns     nil
  2576.  
  2577.         (read-char [<source>])  READ A CHARACTER FROM A FILE OR STREAM
  2578.             <source>    the input source (default is standard input)
  2579.             returns     the character (integer)
  2580.  
  2581.         (peek-char [<flag> [<source>]])  PEEK AT THE NEXT CHARACTER
  2582.             <flag>      flag for skipping white space (default is nil)
  2583.             <source>    the input source (default is standard input)
  2584.             returns     the character (integer)
  2585.  
  2586.         (write-char <ch> [<sink>])  WRITE A CHARACTER TO A FILE OR STREAM
  2587.             <ch>        the character to put (integer)
  2588.             <sink>      the output sink (default is standard output)
  2589.             returns     the character (integer)
  2590.  
  2591.         (read-line [<source>])  READ A LINE FROM A FILE OR STREAM
  2592.             <source>    the input source (default is standard input)
  2593.             returns     the input string
  2594.  
  2595.  
  2596.  
  2597.  
  2598.  
  2599.  
  2600.  
  2601.  
  2602.  
  2603.  
  2604.  
  2605.  
  2606.  
  2607.  
  2608.  
  2609.  
  2610.  
  2611.  
  2612.  
  2613.  
  2614.  
  2615.  
  2616.  
  2617.  
  2618.  
  2619.  
  2620.  
  2621.  
  2622.  
  2623.  
  2624.  
  2625.  
  2626.  
  2627.  
  2628.  
  2629.         XLISP                   SYSTEM FUNCTIONS                 Page 39
  2630.  
  2631.  
  2632.         SYSTEM FUNCTIONS
  2633.  
  2634.         (load <fname> [<vflag> [<pflag>]])  LOAD AN XLISP SOURCE FILE
  2635.             <fname>     the filename string or symbol
  2636.             <vflag>     the verbose flag (default is t)
  2637.             <pflag>     the print flag (default is nil)
  2638.             returns     the filename
  2639.  
  2640.         (transcript [<fname>])  CREATE A FILE WITH A TRANSCRIPT OF A SESSION
  2641.             <fname>     file name string or symbol
  2642.                         (if missing, close current transcript)
  2643.             returns     t if the transcript is opened, nil if it is closed
  2644.  
  2645.         (gc)  FORCE GARBAGE COLLECTION
  2646.             returns     nil
  2647.  
  2648.         (expand <num>)  EXPAND MEMORY BY ADDING SEGMENTS
  2649.             <num>       the number of segments to add
  2650.             returns     the number of segments added
  2651.  
  2652.         (alloc <num>)  CHANGE NUMBER OF NODES TO ALLOCATE IN EACH SEGMENT
  2653.             <num>       the number of nodes to allocate
  2654.             returns     the old number of nodes to allocate
  2655.  
  2656.         (mem)  SHOW MEMORY ALLOCATION STATISTICS
  2657.             returns     nil
  2658.  
  2659.         (type-of <expr>)  RETURNS THE TYPE OF THE EXPRESSION
  2660.             <expr>      the expression to return the type of
  2661.             returns     nil if the value is nil otherwise one of the symbols:
  2662.                           :SYMBOL for symbols
  2663.                           :OBJECT for objects
  2664.                           :CONS   for conses
  2665.                           :SUBR   for built-ins with evaluated arguments
  2666.                           :FSUBR  for built-ins with unevaluated arguments
  2667.                           :STRING for strings
  2668.                           :FIXNUM for integers
  2669.                           :FLONUM for floating point numbers
  2670.                           :FILE   for file pointers
  2671.                           :ARRAY  for arrays
  2672.  
  2673.         (peek <addrs>)  PEEK AT A LOCATION IN MEMORY
  2674.             <addrs>     the address to peek at (integer)
  2675.             returns     the value at the specified address (integer)
  2676.  
  2677.         (poke <addrs> <value>)  POKE A VALUE INTO MEMORY
  2678.             <addrs>     the address to poke (integer)
  2679.             <value>     the value to poke into the address (integer)
  2680.             returns     the value
  2681.  
  2682.         (address-of <expr>)  GET THE ADDRESS OF AN XLISP NODE
  2683.             <expr>      the node
  2684.             returns     the address of the node (integer)
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.  
  2692.  
  2693.  
  2694.  
  2695.  
  2696.  
  2697.  
  2698.         XLISP                   SYSTEM FUNCTIONS                 Page 40
  2699.  
  2700.  
  2701.         (exit)  EXIT XLISP
  2702.             returns     never returns
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.  
  2711.  
  2712.  
  2713.  
  2714.  
  2715.  
  2716.  
  2717.  
  2718.  
  2719.  
  2720.  
  2721.  
  2722.  
  2723.  
  2724.  
  2725.  
  2726.  
  2727.  
  2728.  
  2729.  
  2730.  
  2731.  
  2732.  
  2733.  
  2734.  
  2735.  
  2736.  
  2737.  
  2738.  
  2739.  
  2740.  
  2741.  
  2742.  
  2743.  
  2744.  
  2745.  
  2746.  
  2747.  
  2748.  
  2749.  
  2750.  
  2751.  
  2752.  
  2753.  
  2754.  
  2755.  
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.  
  2762.  
  2763.  
  2764.  
  2765.  
  2766.  
  2767.         XLISP                       EXAMPLES                     Page 41
  2768.  
  2769.  
  2770.         FILE I/O FUNCTIONS
  2771.  
  2772.         Input from a File
  2773.  
  2774.         XLISP provides two functions for opening files.  To open a file
  2775.         for input, use the OPENI function.  To open a file for output,
  2776.         use the OPENO function.  Both of these functions take a single
  2777.         argument which is the name of the file to be opened.  This name
  2778.         can be in the form of a string or a symbol.  Both open functions
  2779.         return an object of type :FILE as their result if they succeed
  2780.         in opening the specified file.  They return the value NIL if
  2781.         they are not successful.  In order to manipulate the file, it is
  2782.         necessary to save the value returned by the open function.  This
  2783.         is usually done by assigning it to a variable with the SETQ
  2784.         special form or by binding it using LET or LET*.  Here is an
  2785.         example:
  2786.  
  2787.             (setq fp (openi "init.lsp"))
  2788.  
  2789.         Evaluating this expression will result in the file "init.lsp"
  2790.         being opened.  The file object that will be returned by the
  2791.         OPENI function will be assigned to the variable "fp".
  2792.  
  2793.         It is now possible to use the file for input.  To read an
  2794.         expression from the file, just supply the value of the "fp"
  2795.         variable as the optional "stream" argument to READ.
  2796.  
  2797.             (read fp)
  2798.  
  2799.         Evaluating this expression will result in reading the first
  2800.         expression from the file "init.lsp".  The expression will be
  2801.         returned as the result of the READ function.  More expressions
  2802.         can be read from the file using further calls to the READ
  2803.         function.  When there are no more expressions to read, the READ
  2804.         function will return NIL (or whatever value was supplied as the
  2805.         second argument to READ).
  2806.  
  2807.         Once you are done reading from the file, you should close it.
  2808.         To close the file, use the following expression:
  2809.  
  2810.             (close fp)
  2811.  
  2812.         Evaluating this expression will cause the file to be closed.
  2813.  
  2814.  
  2815.  
  2816.  
  2817.  
  2818.  
  2819.  
  2820.  
  2821.  
  2822.  
  2823.  
  2824.  
  2825.  
  2826.  
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.  
  2833.  
  2834.  
  2835.  
  2836.         XLISP                       EXAMPLES                     Page 42
  2837.  
  2838.  
  2839.         Output to a File
  2840.  
  2841.         Writing to a file is pretty much the same as reading from one.
  2842.         You need to open the file first.  This time you should use the
  2843.         OPENO function to indicate that you will do output to the file.
  2844.         For example:
  2845.  
  2846.             (setq fp (openo "test.dat"))
  2847.  
  2848.         Evaluating this expression will open the file "test.dat" for
  2849.         output.  If the file already exists, its current contents will
  2850.         be discarded.  If it doesn't already exist, it will be created.
  2851.         In any case, a :FILE object will be returned by the OPENO
  2852.         function.  This file object will be assigned to the "fp"
  2853.         variable.
  2854.  
  2855.         It is now possible to write to this file by supplying the value
  2856.         of the "fp" variable as the optional "stream" parameter in the
  2857.         PRINT function.
  2858.  
  2859.             (print "Hello there" fp)
  2860.  
  2861.         Evaluating this expression will result in the string "Hello
  2862.         there" being written to the file "test.dat".  More data can be
  2863.         written to the file using a similar technique.
  2864.  
  2865.         Once you are done writing to the file, you should close it.
  2866.         Closing an output file is just like closing an input file.
  2867.  
  2868.             (close fp)
  2869.  
  2870.         Evaluating this expression will close the output file and make
  2871.         it permanent.
  2872.  
  2873.  
  2874.  
  2875.  
  2876.  
  2877.  
  2878.  
  2879.  
  2880.  
  2881.  
  2882.  
  2883.  
  2884.  
  2885.  
  2886.  
  2887.  
  2888.  
  2889.  
  2890.  
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899.  
  2900.  
  2901.  
  2902.  
  2903.  
  2904.  
  2905.         XLISP                       EXAMPLES                     Page 43
  2906.  
  2907.  
  2908.         A Slightly More Complicated File Example
  2909.  
  2910.         This example shows how to open a file, read each Lisp expression
  2911.         from the file and print it.  It demonstrates the use of files
  2912.         and the use of the optional "stream" argument to the READ
  2913.         function.
  2914.  
  2915.             (do* ((fp (openi "test.dat"))
  2916.                   (ex (read fp) (read fp)))
  2917.                  ((null ex) nil)
  2918.               (print ex))
  2919.  
  2920.  
  2921.  
  2922.  
  2923.  
  2924.  
  2925.  
  2926.  
  2927.  
  2928.  
  2929.  
  2930.  
  2931.  
  2932.  
  2933.  
  2934.  
  2935.  
  2936.  
  2937.  
  2938.  
  2939.  
  2940.  
  2941.  
  2942.  
  2943.  
  2944.  
  2945.  
  2946.  
  2947.  
  2948.  
  2949.  
  2950.  
  2951.  
  2952.  
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.  
  2963.  
  2964.  
  2965.  
  2966.  
  2967.  
  2968.