diff options
Diffstat (limited to 'docsrc/xlisp')
416 files changed, 67707 insertions, 0 deletions
diff --git a/docsrc/xlisp/intgen.mss b/docsrc/xlisp/intgen.mss new file mode 100644 index 0000000..dcd009d --- /dev/null +++ b/docsrc/xlisp/intgen.mss @@ -0,0 +1,241 @@ +This documentation describes Intgen, a program for generating XLISP to C +interfaces. Intgen works by scanning @code(.h) files with special comments in +them. Intgen builds stubs that implement XLISP SUBR's. When the SUBR is +called, arguments are type-checked and passed to the C routine declared in +the @code(.h) file. Results are converted into the appropriate XLISP type and +returned to the calling XLISP function. Intgen lets you add C functions +into the XLISP environment with very little effort. + +The interface generator will take as command-line input: +@begin(itemize) +the name of the @code(.c) file to generate (do not include the @code(.c) extension; e.g. write +@code(xlexten), not @code(xlexten.c)); + +a list of @code(.h) files. +@end(itemize) +Alternatively, the command line may specify a command file from which to read file names. The command file name should be preceded by "@@", for example: +@begin(example) +intgen @@sndfns.cl +@end(example) +reads sndfns.cl to get the command-line input. Only one level of indirection is allowed. + +The output is: +@begin(itemize) +a single @code(.c) file with one SUBR defined for each designated +routine in a @code(.h) file. + +a @code(.h) file that declares each new C routine. E.g. if the @code(.c) file is named @code(xlexten.c), this file will be named @code(xlextendefs.h); + +a @code(.h) file that extends the SUBR table used by Xlisp. E.g. if the @code(.c) file is named @code(xlexten.c), then this file is named @code(xlextenptrs.h); + +a @code(.lsp) file with lisp initialization expressions copied from the +@code(.h) +files. This file is only generated if at least one initialization expression is encountered. +@end(itemize) + +For example, the command line +@begin(example) +intgen seint ~setypes.h access.h +@end(example) +generates the file @code(seint.c), using declarations in @code(setypes.h) +and @code(access.h). Normally, the @code(.h) files are included by the +generated file using @code(#include) commands. A @code(~) before a file +means do not include the @code(.h) file. (This may be useful if you extend +@code(xlisp.h), which will be included anyway). Also generated will be +@code(setintdefs.h) and @code(seintptrs.h). + +@subsection(Extending Xlisp)@index(Extending Xlisp) +Any number of @code(.h) files may be named on the command line to Intgen, +and Intgen will make a single @code(.c) file with interface routines for all +of the @code(.h) files. On the other hand, it is not necessary to put all +of the extensions to Xlisp into a single interface file. For example, you +can run Intgen once to build interfaces to window manager routines, and +again to build interfaces to a new data type. Both interfaces can be linked +into Xlisp. + +To use the generated files, you must compile the @code(.c) files and link +them with all of the standard Xlisp object files. In addition, you must +edit the file @code(localdefs.h) to contain an @code(#include) for each +@code(*defs.h) file, and edit the file @code(localptrs.h) to include each +@code(*ptrs.h) file. For example, suppose you run Intgen to build +@code(soundint.c), @code(fugueint.c), and @code(tableint.c). You would then +edit @code(localdefs.h) to contain the following: +@begin(example) +#include "soundintdefs.h" +#include "fugueintdefs.h" +#include "tableintdefs.h" +@end(example) +and edit @code(localptrs.h) to contain: +@begin(example) +#include "soundintptrs.h" +#include "fugueintptrs.h" +#include "tableintptrs.h" +@end(example) +These @code(localdefs.h) and @code(localptrs.h) files are in turn included +by @code(xlftab.c) which is where Xlisp builds a table of SUBRs. + +To summarize, building an interface requires just a few simple steps: +@begin(itemize) +Write C code to be called by Xlisp interface routines. This C code does the +real work, and in most cases is completely independent of Xlisp. + +Add comments to @code(.h) files to tell Intgen which routines to build +interfaces to, and to specify the types of the arguments. + +Run Intgen to build interface routines. + +Edit @code(localptrs.h) and @code(localdefs.h) to include generated +@code(.h) files. + +Compile and link Xlisp, including the new C code. +@end(itemize) + +@section(Header file format)@index(Header file format) + +Each routine to be interfaced with Xlisp must be declared as +follows: +@begin(example) +@i(type-name) @i(routine-name)(); /* LISP: (@i(func-name) @i(type@-(1)) @i(type@-(2)) ...) */ +@end(example) +The comment may be on the line following the declaration, but the +declaration and the comment must each be on no more than one line. +The characters @code(LISP:) at the beginning of the comment mark routines +to put in the interface. The comment also gives the +type and number of arguments. The function, when accessed from lisp will +be known as @I(func-name), which need not bear any relationship to +@i(routine-name). By convention, underscores in the C @i(routine-name) +should be converted to dashes in @i(func-name), and @i(func-name) should be in +all capitals. None of this is enforced or automated though. + +Legal type_names are: +@begin(description) +@code(LVAL)@\returns an Xlisp datum. + +@code(atom_type)@\equivalent to @code(LVAL), but the result is expected to +be an atom. + +@code(value_type)@\a value as used in Dannenberg's score editor. + +@code(event_type)@\an event as used in Dannenberg's score editor. + +@code(int)@\interface will convert int to Xlisp @code(FIXNUM). + +@code(boolean)@\interface will convert int to @code( T) or @code(nil). + +@code(float) or @code(double)@\interface converts to @code(FLONUM). + +@code(char *) or @code(string) or @code(string_type)@\interface converts to @code(STRING). The result string will be copied into the XLISP heap. + + void@\interface will return @code(nil). +@end(description) + +It is easy to extend this list. Any unrecognized type will +be coerced to an @code(int) and then returned as a @code(FIXNUM), and a warning will be +issued. + +The ``@code(*)'' after char must be followed by @i(routine-name) with +no intervening space. + +Parameter types may be any of the following: +@begin(description) +@code(FIXNUM)@\C routine expects an int. + +@code(FLONUM) or @code(FLOAT)@\C routine expects a @code(double). + +@code(STRING)@\C routine expects @code(char *), the string is not copied. + +@code(VALUE)@\C routine expects a @code(value_type). (Not applicable to Fugue.) + +@code(EVENT)@\C routine expects an @code(event_type). (Not applicable to Fugue.) + +@code(ANY)@\C routine expects @code(LVAL). + +@code(ATOM)@\C routine expects @code(LVAL) which is a lisp atom. + +@code(FILE)@\C routine expects @code(FILE *). + +@code(SOUND)@\C routine expects a @code(SoundPtr). + +@end(description) +Any of these may be followed by ``@code(*)'': @code(FIXNUM*), @code(FLONUM*), @code(STRING*), @code(ANY*), @code(FILE*), +indicating C routine expects @code(int *), @code(double *), @code(char **), @code(LVAL *), or @code(FILE **) . +This is basically a mechanism for returning more than one value, @i(not) +a mechanism for clobbering XLisp values. In this spirit, the interface +copies the value (an @code(int), @code(double), @code(char *), @code(LVAL), or @code(FILE *)) to a local variable +and passes the address of that variable to the C routine. On return, +a list of resulting ``@code(*)'' parameters is constructed and bound to the +global XLisp symbol @code(*RSLT*@index(*RSLT*)). (Strings are copied.) If the C routine is void, then the result list is also returned by the corresponding XLisp function. + +Note 1: this does not support C routines like strcpy that modify strings, +because the C routine gets a pointer to the string in the XLisp heap. +However, you can always add an intermediate routine that allocates +space and then calls @code(strcpy), or whatever. + +Note 2: it follows that a new XLisp @code(STRING) will be created for each @code(STRING*) parameter. + +Note 3: putting results on a (global!) symbol seems a bit unstructured, but note that one could write a multiple-value binding macro that hides this ugliness from the user if desired. In practice, I find that pulling the extra result values from @code(*RSLT*) when needed is perfectly acceptable. + +For parameters that are result values only, the character ``@code(^)'' may +be substituted for ``@code(*)''. In this case, the parameter is @i(not) to be passed in the XLisp calling site. +However, the address of an initialized +local variable of the given type is passed to the corresponding +C function, and the resulting value is passed back through @code(*RSLT*) as +ordinary result parameter as described above. +The local variables are initialized to zero or @code(NULL). + +@section(Using #define'd macros)@index(#define'd macros) +If a comment of the form: +@begin(example) +/* LISP: @i(type-name) (@i(routine-name-2) @i(type-1) @i(type-2) ...) */ +@end(example) +appears on a line by itself and there was a @code(#define) on the previous +line, then the preceding @code(#define) is treated as a C routine, e.g. +@begin(example) +#define leftshift(val, count) ((val) << (count)) +/* LISP: int (LOGSHIFT INT INT) */ +@end(example) +will implement the LeLisp function @code(LOGSHIFT). + +The @i(type-name) following ``@code(LISP:)'' should have no spaces, e.g. use @code(ANY*), not +@code(ANY *). + +@section(Lisp Include Files)@index(Lisp Include Files) +Include files often define constants that we would like to have around +in the Lisp world, but which are easier to initialize just by loading +a text file. Therefore, a comment of the form: +@begin(example) +/* LISP-SRC: (any lisp expression) */ +@end(example) +will cause Intgen to open a file @i(name)@code(.lsp) and append +@begin(example) +(any lisp expression) +@end(example) +to @i(name)@code(.lsp), where @i(name) is the interface name passed on the command line. If none of the include files examined have comments of +this form, then no @i(name)@code(.lsp) file is generated. +@p(Note:) @i(the LISP-SRC comment must be on a new line.) + +@section(Example) +This file was used for testing Intgen. It uses a trick (ok, it's a hack) to interface +to a standard library macro (tolower). Since tolower is already +defined, the macro ToLower is defined just to give Intgen a name +to call. Two other routines, strlen and tough, are interfaced as +well. +@begin(example) +/* igtest.h -- test interface for intgen */ + +#define ToLower(c) tolower(c) +/* LISP: int (TOLOWER FIXNUM) */ + +int strlen(); /* LISP: (STRLEN STRING) */ + +void tough(); + /* LISP: (TOUGH FIXNUM* FLONUM* STRING ANY FIXNUM) */ +@end(example) + +@section(More Details) + +Intgen has some compiler switches to enable/disable the use of certain types, including +@code(VALUE) and @code(EVENT) types used by Dannenberg's score editing work, the @code(SOUND) type used by Fugue, and @code(DEXT) and @code(SEXT) types added for Dale Amon. +Enabling all of these is not likely to cause problems, +and the chances of an accidental use of these types getting through +the compiler and linker seems very small. diff --git a/docsrc/xlisp/xlisp-doc/README b/docsrc/xlisp/xlisp-doc/README new file mode 100644 index 0000000..d1249c9 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/README @@ -0,0 +1,11 @@ +January 11, 2011 + +The XLISP dos in this directory still in an unfinished state. +The hyperlinking works, but many pages are still too messy. + +Just load "start.htm" into your web browser, everything else +is linked from there. + +In case of doubt write to: + +edgar-rft@web.de diff --git a/docsrc/xlisp/xlisp-doc/examples/apropos.htm b/docsrc/xlisp/xlisp-doc/examples/apropos.htm new file mode 100644 index 0000000..f0657b2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/apropos.htm @@ -0,0 +1,268 @@ +<html><head>
+
+<title>apropos</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>apropos</h1>
+
+<hr>
+
+
+
+<p><div class="box">
+
+<dl>
+
+<dt><p><nobr>(<b>apropos</b> &optional <i>pattern type</i>)</nobr></p></dt>
+
+<dd><p>The 'apropos' function searches the Nyquist/XLISP *obarray* for
+matching symbol names containing 'pattern' and being of 'type'. <nobr>It
+prints</nobr> a list of the results in alphabetical order.</p>
+
+<p>'pattern and 'type' can be given as symbols or strings. <nobr>If
+no</nobr> 'pattern' is given, all symbol names are considered as matching.
+<nobr>If no</nobr> 'type' is given, all symbol types are considered as
+matching. With 'type', only the first letter is important. <nobr>A
+type</nobr> of 'f' searches for symbols with a valid function value, while a
+type of 'v' searches for symbols with a valid variable value.</p></dd>
+
+</dd>
+
+</dl>
+
+</div></p>
+
+<p>Examples:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(apropos)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%"><nobr>all symbols known by Nyquist</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(apropos nil 'f)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%"><nobr>all bound functions known by Nyquist</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(apropos nil 'v)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%"><nobr>all bound variables known by Nyquist</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(apropos 'snd 'f)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%"><nobr>all function names containing 'snd'</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>A method to introspect classes and objects:</p>
+
+<pre class="example">
+(setq instance-var '*wrong-variable*) ; value outside the object
+
+(setq my-class (send class :new '(instance-var))) ; class with instance variable
+(send my-class :answer :isnew '() '((setq instance-var '*OK*))) ; value inside an object
+(send my-class :answer :eval '(list) '((eval list))) ; evaluation method
+
+(setq my-object (send my-class :new)) ; instance of my-class
+(send my-object :eval 'instance-var) => <font color="#008844">*OK*</font>
+(send my-object :eval '(apropos 'instance-var 'v t)) => <font color="#AA0000">*WRONG-VARIABLE*</font>
+</pre>
+
+<p>The first version works because the call to 'eval' happens inside the
+object:</p>
+
+<pre class="example">
+(send my-class :answer :eval '(list) '((eval list))) => <font color="#008844">*OK*</font>
+</pre>
+
+<p>The second version doesn't work because the call to 'eval' happens
+outside the object:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">external-function</font> (list)
+ (eval list))
+
+(send my-class :answer :eval '(list) '((external-function list))) => <font color="#AA0000">*WRONG-VARIABLE*</font>
+</pre>
+
+<p>The call to 'apropos' doesn't work because 'apropos' is executed outside
+the object:</p>
+
+<pre class="example">
+(send my-object :eval '(apropos)) => <font color="#AA0000">*WRONG-VARIABLE*</font>
+</pre>
+
+<p>The trick is to pass the Lisp code of 'apropos' as a list into the inside
+of the object and 'apply' it there to the arguments:</p>
+
+<pre class="example">
+(send my-class :answer :apropos '(args)
+ '((apply (get-lambda-expression #'apropos) args)))
+
+(send my-object :apropos '(instance-var v t)) => <font color="#008844">*OK*</font>
+</pre>
+
+<p>But this only works if all function that need access to internal instance
+or class variables are executed inside the object. For example, if 'apropos'
+calls a function that needs access to an internal instance variable, I
+would get a 'unbound variable' error.</p>
+
+<p>Here is the code of the 'apropos' function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">apropos</font> (&optional pattern type)
+ (let (result-list (<font color="#AA5500">*gc-flag*</font> nil))
+ <font color="#008844">;; make sure 'pattern' is a string, either empty or upper-case</font>
+ (if pattern
+ (setf pattern (string-upcase (string pattern)))
+ (setf pattern <font color="#880000">""</font>))
+ <font color="#008844">;; take only the first letter of 'type' and make it an upper-case string</font>
+ (if type (setf type (string-upcase (subseq (string type) 0 1))))
+ <font color="#008844">;; go through all entries in the *obarray* symbol hash table</font>
+ (dotimes (i (length <font color="#AA5500">*obarray*</font>))
+ (let ((entry (aref <font color="#AA5500">*obarray*</font> i))) <font color="#008844">; *obarray* is an array of lists</font>
+ <font color="#008844">;; if the *obarray* entry is not an empty list</font>
+ (if entry
+ <font color="#008844">;; go through all elements of the *obarray* entry list</font>
+ <font color="#008844">;; do not use 'dolist' because *obarray* contains *unbound*</font>
+ (dotimes (j (length entry))
+ <font color="#008844">;; convert the symbol to a string to enable pattern matching</font>
+ (let ((string (string (nth j entry))))
+ <font color="#008844">;; if the symbol string matches the search pattern</font>
+ (if (string-search pattern string)
+ <font color="#008844">;; if a special symbol type to search for was given</font>
+ (if type
+ <font color="#008844">;; if a 'type' search was initiated and the current</font>
+ <font color="#008844">;; symbol has no 'type' value bound to it, do nothing</font>
+ <font color="#008844">;; and return from 'cond' without adding the symbol</font>
+ <font color="#008844">;; string to the result list</font>
+ (cond ((and (string= type <font color="#880000">"F"</font>) <font color="#008844">; bound functions only</font>
+ (not (fboundp (nth j entry))))
+ nil)
+ ((and (string= type <font color="#880000">"V"</font>) <font color="#008844">; bound variables only</font>
+ (not (boundp (nth j entry))))
+ nil)
+ <font color="#008844">;; if the symbol has passed all tests,</font>
+ <font color="#008844">;; add the symbol string to the result list</font>
+ (t (setf result-list (cons string result-list))))
+ <font color="#008844">;; if no special symbol type to search for had been given,</font>
+ <font color="#008844">;; but the symbol string had matched the search pattern,</font>
+ <font color="#008844">;; add the symbol string to the result list</font>
+ (setf result-list (cons string result-list)))))))))
+ <font color="#008844">;; if the result list contains more than one element</font>
+ <font color="#008844">;; make it become an alphabetically sorted list</font>
+ (if (> (length result-list) 1)
+ (setf result-list (sort result-list 'string<)))
+ <font color="#008844">;; print a message according to the search type and pattern</font>
+ (cond ((and type (string= type <font color="#880000">"F"</font>)) (setf type <font color="#880000">"function"</font>))
+ ((and type (string= type <font color="#880000">"V"</font>)) (setf type <font color="#880000">"variable"</font>))
+ (t (setf type <font color="#880000">"symbol"</font>)))
+ (if (string= pattern <font color="#880000">""</font>)
+ (format t <font color="#880000">"All ~a names known by Nyquist:~%"</font> type)
+ (format t <font color="#880000">"All ~a names containing pattern ~a:~%"</font> type pattern))
+ <font color="#008844">;; print the search results</font>
+ (cond (result-list
+ (let ((list-length (length result-list)))
+ (format t <font color="#880000">";; number of symbols: ~a~%"</font> list-length)
+ (dolist (i result-list) (format t <font color="#880000">"~a~%"</font> i))
+ (if (> list-length 20)
+ (format t <font color="#880000">";; number of symbols: ~a~%"</font> list-length))))
+ (t (format t <font color="#880000">"No matches found."</font>)))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/arrays.htm b/docsrc/xlisp/xlisp-doc/examples/arrays.htm new file mode 100644 index 0000000..6e258ff --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/arrays.htm @@ -0,0 +1,430 @@ +<html><head>
+
+<title>Arrays</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Arrays</h1>
+
+<hr>
+
+<p>Arrays are also <a href="sequences.htm">Sequences</a>.</p>
+
+<ul>
+<li><nobr><a href="#make-array-star">make-array*</a> - create multi-dimensional arrays</nobr></li>
+<li><nobr><a href="#aref-star">aref*</a> - access multi-dimensional-arrays</nobr></li>
+<li><nobr><a href="#vector-star">vector*</a> - make a one-dimensional array out of arbitrary Lisp expressions</nobr></li>
+<li><nobr><a href="#vector-star">array*</a> - make a multi-dimensional array out of arbitrary Lisp expressions</nobr></li>
+</ul>
+
+<a name="make-array-star"></a>
+
+<hr>
+
+<h2>make-array*</h2>
+
+<hr>
+
+<p>XLISP already has the
+<nobr><a href="../reference/make-array.htm">make-array</a></nobr>
+function to create <nobr>one-dimensional</nobr> arrays:</p>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<a href="../reference/make-array.htm">make-array</a> <i>size</i>)</nobr></dt>
+<dd><i>size</i> - the size [integer] of the array to be created<br>
+returns - the new array</dd>
+</dl>
+
+</div></p>
+
+<p>Here is a function to create <nobr>multi-dimensional</nobr> arrays:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>make-array*</b> <i>size-1</i> [<i>size-2</i> ...])</dt>
+<dd><i>sizeN</i> - the size [integer] of the <i>N</i>-th dimension in the array to be created<br>
+returns - the new array</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">make-array*</font> (&rest dimensions-list)
+ (cond ((null dimensions-list)
+ (error <font color="#880000">"too few arguments"</font>))
+ ((and (null (rest dimensions-list))
+ (eql 0 (first dimensions-list)))
+ (make-array 0))
+ (t (labels ((multi-vector (dimensions-list)
+ (let ((count (first dimensions-list)))
+ (if (not (and (integerp count) (plusp count)))
+ (error <font color="#880000">"not a positive integer"</font> count)
+ (let ((rest (rest dimensions-list))
+ (elements-list nil))
+ (dotimes (i count)
+ (push (when rest
+ (multi-vector rest))
+ elements-list))
+ (apply #'vector (reverse elements-list)))))))
+ (multi-vector dimensions-list)))))
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+(make-array* 2 3) => #(#(NIL NIL NIL) #(NIL NIL NIL)))
+(make-array* 2 2 1) => #(#(#(NIL) #(NIL)) #(#(NIL) #(NIL)))
+</pre>
+
+<p>Like <nobr><a href="../reference/make-array.htm">make-array</a></nobr> it
+is possible to create <nobr>one-dimensional</nobr> arrays with zero
+elements:</p>
+
+<pre class="example">
+(make-array* 0) => #()
+(make-array 0) => #()
+</pre>
+
+<p>But it is not allowed to create <nobr>multi-dimensional</nobr> arrays
+with <nobr>zero-size</nobr> dimensions:</p>
+
+<pre class="example">
+(make-array* 1 0 1) => <font color="#AA0000">error: not a positive integer - 0</font>
+</pre>
+
+<p><b>Rationale:</b> Multi-dimensional arrays are implemented as nested
+vectors and a <nobr>zero-element</nobr> vector cannot hold the vector for
+the subsequent dimension. <nobr>We would</nobr> need some additional
+administration overhead to keep the subsequent dimensions accessible, but
+this would break the compatibility to the <nobr>build-in</nobr> XLISP
+<a href="../reference/aref.htm">aref</a> function.</p>
+
+<p>More practical examples see 'aref*' below.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="aref-star"></a>
+
+<hr>
+
+<h2>aref*</h2>
+
+<hr>
+
+<p>XLISP already has the <a href="../reference/aref.htm">aref</a> function
+to access elements in one-dimensional arrays:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<a href="../reference/aref.htm">aref</a> <i>array dimension-1</i>)</dt>
+<dd><i>array</i> - one-dimensional array<br>
+<i>dimension-1</i> - element number in the first dimension<br>
+returns - the value of the array element</dd>
+</dl>
+
+</div></p>
+
+<p>Here is a macro for accessing elements in <nobr>multi-dimensional</nobr>
+arrays:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>aref*</b> <i>array dimension-1</i> [<i>dimension-2</i> ...])</dt>
+<dd><i>array</i> - any-dimensional array<br>
+<i>dimensionN</i> - element number in the <i>N</i>-th dimension<br>
+returns - the value of the array element</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">aref*</font> (array &rest index-list)
+ (labels ((multi-aref (array-name index-list)
+ (let ((index (first index-list)))
+ (if (not (integerp index))
+ (error <font color="#880000">"not an integer"</font> index)
+ (let ((rest (rest index-list))
+ (expansion-list (list 'aref)))
+ (push (if rest
+ (multi-aref array-name rest)
+ array-name)
+ expansion-list)
+ (push index expansion-list)
+ (reverse expansion-list))))))
+ (multi-aref `,array (reverse `,index-list))))
+</pre>
+
+<p>The symbols inside the <a href="../reference/labels.htm">labels</a> form
+do not leak into the expansion, so 'aref*' also works with array names like
+'array', '<nobr>array-name</nobr>' 'index', '<nobr>index-list</nobr>' or
+'<nobr>expansion-list</nobr>'. Also the values of local or global variables
+with these names are not changed.</p>
+
+<pre class="example">
+(macroexpand-1 '(aref* a 1 2 3)) => (aref (aref (aref a 1) 2) 3)
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+> (setq a (make-array* 2 3))
+#(#(NIL NIL NIL) #(NIL NIL NIL)))
+
+> (setf (aref* a 0 1) "hello")
+"hello"
+
+> a
+#(#(NIL "hello" NIL) #(NIL NIL NIL))
+
+> (aref* a 0 1)
+"hello"
+</pre>
+
+<p>'aref*' with only one 'dimension' argument behaves
+<nobr>like <a href="../reference/aref.htm">aref</a>:</nobr></p>
+
+<pre class="example">
+(aref* a 0) => #(NIL "hello" NIL)
+(aref a 0) => #(NIL "hello" NIL)
+
+(aref* (aref* a 0) 1) => "hello"
+(aref (aref a 0) 1) => "hello"
+
+(aref* a 0 1) => "hello"
+(aref a 0 1) => <font color="#AA0000">error: too many arguments</font>
+</pre>
+
+<p>'aref*' like <a href="../reference/aref.htm">aref</a> also works
+<nobr>with <a href="../reference/setf.htm">setf</a></nobr> to store
+values in <nobr>multi-dimensional</nobr> arrays:</p>
+
+<pre class="example">
+(setf (aref* (aref* a 0) 1) "1") => "1" <font color="#008844">; a => #(#(NIL "1" NIL) #(NIL NIL NIL)))</font>
+(setf (aref (aref a 0) 1) "2") => "2" <font color="#008844">; a => #(#(NIL "2" NIL) #(NIL NIL NIL)))</font>
+
+(setf (aref* 0 1) "3") => "3" <font color="#008844">; a => #(#(NIL "3" NIL) #(NIL NIL NIL)))</font>
+(setf (aref 0 1) "4") => <font color="#AA0000">error: too many arguments</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="vector-star"></a>
+
+<hr>
+
+<h2>vector*</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">vector*</font> (&rest items)
+ (if (null items)
+ (make-array 0)
+ (let* ((end (length items))
+ (result (make-array end)))
+ (if (> end 1)
+ (dotimes (index end) <font color="#008844">; more than one item</font>
+ (setf (aref result index)
+ (if (eq (nth index items) '*unbound*)
+ '*unbound*
+ (nth index items))))
+ (if (eq (first items) '*unbound*) <font color="#008844">; one item only</font>
+ (setf (aref result 0) '*unbound*)
+ (let ((item (first items)))
+ (case (type-of item)
+ (cons (let ((end (length item)))
+ (setq result (make-array end))
+ (dotimes (index end)
+ (setf (aref result index)
+ (if (eq (nth index item) '*unbound*)
+ '*unbound*
+ (nth index item))))))
+ (array (let ((end (length item)))
+ (setq result (make-array end))
+ (dotimes (index end)
+ (setf (aref result index)
+ (if (eq (aref item index) '*unbound*)
+ '*unbound*
+ (aref item index))))))
+ (string (let ((end (length item)))
+ (setq result (make-array end))
+ (dotimes (index end)
+ (setf (aref result index)
+ (char item index)))))
+ (t (setf (aref result 0) item))))))
+ result)))
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">list*</font> (&rest items)
+ (if (null items)
+ nil
+ (let* ((end (length items))
+ (result nil))
+ (labels ((push-element (element)
+ (if (member (type-of element) '(array cons string))
+ (setq result (append (reverse (list* element)) result))
+ (push element result))))
+ (dotimes (index end)
+ (if (eq (nth index items) '*unbound*)
+ (push '*unbound* result)
+ (let ((item (nth index items)))
+ (case (type-of item)
+ (nil (push item result))
+ (cons (let ((end (length item)))
+ (when (not (consp (last item))) (incf end))
+ (dotimes (index end)
+ (if (eq (nth index item) '*unbound*)
+ (push '*unbound* result)
+ (push-element (nth index item))))))
+ (array (let ((end (length item)))
+ (dotimes (index end)
+ (if (eq (aref item index) '*unbound*)
+ (push '*unbound* result)
+ (push-element (aref item index))))))
+ (string (let ((end (length item)))
+ (dotimes (index end)
+ (push (char item index) result))))
+ (t (push item result))))))
+ (reverse result)))))
+</pre>
+
+
+<pre class="example">
+(defun <font color="#0000CC">tree*</font> (&rest items)
+ (if (null items)
+ nil
+ (let* ((end (length items))
+ (result nil))
+ (labels ((push-element (element)
+ (if (member (type-of element) '(array cons string))
+ (push (reverse (list* element)) result)
+ (push element result))))
+ (dotimes (index end)
+ (if (eq (nth index items) '*unbound*)
+ (push '*unbound* result)
+ (let ((item (nth index items)))
+ (case (type-of item)
+ (nil (push item result))
+ (cons (let ((end (length item)))
+ (when (not (consp (last item))) (incf end))
+ (dotimes (index end)
+ (if (eq (nth index item) '*unbound*)
+ (push '*unbound* result)
+ (push-element (nth index item))))))
+ (array (let ((end (length item)))
+ (dotimes (index end)
+ (if (eq (aref item index) '*unbound*)
+ (push '*unbound* result)
+ (push-element (aref item index))))))
+ (string (let ((end (length item)))
+ (dotimes (index end)
+ (push (char item index) result))))
+ (t (push item result))))))
+ (reverse result)))))
+</pre>
+
+
+
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="array-star"></a>
+
+<hr>
+
+<h2>array*</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">array*</font> (&rest items)
+ (if (null items)
+ (make-array 0)
+ (let* ((end (length items))
+ (result (make-array end)))
+ (labels ((vector-element (element index)
+ (setf (aref result index)
+ (if (member (type-of element) '(cons string array))
+ (array* element)
+ element))))
+ (dotimes (index end)
+ (if (eq (nth index items) '*unbound*)
+ (setf (aref result index) '*unbound*)
+ (let ((item (nth index items)))
+ (case (type-of item)
+ (cons (let ((end (length item)))
+ (dotimes (index end)
+ (if (eq (nth index item) '*unbound*)
+ (strcat-element <font color="#880000">"*UNBOUND*"</font>)
+ (strcat-element (nth index item))))))
+ (array (let ((end (length item)))
+ (dotimes (index end)
+ (if (eq (aref item index) '*unbound*)
+ (strcat-element <font color="#880000">"*UNBOUND*"</font>)
+ (strcat-element (aref item index))))))
+ (t (strcat-element item))))))
+ result))))
+</pre>
+
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/binary.htm b/docsrc/xlisp/xlisp-doc/examples/binary.htm new file mode 100644 index 0000000..3ae5d56 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/binary.htm @@ -0,0 +1,160 @@ +<html><head>
+
+<title>Binary Integer Numbers</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Binary Integer Numbers</h1>
+
+<hr>
+
+<p>XLISP provides the <a href="../manual/xlisp.htm#binary">#b</a>
+<nobr>read-macro</nobr> for binary numbers:</p>
+
+<pre class="example">
+#b0 => 0 #b1000 => 8 #b100000 => 16
+#b1 => 1 #b1001 => 9 #b100001 => 17
+#b10 => 2 #b1010 => 10 #b100010 => 18
+#b11 => 3 #b1011 => 11 #b100011 => 19
+#b100 => 4 #b1100 => 12 #b100100 => 20
+#b101 => 5 #b1101 => 13 #b100101 => 21
+#b110 => 6 #b1110 => 14 #b100110 => 22
+#b111 => 7 #b1111 => 15 #b100111 => 23
+</pre>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>bin-string</b> <i>integer</i> [<i>all</i>])</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>all</i> - a boolean expression<br>
+returns - the <i>integer</i> in binary form as string</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">bin-string</font> (integer &optional all)
+ (if (integerp integer)
+ (let ((digits (or (dolist (bits '(16 32 64 128) nil)
+ (let ((fixnum (round (expt 2.0 (1- bits)))))
+ (and (plusp (1- fixnum))
+ (minusp fixnum)
+ (return bits))))
+ (error <font color="#880000">"integer limit not found"</font>)))
+ (string <font color="#880000">""</font>))
+ (dotimes (x digits)
+ (let ((digit (logand (round (expt 2.0 x)) integer)))
+ (setq string (strcat (if (zerop digit) <font color="#880000">"0" "1"</font>) string))))
+ (format nil <font color="#880000">"~a"</font> (if all string (string-left-trim <font color="#880000">"0"</font> string))))
+ (error <font color="#880000">"not an integer"</font> integer)))
+</pre>
+
+<p>The '<nobr>bin-string</nobr>' function converts the 'integer' argument
+into binary form and returns is as a string. <nobr>If the</nobr>
+optional 'all' argument is not given or
+<a href="../reference/nil.htm">NIL</a>, leading zeros are not included in
+the string. <nobr>If the</nobr> optional 'all' argument is
+<nobr>non-<a href="../reference/nil.htm">NIL</a></nobr>, all digits of the
+internal representation of the 'integer' argument, including leading zeros,
+are contained in the string. This is useful for debugging integer overflow
+and <nobr>bit-wise</nobr> functions.</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>bin</b> <i>integer</i> [<i>all</i>])</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>all</i> - a boolean expression<br>
+prints - the <i>integer</i> in binary form<br>
+returns - the <i>integer</i> argument</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">bin</font> (integer &optional all)
+ (if (integerp integer)
+ (format t <font color="#880000">"#b~a~%"</font> (bin-string integer all))
+ (format t <font color="#880000">";; not an integer~%"</font>))
+ integer)
+</pre>
+
+<p>The 'bin' function prints the 'integer' argument in binary form on
+the screen. Together with the
+<a href="../manual/xlisp.htm#binary">#b</a> <nobr>read-macro</nobr>
+this can be used for interactive binary computations.</p>
+
+<pre class="example">
+> (bin 12345678)
+#b101111000110000101001110
+12345678
+
+> (bin 12345678 :all)
+#b00000000101111000110000101001110
+12345678
+
+> (bin 1.2345678)
+;; not an integer
+1.2345678
+
+> (bin (logand #b1011 #b1101))
+#b1001
+9
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/circular-lists.htm b/docsrc/xlisp/xlisp-doc/examples/circular-lists.htm new file mode 100644 index 0000000..48d7cdf --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/circular-lists.htm @@ -0,0 +1,133 @@ +<html><head>
+
+<title>Circular Lists</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Circular Lists</h1>
+
+<hr>
+
+
+<hr>
+
+<h2>Known XLISP Problems with Circular Lists</h2>
+
+<hr>
+
+<p><b>Warning:</b> do <b>not</b> try this with XLISP:</p>
+
+<pre class="example">
+> (setq my-list (cons 'item nil)) <font color="#008844">; create a 1-item list</font>
+(ITEM)
+
+> (setf (cdr my-list) my-list)) <font color="#008844">; create the circle</font>
+ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM
+ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM
+ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM
+ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ...
+</pre>
+
+<p>If you're lucky you can <a href="../reference/break.htm">break</a> the
+loop. <nobr>If not</nobr>, then XLISP will print the ITEM forever.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="circular-nth"></a>
+
+<hr>
+
+<h2>c-nth</h2>
+
+<hr>
+
+<p>The '<nobr>c-nth</nobr>' macro accesses a linear list as if it were
+circular:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">c-nth</font> (index list)
+ `(nth ,(rem index (length list)) ,list))
+</pre>
+
+<p>Note that with every call to '<nobr>c-nth</nobr>', the length of the list
+will be computed again.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(c-nth 0 '(1 2 3)) => 1
+(c-nth 1 '(1 2 3)) => 2
+(c-nth 2 '(1 2 3)) => 3
+(c-nth 3 '(1 2 3)) => 1
+(c-nth 4 '(1 2 3)) => 2
+(c-nth 5 '(1 2 3)) => 3
+(c-nth 6 '(1 2 3)) => 1
+(c-nth 7 '(1 2 3)) => 2
+</pre>
+
+Because '<nobr>c-nth</nobr>' is a macro expanding into a regular
+<a href="../reference/nth.htm">nth</a> form, '<nobr>c-nth</nobr>' can be
+used <nobr>with <a href="../reference/setf.htm">setf</a></nobr>:
+
+<pre class="example">
+(setq lst '(1 2 3)) => (1 2 3)
+lst => (1 2 3)
+(setf (c-nth 4 lst) 'x) => X
+lst => (1 X 3)
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp.htm new file mode 100644 index 0000000..add5cc7 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp.htm @@ -0,0 +1,161 @@ +<html><head>
+
+<title>Common Lisp</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Where is the Nyquist Common Lisp Library?</h1>
+
+<hr>
+
+<p>Short answer - nowhere.</p>
+
+<p>Rationale:</p>
+
+<ol>
+
+<li><p>XLISP is a very simple Lisp. Many of the XLISP functions are just simple
+wrappers around the underlying <nobr>C functions</nobr>. This makes XLISP,
+as an interpreted language, run with reasonable speed. <nobr>The main</nobr>
+advantage of XLISP over <nobr>Common Lisp</nobr> is that XLISP is much
+smaller and therefore much easier to learn.</p></li>
+
+<li><p>The main trick of Nyquist is to use XLISP only in the initial setup
+phase, where the Lisp code is parsed, to <nobr>set-up</nobr> the
+<nobr>low-level</nobr> sound sample functions, written <nobr>in C</nobr>,
+not in Lisp.</p>
+
+<p><nobr>The Nyquist</nobr> <nobr>low-level</nobr> '<nobr>snd-...</nobr>'
+functions only look like Lisp functions, but they are direct wrappers around
+<nobr>C functions</nobr> and behave like that. They do not provide type
+contagion, instead they expect a correct number of arguments, given in
+correct order with correct data types, and if not given exactly as expected,
+chances are good that Nyquist will crash.</p>
+
+<p><nobr>In Nyquist</nobr>, <nobr>XLISP [slow]</nobr> is used to make sure
+that the <nobr>low-level</nobr> functions will be given the correct
+arguments, while the <nobr>low-level</nobr> sound sample functions after the
+initial setup phase will run in <nobr>high-speed C</nobr>, and not in Lisp
+anymore.</nobr></p></li>
+
+</ol>
+
+<p>Because the Nyquist <nobr>Common Lisp</nobr> functions are running in
+interpreted XLISP, they run slower than the <nobr>built-in</nobr> XLISP
+functions. Because many <nobr>Common Lisp</nobr> functions do extensive
+parsing and/or type checking on their arguments, they run many times
+slower than XLISP. That's why overloading Nyquist with an extensive
+<nobr>Common Lisp</nobr> layer makes not much sense.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>But why did you write so many Common Lisp functions?</h2>
+
+<hr>
+
+<p>I usually work with <nobr>Common Lisp</nobr> for prototyping, so if I'm
+porting code from <nobr>Common Lisp</nobr> to Nyquist:</p>
+
+<ol>
+
+<li><p>I first copy the <nobr>Common Lisp</nobr> code together with the
+respective Nyquist <nobr>Common Lisp</nobr> functions from screen into a
+Nyquist lisp file to see if the <nobr>Common Lisp</nobr> code works with
+Nyquist <nobr>at all</nobr>. Many of the Nyquist <nobr>Common Lisp</nobr>
+functions have argument tests to help with error tracking.</p></li>
+
+<li><p>When the <nobr>Common Lisp</nobr> code works with Nyquist I start to
+strip out everything I don't need for the particular problem at hand, making
+the Nyquist code run faster. Because this second step is highly depending on
+the particular problem at hand, there probably never will be a general
+solution for this.</p></li>
+
+</ol>
+
+<p><div class="box">
+
+<p>I have tried to keep the functions as <nobr>self-contained</nobr> as
+possible, any dependencies to <nobr>non-Nyquist</nobr> functions are noted
+directly below the code.</p>
+
+</div></p>
+
+<p>There are many XLISP functions that behave exactly like their
+<nobr>Common Lisp</nobr> counterparts, so I haven't written extra functions
+for them.</p>
+
+<ul>
+
+<li><p>If you already know <nobr>Common Lisp</nobr> then the Nyquist
+<nobr>Common Lisp</nobr> functions may help to understand how XLISP
+works.</p></li>
+
+<li><p>If you still don't know <nobr>Common Lisp</nobr> and maybe one day
+you decide to learn more <nobr>about it</nobr>, then the Nyquist
+<nobr>Common Lisp</nobr> functions may save you from learning everything
+double.</p></li>
+
+</ul>
+
+<p>In either case you can use the Nyquist <nobr>Common Lisp</nobr> functions
+as a <nobr>grab-bag</nobr> for your own functions.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/ceiling.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/ceiling.htm new file mode 100644 index 0000000..a39f495 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/ceiling.htm @@ -0,0 +1,137 @@ +<html><head>
+
+<title>cl:ceiling</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:ceiling</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>ceiling</b></nobr> function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward positive infinity:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>ceiling</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of truncating the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the truncate operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:ceiling</font> (number &optional (divisor
+ (if (integerp number) 1 1.0)
+ divisor-p))
+ (let ((quotient
+ (cond ((and (not divisor-p) (integerp number)) number)
+ ((= number divisor) 1)
+ (t (let ((i-quotient (/ (truncate number) (truncate divisor)))
+ (f-quotient (/ (float number) divisor)))
+ (if (or (= i-quotient f-quotient) <font color="#008844">; integer result</font>
+ (not (plusp f-quotient)))
+ (truncate f-quotient)
+ (1+ (truncate f-quotient))))))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The <nobr>cl:<b>ceiling</b></nobr> function computes a quotient that has
+been truncated toward positive infinity. <nobr>That is</nobr>, the quotient
+represents the smallest mathematical integer that is not smaller than the
+mathematical result.</p>
+
+<p>The quotient is directly returned by the function, while a list:</p>
+
+<pre class="example">
+(quotient remainder)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a> is set to
+<a href="../../reference/t.htm"> T </a> to signal that
+<a href="multiple-values.htm">Multiple Values</a> are returned.</p>
+
+<nobr>See
+<a href="rounding-and-truncation.htm">Rounding and Truncation</a></nobr>
+for more details.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:ceiling 3.5) => 4 <font color="#008844">; *rslt* => ( 4 -0.5)</font>
+(cl:ceiling -3.5) => -3 <font color="#008844">; *rslt* => (-3 -0.5)</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/debug-mv.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/debug-mv.htm new file mode 100644 index 0000000..c61cb23 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/debug-mv.htm @@ -0,0 +1,110 @@ +<html><head>
+
+<title>cl:debug:mv</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:debug:mv</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>debug:mv</b></b></nobr> function can be used to debug
+multiple value expressions:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>debug:mv</b> <i>expr</i></dt>
+<dd><i>expr</i> - a Lisp expression, returning an arbitrary number of values<br>
+returns - the normal Lisp return value from evaluating <i>expr</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:debug:mv</font> (expr)
+ (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+ (let ((result (eval expr)))
+ (format t <font color="#880000">";; cl:*multiple-values* => ~a~%"</font> <font color="#AA5500">cl:*multiple-values*</font>)
+ (format t <font color="#880000">";; *rslt* => ~a~a~%"</font> <font color="#AA5500">*rslt*</font>
+ (if <font color="#AA5500">cl:*multiple-values*</font> <font color="#880000">"" " [invalid]"</font>))
+ result))
+</pre>
+
+<p>The <nobr>cl:<b>debug:mv</b></nobr> function first sets the
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>, then it
+evaluates the expression. After evaluation it prints the values of the
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+and <a href="../../reference/global-rslt.htm">*rslt*</a> variables and
+returns the normal Lisp return value from the evaluation.</p>
+
+<p>Example:</p>
+
+<pre class="example">
+> (cl:debug:mv '(cl:values 1 2 3))
+;; cl:*multiple-values* => T
+;; *rslt* => (1 2 3)
+1
+
+> (cl:debug:mv 1)
+;; cl:*multiple-values* => NIL
+;; *rslt* => (1 2 3) [invalid]
+1
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/equalp.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/equalp.htm new file mode 100644 index 0000000..14835c5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/equalp.htm @@ -0,0 +1,162 @@ +<html><head>
+
+<title>cl:equalp</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:equalp</h1>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>equalp</b> <i>expr1 expr2</i>)</dt>
+<dd><i>exprN</i> - arbitrary Lisp expressions<br>
+returns - <a href="t.htm"> T </a> if the expressions
+are structurally equal, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<p>Two expressions are 'equalp':</p>
+
+<ul>
+
+<li><p>If the expressions
+<nobr>are <a href="../../reference/equal.htm">equal</a></nobr>.</p></li>
+
+<li><p>If two numbers of arbitrary type <nobr>are
+<a href="../../reference/number-equal.htm"> = </a></nobr>.</p></li>
+
+<li><p>If two characters are
+<nobr><a href="../../reference/char-equal-i.htm">char-equal</a></nobr>.</p></li>
+
+<li><p>If two strings are <nobr><a
+href="../../reference/string-equal-i.htm">string-equal</a></nobr>.</p></li>
+
+<li><p>If the two <a href="../../reference/car.htm">car</a>s in conses are
+'equalp' and the two <a href="../../reference/cdr.htm">cdr</a>s in conses
+are 'equalp'.</p></li>
+
+<li><p>If two arrays have the same number of elements and dimensions, and
+the corresponding elements in all dimensions are 'equalp'.</p></li>
+
+</ul>
+
+<p>Note that only 'equalp' can compare arrays.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:equalp</font> (expr-1 expr-2)
+ (or (equal expr-1 expr-2)
+ (and (numberp expr-1) (numberp expr-2) (= expr-1 expr-2))
+ (let ((type (type-of expr-1)))
+ (when (eq type (type-of expr-2))
+ (case type
+ (character (char-equal expr-1 expr-2))
+ (string (string-equal expr-1 expr-2))
+ (cons (do ((x (first expr-1)
+ (if (consp expr-1) (first expr-1) expr-1))
+ (y (first expr-2)
+ (if (consp expr-2) (first expr-2) expr-2)))
+ ((or (null expr-1)
+ (null expr-2)
+ (not (equalp x y)))
+ (and (null expr-1)
+ (null expr-2)))
+ (setq expr-1 (and (consp expr-1) (rest expr-1))
+ expr-2 (and (consp expr-2) (rest expr-2)))))
+ (array (let ((end (length expr-1)))
+ (when (eql end (length expr-2))
+ (dotimes (index end t)
+ (and (not (equalp (aref expr-1 index)
+ (aref expr-2 index)))
+ (return nil)))))))))))
+</pre>
+
+<p><b>cons:</b> <a href="../../reference/do.htm">do</a> is used instead of
+recursion because XLISP has only two kilobytes stack size. <nobr>The
+(<a href="../../reference/consp.htm">consp</a> <i>expr</i>)</nobr> tests are
+necessary because in a dotted list the last
+<a href="../../reference/rest.htm">rest</a> element is not a cons.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:equalp 1 1.0) => T
+(cl:equalp #\a #\A) => T
+(cl:equalp "Abc" "aBc") => T
+(cl:equalp '(1 #\a "Abc") '(1.0 #\A "aBc")) => T
+(cl:equalp #(1 #\a "Abc") #(1.0 #\A "aBc")) => T
+</pre>
+
+<p>Nested expressions only match if the nesting matches:</p>
+
+<pre class="example">
+(cl:equalp '(1 <font color="#AA0000">(</font>2 3<font color="#AA0000">)</font>) '(1.0 <font color="#AA0000">(</font>2.0 3.0<font color="#AA0000">)</font>) => T
+(cl:equalp '(1 <font color="#AA0000">(</font>2 3<font color="#AA0000">)</font>) '(<font color="#AA0000">(</font>1.0 2.0<font color="#AA0000">)</font> 3.0) => NIL
+(cl:equalp '(<font color="#AA0000">(</font>1 2<font color="#AA0000">)</font> 3) '(<font color="#AA0000">(</font>1.0 2.0<font color="#AA0000">)</font> 3.0) => T
+(cl:equalp '(<font color="#AA0000">(</font>1 2<font color="#AA0000">)</font> 3) '(1.0 <font color="#AA0000">(</font>2.0 3.0<font color="#AA0000">)</font>) => NIL
+</pre>
+
+<p>A character does not match a string with the same character:</p>
+
+<pre class="example">
+(cl:equalp #\a "a") => NIL
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/exp.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/exp.htm new file mode 100644 index 0000000..707e28e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/exp.htm @@ -0,0 +1,92 @@ +<html><head>
+
+<title>cl:exp</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:exp</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>exp</b></nobr> function does the same as the
+Nyquist/XLISP <a href="../../reference/exp.htm">exp</a> function, but
+also accepts integer numbers as argument:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>exp</b> <i>power</i>)</dt>
+<dd><i>power</i> - an integer or floating-point number<br>
+returns - the result of <nobr>'e' [2.7128]</nobr> to the power of <i>power</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:exp</font> (x)
+ (exp (float x)))
+</pre>
+
+<p>See <a href="../../reference/defun.htm">defun</a>,
+<a href="../../reference/exp.htm">exp</a>,
+<a href="../../reference/float.htm">float</a>.</p>
+
+<p>The <nobr>cl:<b>exp</b></nobr> function computes <nobr>'e'
+[2.7128]</nobr> raised to the specified 'power' and returns the result as a
+<nobr>floating-point</nobr> number.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/expt.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/expt.htm new file mode 100644 index 0000000..05e95ea --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/expt.htm @@ -0,0 +1,105 @@ +<html><head>
+
+<title>cl:expt</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:expt</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>expt</b></nobr> function computes the result of 'x' to
+the power <nobr>of 'y'</nobr>:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>expt</b> <i>base power</i>)</dt>
+<dd><i>base</i> - the base<br>
+<i>power</i> - the exponent<br>
+returns - the result of <i>base</i> to the power of <i>power</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:expt</font> (x y)
+ (let ((power (expt (float x) y)))
+ (if (and (integerp x) (integerp y))
+ (round power)
+ power)))
+</pre>
+
+<p>See <a href="../reference/and.htm">and</a>,
+<a href="../reference/defun.htm">defun</a>,
+<a href="../reference/expt.htm">expt</a>,
+<a href="../reference/float.htm">float</a>,
+<nobr><a href="../reference/if.htm"> if </a></nobr>,
+<a href="../reference/integerp.htm">integerp</a>,
+<a href="../reference/let.htm">let</a>,
+<a href="../reference/power.htm">power</a>,
+<a href="../reference/round.htm">round</a>.</p>
+
+<p>The <nobr>cl:<b>expt</b></nobr> function accepts integer and floating
+point numbers as arguments. <nobr>If both</nobr> arguments are integer
+numbers, the result will be an integer number, <nobr>if one</nobr> or both
+arguments are <nobr>floating-point</nobr> numbers, the result will be a
+<nobr>floating-point</nobr> number. <nobr>In contrast</nobr> to the
+Nyquist/XLISP <a href="../../reference/expt.htm">expt</a> function, the
+'<nobr>cl:expt</nobr>' function accepts exactly two arguments.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/floor.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/floor.htm new file mode 100644 index 0000000..79e046c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/floor.htm @@ -0,0 +1,150 @@ +<html><head>
+
+<title>cl:floor</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:floor</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>floor</b></nobr> function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward negative infinity:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>floor</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of truncating the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the truncate operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:floor</font> (number &optional (divisor
+ (if (integerp number) 1 1.0)
+ divisor-p))
+ (let ((quotient
+ (cond ((and (not divisor-p) (integerp number)) number)
+ ((= number divisor) 1)
+ (t (let ((i-quotient (/ (truncate number) (truncate divisor)))
+ (f-quotient (/ (float number) divisor)))
+ (if (or (= i-quotient f-quotient) <font color="#008844">; integer result</font>
+ (not (minusp f-quotient)))
+ (truncate f-quotient)
+ (1- (truncate f-quotient))))))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The <nobr>cl:<b>floor</b></nobr> function computes a quotient that has
+been truncated toward negative infinity. <nobr>That is</nobr>, the quotient
+represents the largest mathematical integer that is not larger than the
+mathematical quotient.</p>
+
+<p>The quotient is directly returned by the function, while a list:</p>
+
+<pre class="example">
+(quotient remainder)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a> is set to
+<a href="../../reference/t.htm"> T </a> to signal that
+<a href="multiple-values.htm">Multiple Values</a> are returned.</p>
+
+<nobr>See
+<a href="rounding-and-truncation.htm">Rounding and Truncation</a></nobr>
+for more details.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:floor 3.5) => 3 <font color="#008844">; *rslt* => ( 3 0.5)</font>
+(cl:floor -3.5) => -4 <font color="#008844">; *rslt* => (-4 0.5)</font>
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr><a href="../../reference/rem.htm">rem</a> - remainder of an integer division</nobr></li>
+<li><nobr><a href="../../reference/round.htm">round</a> - round arbitrary numbers to integers</nobr></li>
+<li><nobr><a href="../../reference/truncate.htm">truncate</a> - truncate arbitrary numbers toward zero</nobr></li>
+<li><nobr><a href="mod.htm">cl:mod</a></nobr></li>
+<li><nobr><a href="rem.htm">cl:rem</a></nobr></li>
+<li><nobr><a href="round.htm">cl:round</a></nobr></li>
+<li><nobr><a href="truncate.htm">cl:truncate</a></nobr></li>
+<li><nobr><a href="ceiling.htm">cl:ceiling</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/global-multiple-values.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/global-multiple-values.htm new file mode 100644 index 0000000..5ca1757 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/global-multiple-values.htm @@ -0,0 +1,142 @@ +<html><head>
+
+<title>cl:*multiple-values*</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:*multiple-values*</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>*multiple-values*</b></nobr> variable is used to signal
+if a function has returned multiple values:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>cl:<b>*multiple-values*</b></dt>
+<dd>returns - <a href="../../reference/t.htm"> T </a> if a
+function returned multiple values</dd>
+</dl>
+
+</div></p>
+
+<p>Test if a function has returned multiple values:</p>
+
+<pre class="example">
+(setf cl:*multiple-values* nil)
+(let ((result (function ...)))
+ (if cl:*multiple-values*
+ (do-something-with *rslt* ...)
+ (do-something-with result ...))
+ ... )
+</pre>
+
+<p>Do not use <nobr>cl:<b>*multiple-values*</b></nobr> with
+<a href="../../reference/let.htm">let</a> like this:</p>
+
+<pre class="example">
+(let ((cl:*multiple-values* nil)
+ (result (function ...)))
+ (if cl:*multiple-values*
+ (do-something-with *rslt* ...)
+ (do-something-with result ...))
+ ... )
+</pre>
+
+<p>This doesn't work because 'function' is evaluated in the global XLISP
+environment, where the lexical <a href="../../reference/let.htm">let</a>
+binding of the <nobr>cl:<b>*multiple-values*</b></nobr> variable does not
+exist, while the <a href="../../reference/if.htm"> if </a> form
+inside the <a href="../../reference/let.htm">let</a> form cannot see a
+global change of the <nobr>cl:<b>*multiple-values*</b></nobr> variable,
+because the global value is shadowed by the lexical
+<a href="../../reference/let.htm">let</a> binding.
+<nobr>See <a href="../environment.htm">Environment</a></nobr> for more
+details about variables.</p>
+
+<p>The XLISP <a href="../../reference/progv.htm">progv</a> special form can
+be used to encapsulate a multiple value call while automatically restoring
+the old values at the end like this:</p>
+
+<pre class="example">
+(values 1 2 3) => 1
+
+cl:*multiple-values* => T
+*rslt* => (1 2 3)
+
+(progv '(cl:*multiple-values* *rslt*) '(nil nil)
+ (let ((result (function ...)))
+ (if cl:*multiple-values*
+ (do-something-with *rslt* ...)
+ (do-something-with result ...))))
+
+cl:*multiple-values* => T
+*rslt* => (1 2 3)
+</pre>
+
+<p><div class="box">
+
+<p><b>Note:</b> All functions returning multiple values set
+<nobr>cl:<b>*multiple-values*</b></nobr> to
+<a href="../../reference/t.htm"> T </a>, but it's up to the
+Lisp programmer to reset the variable
+<nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>.</p>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/log.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/log.htm new file mode 100644 index 0000000..c7e5c5f --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/log.htm @@ -0,0 +1,95 @@ +<html><head>
+
+<title>cl:log</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:log</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>log</b></nobr> function does the same as the
+Nyquist/XLISP <a href="../../reference/log.htm">log</a> function, but also
+accepts integer numbers and has an optional 'base' argument:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>log</b> <i>number</i> [<i>base</i>])</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+<i>base</i> - an integer or floating-point number<br>
+returns - the the logarithm of <i>number</i> in base <i>base</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:log</font> (number &optional base)
+ (if base
+ (if (zerop base)
+ 0.0
+ (/ (log (float number)) (log (float base))))
+ (log (float number))))
+</pre>
+
+<p>The '<nobr>cl:log</nobr>' function returns the logarithm of 'number' in
+base 'base'. <nobr>If 'base'</nobr> is not supplied its value <nobr>is
+'e'</nobr>, the base of the natural logarithms. <nobr>If the</nobr> 'base'
+argument is zero, then 'cl:log' returns zero. <nobr>The result</nobr> is
+always a <nobr>floating-point</nobr> number.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/mod.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/mod.htm new file mode 100644 index 0000000..9454d4e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/mod.htm @@ -0,0 +1,97 @@ +<html><head>
+
+<title>cl:mod</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:mod</h1>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>mod</b> <i>number divisor</i>)</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+<i>divisor</i> - an integer or floating-point number<br>
+returns - the remainder of a <a href="#cl-floor">cl:floor</a> operation</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:mod</font> (number divisor)
+ (if (= (abs number) (abs divisor))
+ (if (and (integerp number) (integerp divisor)) 0 0.0)
+ (let* ((i-quotient (/ (truncate number) (truncate divisor)))
+ (f-quotient (/ (float number) divisor))
+ (quotient (if (or (= i-quotient f-quotient) <font color="#008844">; integer result</font>
+ (not (minusp f-quotient)))
+ (truncate f-quotient)
+ (1- (truncate f-quotient)))))
+ (- number (* quotient divisor)))))
+</pre>
+
+<p>The <nobr>cl:<b>mod</b></nobr> function performs the
+<a href="floor.htm">cl:floor</a> operation on its arguments and returns the
+remainder of the <a href="floor.htm">cl:floor</a> operation. <nobr>The
+result</nobr> is either zero or an integer or <nobr>floating-point</nobr>
+number with the same sign as the 'divisor' argument. <nobr>If both</nobr>
+arguments are integer numbers, the <nobr>cl:<b>mod</b></nobr> function is
+equal to the mathematical modulus function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-bind.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-bind.htm new file mode 100644 index 0000000..32fdadf --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-bind.htm @@ -0,0 +1,193 @@ +<html><head>
+
+<title>cl:multiple-value-bind</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:multiple-value-bind</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>multiple-value-bind</b></nobr> macro creates new bindings
+for a list of symbols and evaluates expressions that use these bindings:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>multiple-value-bind</b> <i>symbols values</i> [<i>expr1</i> ...])</dt>
+<dd><i>symbols</i> - a list of symbols<br>
+<i>values</i> - a Lisp expression returning one or more values<br>
+<i>exprN</i> - arbitrary Lisp expressions<br>
+returns - the value[s] returned by the last expression</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:multiple-value-bind</font> (symbols expr &rest body)
+ (and (or (not (consp symbols))
+ (eq 'quote (first symbols))
+ (dolist (symbol symbols)
+ (or (symbolp symbol) (return t))))
+ (error <font color="#880000">"not a list of symbols"</font> symbols))
+ (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+ (let* ((result (eval expr))
+ (values (if <font color="#AA5500">cl:*multiple-values*</font>
+ <font color="#AA5500">*rslt*</font>
+ (list result)))
+ (number-of-symbols (length symbols))
+ (number-of-values (length values))
+ (bindings nil))
+ (dotimes (index number-of-symbols)
+ (push (if (< index number-of-values)
+ (list (nth index symbols)
+ (list 'quote (nth index values)))
+ (nth index symbols))
+ bindings))
+ (setq bindings (reverse bindings))
+ `(let ,bindings ,@body)))
+</pre>
+
+<p>The 'values' expression is evaluated, and each of the symbols is bound to
+the respective value returned by the evaluation. <nobr>If there</nobr> are
+more symbols than values returned, extra values of
+<a href="../../reference/nilo.htm">NIL</a> are bound to the remaining
+symbols. <nobr>If there</nobr> are more values than symbols, the extra
+values are ignored. The symbols are bound to the values <nobr>by
+<a href="../../reference/let.htm">let</a></nobr>, behaving like an
+<nobr>implicit <a href="../../reference/progn.htm">progn</a></nobr>.</p>
+
+<p><nobr>Before evaluating 'expr1', the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable <nobr>is <a href="../../reference/t.htm"> T </a></nobr>
+if evaluating the 'values' expression returned multiple values and
+<a href="../../reference/nil.htm">NIL</a> with a normal return value.</p>
+
+<p>The <nobr>cl:<b>multiple-value-bind</b></nobr> macro binds multiple
+values to local <a href="../../reference/let.htm">let</a> variables::</p>
+
+<pre class="example">
+> (macroexpand-1 '(cl:multiple-value-bind (a b c)
+ (cl:values 1 2 3)
+ (list a b c)))
+(LET ((A (QUOTE 1))
+ (B (QUOTE 2))
+ (C (QUOTE 3)))
+ (LIST A B C))
+</pre>
+
+<p>The <a href="../../reference/quote.htm">quote</a>s are necessary to
+prevent 'unbound variable' and 'unbound function' errors with symbols and
+lists.</p>
+
+<p>Examples:</p>
+
+<p><b>1.</b> The <nobr>cl:<b>multiple-value-bind</b></nobr> macro binds
+values returned by the <a href="values.htm">cl:values</a> function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">multiple-value-function</font> ()
+ (cl:values 1 2 3)) <font color="#008844">; multiple return values</font>
+
+> (cl:multiple-value-bind (a b c)
+ (multiple-value-function)
+ (list a b c))
+(1 2 3)
+</pre>
+
+<p><b>2.</b> If there are no values returned in the Nyquist
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable, the normal
+function return value is bound to the first symbol and all remaining symbols
+are bound <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">normal-lisp-function</font> ()
+ (+ 1 1)) <font color="#008844">; normal return value</font>
+
+> (cl:multiple-value-bind (a b c)
+ (normal-lisp-function)
+ (list a b c))
+(2 NIL NIL)
+</pre>
+
+<p><b>3.</b> If there are less values than symbols, the extra symbols are
+bound <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">not-enough-values-function</font> ()
+ (cl:values 1 2)) <font color="#008844">; multiple return values</font>
+
+> (cl:multiple-value-bind (a b c)
+ (not-enough-values-function)
+ (list a b c))
+(1 2 NIL)
+</pre>
+
+<p><b>4.</b> If there are more values than symbols, the extra values are
+ignored:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">too-many-values-function</font> ()
+ (cl:values 1 2 3 4 5)) <font color="#008844">; multiple return values</font>
+
+> (cl:multiple-value-bind (a b c)
+ (too-many-values-function)
+ (list a b c))
+(1 2 3)
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-call.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-call.htm new file mode 100644 index 0000000..dba7c45 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-call.htm @@ -0,0 +1,119 @@ +<html><head>
+
+<title>cl:multiple-value-call</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:multiple-value-call</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>multiple-value-call</b></nobr> macro applies a function
+to a list of return values:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>multiple-value-call</b> <i>function</i> [<i>expr1</i> ...])</dt>
+<dd><i>function</i> - a Lisp expression evaluating to a function call<br>
+<i>exprN</i> - arbitrary Lisp expressions<br>
+returns - the values returned by the function</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:multiple-value-call</font> (function &rest exprs)
+ (let (args)
+ (dolist (expr exprs)
+ (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+ (let* ((result (eval expr)))
+ (if <font color="#AA5500">cl:*multiple-values*</font>
+ (dolist (rslt <font color="#AA5500">*rslt*</font>) (push rslt args))
+ (push result args))))
+ (setq args (reverse args))
+ `(progn
+ (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+ (apply ,function ',args)))
+</pre>
+
+<p>The <nobr>cl:<b>multiple-value-call</b></nobr> macro first evaluates the
+expressions and collects all return values in a single list, then the
+'function' form is evaluated and the resulting function call is applied to
+the list of values.</p>
+
+<p>Before applying the function to the list of values the
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable is set to <a href="../../reference/nil.htm">NIL</a>, the final value of
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+depends on the 'function' argument.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+> (funcall #'+
+ (cl:values 1 2)
+ (cl:values 3 4))
+4 <font color="#008844">; (apply #'+ (1 3))</font>
+
+> (cl:multiple-value-call #'+
+ (cl:values 1 2)
+ (cl:values 3 4))
+10 <font color="#008844">; (apply #'+ (1 2 3 4))</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-list.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-list.htm new file mode 100644 index 0000000..6e3a374 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-list.htm @@ -0,0 +1,112 @@ +<html><head>
+
+<title>cl:multiple-value-list</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:multiple-value-list</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>multiple-value-list</b></nobr> macro evaluates a Lisp
+expression and returns all values in a list:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>multiple-value-list</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - an arbitrary Lisp expression<br>
+returns - all values in a list</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:multiple-value-list</font> (expr)
+ (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+ (let ((result (eval expr)))
+ (if <font color="#AA5500">cl:*multiple-values*</font>
+ '<font color="#AA5500">*rslt*</font>
+ `(list ,result))))
+</pre>
+
+<p>The <nobr>cl:<b>multiple-value-list</b></nobr> macro first evaluates the
+expression. <nobr>If the</nobr> evaluation returned multiple values, the
+value of the <a href="../../reference/global-rslt.htm">*rslt*</a> variable
+is returned, otherwise the normal Lisp return value is returned in a list of
+one element.</p>
+
+<p><nobr>The
+<a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable <nobr>is <a href="../../reference/t.htm"> T </a></nobr>
+if evaluating the expression returns multiple values and
+<a href="../../reference/nil.htm">NIL</a> with a normal return value.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:multiple-value-list 1) => (1) <font color="#008844">; cl:*multiple-values* => NIL</font>
+ <font color="#008844">; *rslt* => [invalid]</font>
+(cl:multiple-value-list
+ (+ 1 1)) => (2) <font color="#008844">; cl:*multiple-values* => NIL</font>
+ <font color="#008844">; *rslt* => [invalid]</font>
+(cl:multiple-value-list
+ (cl:values 1 2 3)) => (1 2 3) <font color="#008844">; cl:*multiple-values* => T</font>
+ <font color="#008844">; *rslt* => (1 2 3)</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-prog1.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-prog1.htm new file mode 100644 index 0000000..d5f5fc6 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-prog1.htm @@ -0,0 +1,106 @@ +<html><head>
+
+<title>cl:multiple-value-prog1</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:multiple-value-prog1</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>multiple-value-prog1</b></nobr> macro is like
+<a href="../../reference/prog1.htm">prog1</a>, but it can handle multiple
+values:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>multiple-value-prog1</b> <i>expr1</i> [<i>expr2</i> ...])</dt>
+<dd><i>exprN</i> - arbitrary Lisp expressions<br>
+returns - the values returned by the first expression</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:multiple-value-prog1</font> (expr &rest body)
+ (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+ (let* ((result (eval expr)))
+ (if <font color="#AA5500">cl:*multiple-values*</font>
+ `(progn ,@body
+ (setq <font color="#AA5500">*rslt*</font> ',<font color="#AA5500">*rslt*</font>
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ ',result)
+ `(progn ,@body ',result))))
+</pre>
+
+<p>The <nobr>cl:<b>multiple-value-prog1</b></nobr> macro evaluates the first
+expression and saves all the values returned by the evaluation. <nobr>It
+then</nobr> evaluates each of the following expressions from left to right,
+discarding their values. After the evaluation is finished, the
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+and <a href="../../reference/global-rslt.htm">*rslt*</a> variables are
+restored and the primary value from evaluating the fist expression is
+returned.</p>
+
+<p><nobr>The
+<a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable <nobr>is <a href="../../reference/t.htm"> T </a></nobr>
+if evaluating the first expression returns multiple values and
+<a href="../../reference/nil.htm">NIL</a> with a normal return value.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-setq.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-setq.htm new file mode 100644 index 0000000..3a8b701 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-setq.htm @@ -0,0 +1,239 @@ +<html><head>
+
+<title>cl:multiple-value-setq</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:multiple-value-setq</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>multiple-value-setq</b></nobr> macro assigns multiple
+values to multiple variables:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>multiple-value-setq</b> <i>symbols expr</i>)</dt>
+<dd><i>symbols</i> - a list of symbols<br>
+<i>expr</i> - a Lisp expression returning one or more values<br>
+returns - the primary value returned by evaluating the expression</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:multiple-value-setq</font> (symbols expr)
+ (and (or (not (consp symbols))
+ (eq 'quote (first symbols))
+ (dolist (symbol symbols)
+ (or (symbolp symbol) (return t))))
+ (error <font color="#880000">"not a list of symbols"</font> symbols))
+ (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+ (let* ((result (eval expr))
+ (values (if <font color="#AA5500">cl:*multiple-values*</font>
+ <font color="#AA5500">*rslt*</font>
+ (list result)))
+ (number-of-symbols (length symbols))
+ (number-of-values (length values))
+ (assignments (list 'setq)))
+ (dotimes (index number-of-symbols)
+ (push (nth index symbols) assignments)
+ (push (when (< index number-of-values)
+ (list 'quote (nth index values)))
+ assignments))
+ (setq assignments (reverse assignments))
+ `(progn ,assignments ',result)))
+</pre>
+
+<p>The expression is evaluated, and each symbol is assigned to the
+corresponding value returned by the evaluation. <nobr>If there</nobr> are
+more symbols than values returned,
+<a href="../../reference/nil.htm">NIL</a> is assigned to the extra symbols.
+<nobr>If there</nobr> are more values than symbols, the extra values are
+discarded.</p>
+
+<p><nobr>The
+<a href="#cl-global-multiple-values">cl:*multiple-values*</a></nobr>
+variable <nobr>is <a href="../../reference/t.htm"> T </a></nobr>
+if evaluating the expression returns multiple values and
+<a href="../../reference/nil.htm">NIL</a> with a normal return value.</p>
+
+<p>The <nobr>cl:<b>multiple-value-setq</b></nobr> macro assigns multiple
+values to multiple variables
+<nobr>using <a href="../../reference/setq.htm">setq</a>:</nobr></p>
+
+<pre class="example">
+> (macroexpand-1 '(cl:multiple-value-setq (a b c)
+ (cl:values 1 2 3)))
+(PROGN (SETQ A (QUOTE 1)
+ B (QUOTE 2)
+ C (QUOTE 3))
+ (QUOTE 1))
+</pre>
+
+<p>The <a href="../../reference/quote.htm">quote</a>s are necessary to
+prevent 'unbound variable' and 'unbound function' errors with symbols and
+lists.</p>
+
+<p>Examples:</p>
+
+<p><b>1.</b> The <nobr>cl:<b>multiple-value-setq</b></nobr> macro assigns
+values returned by the <a href="values.htm">cl:values</a> function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">multiple-value-function</font> ()
+ (cl:values 1 2 3)) <font color="#008844">; multiple return values</font>
+
+> (let ((a 'A) (b 'B) (c 'C))
+ (cl:multiple-value-setq (a b c)
+ (multiple-value-function))
+ (list a b c))
+(1 2 3)
+</pre>
+
+<p><b>2.</b> If there are no values returned in the Nyquist
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable, the normal
+function return value is assigned to the first symbol and all remaining
+symbols are assigned
+<nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">normal-lisp-function</font> ()
+ (+ 1 1)) <font color="#008844">; normal return value</font>
+
+> (let ((a 'A) (b 'B) (c 'C))
+ (cl:multiple-value-setq (a b c)
+ (normal-lisp-function))
+ (list a b c))
+(2 NIL NIL)
+</pre>
+
+<p><b>3.</b> If there are less values than symbols, the extra symbols are
+assigned <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">not-enough-values-function</font> ()
+ (cl:values 1 2)) <font color="#008844">; multiple return values</font>
+
+> (let ((a 'A) (b 'B) (c 'C))
+ (cl:multiple-value-setq (a b c)
+ (not-enough-values-function))
+ (list a b c))
+(1 2 NIL)
+</pre>
+
+<p><b>4.</b> If there are more values than symbols, the extra values are
+ignored:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">too-many-values-function</font> ()
+ (cl:values 1 2 3 4 5)) <font color="#008844">; multiple return values</font>
+
+> (let ((a 'A) (b 'B) (c 'C))
+ (cl:multiple-value-setq (a b c)
+ (too-many-values-function))
+ (list a b c))
+(1 2 3)
+</pre>
+
+<p><b>5.</b> Symbols not contained in the
+<nobr>cl:<b>multiple-value-setq</b></nobr> <nobr>symbol-list</nobr> are not
+changed:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">multiple-value-function</font> ()
+ (cl:values 1 2 3)) <font color="#008844">; multiple return values</font>
+
+> (let ((a 'A) (b 'B) (c 'C) (d 'D) (e 'E))
+ (cl:multiple-value-setq (a b c)
+ (multiple-value-function))
+ (list a b c d e))
+(1 2 3 D E)
+</pre>
+
+<p><b>5.</b> If no bindings exist, new variables will be created:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">multiple-value-function</font> ()
+ (cl:values 1 2 3)) <font color="#008844">; multiple return values</font>
+
+> (let ((c 'C) (d 'D) (e 'E))
+ (cl:multiple-value-setq (a b c)
+ (multiple-value-function))
+ (list a b c d e))
+(1 2 3 D E)
+</pre>
+
+<p><b>Caution:</b> In the last example, two global variables 'a' and 'b'
+were created, while the lexical <a href="../../reference/let.htm">let</a>
+variable 'c' was assigned to the <nobr>value 3</nobr>:</p>
+
+<pre class="example">
+> (list a b)
+(1 2)
+
+> (list a b c)
+<font color="#AA0000">error: unbound variable - C</font>
+</pre>
+
+<p>The lexical <a href="../../reference/let.htm">let</a> binding of 'c' does
+not exist in the global <nobr>top-level</nobr>.
+<nobr>See <a href="../environment.htm">Environment</a></nobr> for more
+details about variables.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-values.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-values.htm new file mode 100644 index 0000000..d05df73 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-values.htm @@ -0,0 +1,181 @@ +<html><head>
+
+<title>Multiple Values</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Multiple Values</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#multiple-values">Multiple Values</a></nobr></li>
+<ul>
+<li><nobr>Nyquist/XLISP helpers</nobr></li>
+<ul>
+<li><nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a> - [Variable] - signals if a function has returned multiple values</nobr></li>
+<li><nobr><a href="debug-mv.htm">cl:debug:mv</a> - [Function] - debug multiple values</nobr></li>
+</ul>
+<li><nobr>Returning Multiple Values</nobr></li>
+<ul>
+<li><nobr><a href="values.htm">cl:values</a> - [Function] - return multiple values</nobr></li>
+<li><nobr><a href="values-list.htm">cl:values-list</a> - [Function] - return multiple values from a list</nobr></li>
+</ul>
+<li><nobr>Working with Multiple Values</nobr></li>
+<ul>
+<li><nobr><a href="multiple-value-list.htm">cl:multiple-value-list</a> - [Macro] - evaluate an expression and return all values in a list</nobr></li>
+<li><nobr><a href="multiple-value-bind.htm">cl:multiple-value-bind</a> - [Macro] - bind multiple values to multiple <a href="../reference/let.htm">let</a> variables</nobr></li>
+<li><nobr><a href="multiple-value-setq.htm">cl:multiple-value-setq</a> - [Macro] - assign multiple values to multiple variables using <a href="../reference/setq.htm">setq</a></nobr></li>
+<li><nobr><a href="multiple-value-prog1.htm">cl:multiple-value-prog1</a> - [Macro] - eveluate multiple expressions, return the values of the first expression</nobr></li>
+<li><nobr><a href="multiple-value-call.htm">cl:multiple-value-call</a> - [Macro] - apply a function to multiple values collected in a list</nobr></li>
+</ul>
+</ul>
+</ol>
+
+<a name="multiple-values"></a>
+
+<hr>
+
+<h2>Multiple Values</h2>
+
+<hr>
+
+<p>This is a port of the Common List framework for passing multiple values
+from one place to another. <nobr>It is</nobr> most often used to return
+multiple values from a function with
+<a href="values.htm">cl:values</a> or to bind multiple values to multiple
+variables with
+<nobr><a href="multiple-value-bind.htm">cl:multiple-value-bind</a></nobr> or
+<nobr><a href="multiple-value-setq.htm">cl:multiple-value-setq</a></nobr>.</p>
+
+<p>The multiple value functions and macros use the
+<nobr>Nyquist/XLISP</nobr>
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable to store the
+values as a list, while the
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable is used as a flag to indicate if a function has returned multiple
+values.</p>
+
+<p><b>What happens if a normal Lisp function are given multiple
+values?</b></p>
+
+<p>A normal Lisp function only sees the 'primary' return value, as returned
+by every Lisp function. <nobr>The additional</nobr> return values
+[including the primary return value] are stored in the
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and are only read
+by the multiple value functions. This also means that with multiple values,
+the most important value should always be returned as the first value,
+because only the first value can be seen by a normal Lisp function.
+<nobr>See <a href="values.htm">cl:values</a></nobr> for examples.</p>
+
+<p><b>What happens if a function expecting multiple values is given a normal
+Lisp return value?</b></p>
+
+<p>The first symbol will be set to the function's return value, while all
+other symbol will be set to <a href="../../reference/nil.htm">NIL</a>.
+<nobr>No symbol</nobr> will be left unset. <nobr>All functions</nobr>
+expecting multiple values are protected against a wrong number of values.
+<nobr>If there</nobr> are more symbols than values, then the extra symbols
+are set to <a href="../../reference/nil.htm">NIL</a>, if there are more
+values than symbols, the extra values will be ignored.</p>
+
+<p><div class="box">
+
+<p><b>Known Limitations</b></p>
+
+<p><b>1.</b> In Nyquist/XLISP, <a href="values.htm">cl:values</a> cannot be
+used as argument to <a href="../../reference/setf.htm">setf</a>. <nobr>But
+this</nobr> is not a real problem, because the values are stored as a
+simple list in the <a href="../../reference/global-rslt.htm">*rslt*</a>
+variable, where they can be manipulated with any arbitrary Lisp
+functions, not only <nobr>with
+<a href="../../reference/setf.htm">setf</a></nobr>.</p>
+
+<p><b>2.</b> In <nobr>Common Lisp</nobr> there exists the option to return
+<nobr>'no value</nobr>' by calling the 'values' function with no arguments.
+<nobr>In Nyquist/XLISP</nobr> there is no <nobr>built-in</nobr> way to
+return '<nobr>no value</nobr>' from a function. <nobr>The symbol</nobr>
+<a href="../../reference/global-unbound.htm">*unbound*</a> cannot be used for
+this because in <nobr>Common Lisp</nobr>, if '<nobr>no value</nobr>' is
+assigned to a symbol as variable value, the new value will be
+<a href="../../reference/nil.htm">NIL</a> and not
+<a href="../../reference/global-unbound.htm">*unbound*</a>.</p>
+
+<p>In Nyquist/XLISP, the <a href="values.htm">cl:values</a> function, if
+called with no arguments, always returns
+<a href="../../reference/nil.htm">NIL</a>, and the
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable will be
+set <nobr>to <a href="../../reference/nil.htm">NIL</a>, too:</nobr></p>
+
+<pre class="example">
+(cl:values) => NIL <font color="#008844">; *rslt* = NIL</font>
+(cl:values nil) => NIL <font color="#008844">; *rslt* = (NIL)</font>
+</pre>
+
+<p>Maybe this observation helps to write a '<nobr>no values</nobr>' test if
+anybody really <nobr>needs it</nobr>.</p>
+
+<p><b>3.</b> Neither in <nobr>Common Lisp</nobr> nor in Nyquist/XLISP is it
+possibe to return nested multiple values:</p>
+
+<pre class="example">
+(cl:values (1 (cl:values 2 3) 4) => 1 <font color="#008844">; *rslt* = (1 2 4)</font>
+</pre>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/numbers.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/numbers.htm new file mode 100644 index 0000000..d1b684c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/numbers.htm @@ -0,0 +1,104 @@ +<html><head>
+
+<title>Numbers</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Numbers</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#number-types">Number Types</a></nobr></li>
+<li><nobr><a href="#integer-limits">Integer Limits</a></nobr></li>
+</ol>
+
+<a name="number-types"></a>
+
+<hr>
+
+<h2>Number Types</h2>
+
+<hr>
+
+<p>In Nyquist/XLISP only two types of numers exist:</p>
+
+<ul>
+<li><nobr><b>fixnum</b> - integer numbers</nobr></li>
+<li><nobr><b>flonum</b> - floating-point numbers</nobr></li>
+</ul>
+
+<p>In Nyquist/XLISP, there are no ratios or complex numbers. Even if the
+math functions in this section are modelled after <nobr>Common Lisp</nobr>,
+no attempt is made to emulate these numbers.</p>
+
+<a name="integer-limits"></a>
+
+<hr>
+
+<h2>Integer Limits</h2>
+
+<hr>
+
+<pre class="example">
+(setq <font color="#AA5500">*most-positive-fixnum*</font> 2147483647)
+(setq <font color="#AA5500">*most-negative-fixnum*</font> -2147483648)
+</pre>
+
+<p><b>Note:</b> these are the limits for <nobr>32-bit</nobr> machines.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/rem.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/rem.htm new file mode 100644 index 0000000..aba20c5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/rem.htm @@ -0,0 +1,93 @@ +<html><head>
+
+<title>cl:rem</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:rem</h1>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>rem</b> <i>number divisor</i>)</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+<i>divisor</i> - an integer or floating-point number<br>
+returns - the remainder of a <a href="cl-truncate">cl:truncate</a> operation</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:rem</font> (number divisor)
+ (if (= (abs number) (abs divisor))
+ (if (and (integerp number) (integerp divisor)) 0 0.0)
+ (let ((quotient (truncate (/ (float number) divisor))))
+ (- number (* quotient divisor)))))
+</pre>
+
+<p>The <nobr>cl:<b>rem</b></nobr> function performs the
+<a href="truncate.htm">cl:truncate</a> operation on its arguments and
+returns the remainder of the <a href="truncate.htm">cl:truncate</a>
+operation. <nobr>The result</nobr> is either zero or an integer or
+<nobr>floating-point</nobr> number with the same sign as the 'number'
+argument. <nobr>If both</nobr> arguments are integer numbers, the
+<nobr>cl:<b>rem</b></nobr> function is equal to the mathematical remainder
+function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/remainder-and-modulus.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/remainder-and-modulus.htm new file mode 100644 index 0000000..b7e89c4 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/remainder-and-modulus.htm @@ -0,0 +1,93 @@ +<html><head>
+
+<title>Remainder and Modulus</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Remainder and Modulus</h1>
+
+<hr>
+
+<p>The <a href="mod.htm">cl:mod</a> and <a href="rem.htm">cl:rem</a>
+function are generalizations of the modulus and remainder functions.</p>
+
+<ul>
+
+<li><p><nobr>The <a href="mod.htm">cl:mod</a></nobr> function performs the
+<a href="floor.htm">cl:floor</a> operation on its arguments and returns the
+remainder of the <a href="floor.htm">cl:floor</a> operation.</p></li>
+
+<li><p><nobr>The <a href="rem.htm">cl:rem</a></nobr> function performs the
+<a href="truncate.htm">cl:truncate</a> operation on its arguments and returns
+the remainder of the <a href="truncate.htm">cl:truncate</a> operation.</p></li>
+
+</ul>
+
+<p><nobr>The <a href="mod.htm">cl:mod</a></nobr> and
+<a href="rem.htm">cl:rem</a> functions are the modulus and remainder
+functions when the 'number' and 'divisor' arguments both are integers.</p>
+
+<pre class="example">
+(mod 13 4) => 1 (rem 13 4) => 1
+(mod -13 4) => 3 (rem -13 4) => -1
+(mod 13 -4) => -3 (rem 13 -4) => 1
+(mod -13 -4) => -1 (rem -13 -4) => -1
+(mod 13.4 1) => 0.4 (rem 13.4 1) => 0.4
+(mod -13.4 1) => 0.6 (rem -13.4 1) => -0.4
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/round.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/round.htm new file mode 100644 index 0000000..cf0be2c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/round.htm @@ -0,0 +1,141 @@ +<html><head>
+
+<title>cl:round</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:round</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>round</b></nobr> function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward the next integer:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>round</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of runding the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the round operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:round</font> (number &optional (divisor
+ (if (integerp number) 1 1.0)
+ divisor-p))
+ (let* ((x (/ (float number) divisor))
+ (quotient (cond ((and (not divisor-p) (integerp number)) number)
+ ((= number divisor) 1)
+ ((plusp x) (truncate (+ x 0.5)))
+ ((= (- x 0.5) (truncate (- x 0.5)))
+ (if (minusp x)
+ (1- (truncate x))
+ (truncate x)))
+ (t (truncate (- x 0.5))))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The <nobr>cl:<b>round</b></nobr> function computes a quotient that has
+been rounded to the nearest mathematical integer. <nobr>If the</nobr>
+mathematical quotient is exactly halfway between two integers, [that is, it
+has the form <nobr>'integer+1/2']</nobr>, then the quotient has been rounded
+to the even [divisible <nobr>by two]</nobr> integer.</p>
+
+<p>The quotient is directly returned by the function, while a list:</p>
+
+<pre class="example">
+(quotient remainder)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a> is set to
+<a href="../../reference/t.htm"> T </a> to signal that
+<a href="multiple-values.htm">Multiple Values</a> are returned.</p>
+
+<nobr>See
+<a href="rounding-and-truncation.htm">Rounding and Truncation</a></nobr>
+for more details.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(round 3.5) => 4
+(round -3.5) => -3
+
+(cl:round 3.5) => 4 <font color="#008844">; *rslt* = ( 4 -0.5)</font>
+(cl:round -3.5) => -4 <font color="#008844">; *rslt* = (-4 0.5)</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/rounding-and-truncation.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/rounding-and-truncation.htm new file mode 100644 index 0000000..40eaebc --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/rounding-and-truncation.htm @@ -0,0 +1,179 @@ +<html><head>
+
+<title>Rounding and Truncation</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Rounding and Truncation</h1>
+
+<hr>
+
+<p>The <a href="round.htm">cl:round</a>,
+<a href="truncate.htm">cl:truncate</a>,
+<a href="ceiling.htm">cl:ceiling</a> and
+<a href="floor.htm">cl:floor</a> functions divide a number by a divisor,
+returning a quotient and a remainder:</p>
+
+<p><div class="box">
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="round.htm">cl:round</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="truncate.htm">cl:truncate</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="ceiling.htm">cl:ceiling</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="floor.htm">cl:floor</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+</tbody></table></p>
+
+<p><nobr>
+<i>quotient</i> * <i>divisor</i> + <i>remainder</i> = <i>number</i></nobr></p>
+
+</div></p>
+
+<p>The 'quotient' always represents a mathematical integer. <nobr>The
+'remainder'</nobr> is an integer if both 'number' and 'divisor' arguments
+are integers, and a <nobr>floating-point</nobr> number if either the
+'number' or the 'divisor' or both are <nobr>floating-point</nobr>
+numbers.</p>
+
+<p>With Nyquist/XLISP, the 'quotient' is always directly returned by the
+function, while a list:</p>
+
+<pre class="example">
+(<font color="#0000CC">quotient remainder</font>)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a> is set to
+<a href="../../reference/t.htm"> T </a> to signal that
+<a href="multiple-values.htm">Multiple Values</a> are returned.</p>
+
+Examples:
+
+<pre class="example">
+(cl:round 3.5) => 4 <font color="#008844">; *rslt* = ( 4 -0.5)</font>
+(cl:truncate 3.5) => 3 <font color="#008844">; *rslt* = ( 3 0.5)</font>
+(cl:ceiling 3.5) => 4 <font color="#008844">; *rslt* = ( 4 -0.5)</font>
+(cl:floor 3.5) => 3 <font color="#008844">; *rslt* = ( 3 0.5)</font>
+
+(cl:round -3.5) => -4 <font color="#008844">; *rslt* = (-4 0.5)</font>
+(cl:truncate -3.5) => -3 <font color="#008844">; *rslt* = (-3 -0.5)</font>
+(cl:ceiling -3.5) => -3 <font color="#008844">; *rslt* = (-3 -0.5)</font>
+(cl:floor -3.5) => -4 <font color="#008844">; *rslt* = (-4 0.5)</font>
+</pre>
+
+<p>Force an integer division:</p>
+
+<pre class="example">
+(cl:truncate 3.0 2.0) => 1 <font color="#008844">; Common Lisp</font>
+(/ (truncate 3.0) (truncate 2.0)) => 1 <font color="#008844">; Nyquist/XLISP</font>
+(/ 3 2) => 1 <font color="#008844">; integer division</font>
+</pre>
+
+<p><div class="box">
+
+<p><b>Implementation Notes</b></p>
+
+<pre class="example">
+(defun <font color="#0000CC">name</font> (number &optional (divisor (if (<font color="#AA0000">integerp</font> number) 1 1.0)))
+ ... )
+</pre>
+
+<p>The <a href="../../reference/integerp.htm">integerp</a> test in the
+parameter list signals an error if the 'number' argument is not a number,
+also the <nobr><a href="../../reference/division.htm"> / </a>
+[division]</nobr> function signals errors if the 'divisor' argument is zero
+or not a number, so we do not explicitely need to test the arguments.</p>
+
+<p>The <nobr><a href="ceiling.htm">cl:ceiling</a></nobr> and
+<nobr><a href="floor.htm">cl:floor</a></nobr> functions test if 'number' is
+an integer multiple of 'divisor' by comparing the results of an integer
+division and a <nobr>floating-point</nobr> division:</p>
+
+<pre class="example">
+(let ((<font color="#AA0000">i-quotient</font> (/ (truncate number) (truncate divisor)))
+ (<font color="#AA0000">f-quotient</font> (/ (float number) divisor)))
+ (if (= <font color="#AA0000">i-quotient f-quotient</font>)
+ ...
+</pre>
+
+<p>I'm not sure if this really catches all cases <nobr>[e.g.
+regarding</nobr> floating point precision], but have found no problems so
+far.</p>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/sqrt.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/sqrt.htm new file mode 100644 index 0000000..b430da3 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/sqrt.htm @@ -0,0 +1,92 @@ +<html><head>
+
+<title>cl:sqrt</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:sqrt</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>sqrt</b></nobr> function does the same as the
+Nyquist/XLISP <a href="../../reference/sqrt.htm">sqrt</a> function, but
+also accepts integer numbers as argument:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>sqrt</b> <i>number</i>)</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+returns - the square root of <i>number</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:sqrt</font> (x)
+ (sqrt (float x)))
+</pre>
+
+<p>See <a href="../../reference/defun.htm">defun</a>,
+<a href="../../reference/float.htm">float</a>,
+<a href="../../reference/sqrt.htm">sqrt</a>.</p>
+
+The <nobr>cl:<b>sqrt</b></nobr> function computes the square root of its
+argument and returns the result. as a <nobr>floating-point</nobr>
+number.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/truncate.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/truncate.htm new file mode 100644 index 0000000..6032dd3 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/truncate.htm @@ -0,0 +1,135 @@ +<html><head>
+
+<title>cl:truncate</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:truncate</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>truncate</b></nobr> function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward zero:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>truncate</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of truncating the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the truncate operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:truncate</font> (number &optional (divisor (if (integerp number) 1 1.0)))
+ (let ((quotient (truncate (/ (float number) divisor))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The <nobr>cl:<b>truncate</b></nobr> function computes a quotient that has
+been truncated towards zero. <nobr>That is</nobr>, the quotient represents
+the mathematical integer of the same sign as the mathematical quotient, and
+that has the greatest integral magnitude not greater than that of the
+mathematical quotient.</p>
+
+<p>The quotient is directly returned by the function, while a list:</p>
+
+<pre class="example">
+(quotient remainder)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a> is set to
+<a href="../../reference/t.htm"> T </a> to signal that
+<a href="multiple-values.htm">Multiple Values</a> are returned.</p>
+
+<nobr>See
+<a href="rounding-and-truncation.htm">Rounding and Truncation</a></nobr>
+for more details.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:truncate 3.5) => 0 <font color="#008844">; *rslt* => ( 3 0.5)</font>
+(cl:truncate -3.5) => -3 <font color="#008844">; *rslt* => (-3 -0.5)</font>
+</pre>
+
+<p>Force an integer division:</p>
+
+<pre class="example">
+(cl:truncate 3.1 2.6) => 1 <font color="#008844">; *rslt* => (1 0.5)</font>
+(/ 3 2) => 1
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/values-list.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/values-list.htm new file mode 100644 index 0000000..52fa6e6 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/values-list.htm @@ -0,0 +1,113 @@ +<html><head>
+
+<title>cl:values-list</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:values-list</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>values-list</b></nobr> function returns the elements of a
+list unevaluated as multiple values:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>values-list</b> <i>list</i>)</dt>
+<dd><i>list</i> - a list of values<br>
+returns - the elements of the list as multiple values</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:values-list</font> (list)
+ (or (listp list) (error <font color="#880000">"not a list"</font> list))
+ (or (null list) (consp (last list)) (error <font color="#880000">"not a proper list"</font> list))
+ (setq <font color="#AA5500">*rslt*</font> list
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ (first list))
+</pre>
+
+<p>The unevaluated first value from the list is returned as the primary
+return value, and the list is assigned to the Nyquist
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable. <nobr>If
+an</nobr> an empty list is given, <a href="../../reference/nil.htm">NIL</a>
+is returned and the <a href="../../reference/global-rslt.htm">*rslt*</a>
+variable is set <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>.
+<nobr>An error</nobr> is signalled if the 'list' argument is not a list or
+if the list does not end
+<nobr>with <a href="../../reference/nil.htm">NIL</a></nobr>.</p>
+
+<p><nobr>The
+<a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable is set <nobr>to
+<a href="../../reference/t.htm"> T </a></nobr> to indicate that
+multiple values are returned.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:values-list nil) => NIL <font color="#008844">; *rslt* = NIL</font>
+(cl:values-list '(1)) => 1 <font color="#008844">; *rslt* = (1)</font>
+(cl:values-list '(1 2)) => 1 <font color="#008844">; *rslt* = (1 2)</font>
+(cl:values-list '(1 2 3)) => 1 <font color="#008844">; *rslt* = (1 2 3)</font>
+(cl:values-list '(1 2 . 3)) => <font color="#AA0000">error: not a proper list - (1 2 . 3)</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/values.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/values.htm new file mode 100644 index 0000000..92a828e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/values.htm @@ -0,0 +1,160 @@ +<html><head>
+
+<title>cl:values</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:values</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>values</b></nobr> function evaluates all given Lisp
+expressions and returns the results as multiple values:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>values</b> [<i>expr1</i> ...])</dt>
+<dd><i>exprN</i> - an arbitrary Lisp expression<br>
+returns - the results of evaluating the expressions, as multiple values</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:values</font> (&rest exprs)
+ (setq <font color="#AA5500">*rslt*</font> exprs
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ (first exprs))
+</pre>
+
+<p>The primary return value <nobr>[the result</nobr> from evaluating the
+first expression] is returned by the <nobr>cl:<b>values</b></nobr> function
+and a list with the results of evaluating all expressions is assigned to the
+Nyquist <a href="../../reference/global-rslt.htm">*rslt*</a> variable.
+<nobr>If no</nobr> expressions are given,
+<a href="..././reference/nil.htm">NIL</a> is returned and the
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable is set
+<nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>.</p>
+
+<p><nobr>The
+<a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable is set
+<nobr>to <a href="../../reference/t.htm"> T </a></nobr>
+to indicate that multiple values are returned.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:values 1 2 3) => 1 <font color="#008844">; primary value</font>
+*rslt* => (1 2 3) <font color="#008844">; all values</font>
+
+(cl:values 'a 'b) => A <font color="#008844">; primary value</font>
+*rslt* => (A B) <font color="#008844">; all values</font>
+
+> (cl:multiple-value-bind (a b c)
+ (cl:values 1 2 3)
+ (list a b c))
+(1 2 3)
+</pre>
+
+<p>See
+<nobr><a href="multiple-value-bind.htm">cl:multiple-value-bind</a></nobr>,
+<a href="../../reference/list.htm">list</a>,
+<a href="../../reference/global-rslt.htm">*rslt*</a>.</p>
+
+<p><div class="box">
+
+<p><b>Known Limitations</b></p>
+
+<p><b>1.</b> In Nyquist/XLISP, <nobr>cl:<b>values</b></nobr> cannot be
+used as argument to <a href="../../reference/setf.htm">setf</a>. <nobr>But
+this</nobr> is not a real problem, because the values are stored as a
+simple list in the <a href="../../reference/global-rslt.htm">*rslt*</a>
+variable, where they can be manipulated with any arbitrary Lisp
+functions, not only <nobr>with
+<a href="../../reference/setf.htm">setf</a></nobr>.</p>
+
+<p><b>2.</b> In <nobr>Common Lisp</nobr> there exists the option to return
+<nobr>'no value</nobr>' by calling the 'values' function with no arguments.
+<nobr>In Nyquist/XLISP</nobr> there is no <nobr>built-in</nobr> way to
+return '<nobr>no value</nobr>' from a function. <nobr>The symbol</nobr>
+<a href="../../reference/global-unbound.htm">*unbound*</a> cannot be used for
+this because in <nobr>Common Lisp</nobr>, if '<nobr>no value</nobr>' is
+assigned to a symbol as variable value, the new value will be
+<a href="../../reference/nil.htm">NIL</a> and not
+<a href="../../reference/global-unbound.htm">*unbound*</a>.</p>
+
+<p>In Nyquist/XLISP, the cl:<b>values</b> function, if called with no
+arguments, always returns <a href="../../reference/nil.htm">NIL</a>, and the
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable will be
+set <nobr>to <a href="../../reference/nil.htm">NIL</a>, too:</nobr></p>
+
+<pre class="example">
+(cl:values) => NIL <font color="#008844">; primary value</font>
+*rslt* => NIL <font color="#008844">; all values</font>
+
+(cl:values nil) => NIL <font color="#008844">; primary value</font>
+*rslt* => (NIL) <font color="#008844">; all values</font>
+</pre>
+
+<p>Maybe this observation helps to write a '<nobr>no values</nobr>' test if
+anybody really <nobr>needs it</nobr>.</p>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/environment.htm b/docsrc/xlisp/xlisp-doc/examples/environment.htm new file mode 100644 index 0000000..13a362d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/environment.htm @@ -0,0 +1,1001 @@ +<html><head>
+
+<title>Environment</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Environment</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#unbound">*unbound*</a></nobr></li>
+<li><nobr><a href="#lexical-environment">Lexical Environment</a></nobr></li>
+<ul>
+<li><nobr><a href="#getenv">getenv</a> - [Macro]</nobr></li>
+<li><nobr><a href="#eval-env">eval-env</a> - [Macro]</nobr></li>
+</ul>
+<li><nobr><a href="#lboundp">lboundp</a> - [Macro] - has this symbol a lexical variable value bound to it?</nobr></li>
+<ul>
+<li><nobr><a href="#valuep">valuep</a> - [Macro] - has this symbol a valid variable value bound to it?</nobr></li>
+</ul>
+<li><nobr><a href="#lfboundp">lfboundp</a> - [Macro] - has this symbol a lexical function value bound to it?</nobr></li>
+<li><nobr><a href="#lsymbol-value">lsymbol-value</a> - [Macro] - get the lexical variable value</nobr></li>
+<li><nobr><a href="#lsymbol-function">lsymbol-function</a> - [Macro] - get the lexical <a href="../reference/flet.htm">flet</a>, <a href="../reference/labels.htm">labels</a>, or <a href="../reference/macrolet.htm">macrolet</a> function value</nobr></li>
+<li><nobr><a href="#lmacroexpand-1">lmacroexpand-1</a> - [Macro] - expand the first level of a a <a href="../reference/macrolet.htm">macrolet</a> form</nobr></li>
+<li><nobr><a href="#known-problems">Known Problems</a></nobr></li>
+</ol>
+
+<a name="unbound"></a>
+
+<hr>
+
+<h2>*unbound*</h2>
+
+<hr>
+
+<p>A tricky problem with XLISP is that the symbol
+<a href="../reference/global-unbound.htm">*unbound*</a> can be bound as a
+value to any Lisp symbol, also to a lexical parameter variable if passed
+as a value to a Lisp function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">test</font> (x)
+ (print x))
+
+(test '*unbound*) => <font color="#880000">error: unbound variable</font>
+</pre>
+
+<p>The problem here is that the symbol
+<a href="../reference/global-unbound.htm">*unbound*</a> has been bound to
+the parameter variable 'x'</nobr>, so the expression <nobr>(print x)</nobr>
+instead of printing "*UNBOUND*" now causes an 'unbound variable'
+error. How can</nobr> I test from inside of a function if the lexical
+parameter variable 'x' is bound to the symbol
+<a href="../reference/global-unbound.htm">*unbound*</a>? Unfortunately there
+is no standard Lisp way to solve this problem.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="obarray"></a>
+
+<hr>
+
+<h2>*obarray*</h2>
+
+<hr>
+
+<p>A symbol in the *obarray* is protected from garbage collection.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lexical-environment"></a>
+
+<hr>
+
+<h2>Lexical Environment</h2>
+
+<hr>
+
+<p>Lisp parameter variables together with local variables bound with
+<a href="../reference/let.htm">let</a> and
+<a href="../reference/let-star.htm">let*</a> and functions defined by
+<a href="../reference/flet.htm">flet</a> and
+<a href="../reference/labels.htm">labels</a> are not interned in the
+<a href="../reference/global-obarray.htm">*obarray*</a>, instead they are
+stored in the local lexical environment, maintained via an internal
+association list. <nobr>The key</nobr> for reading this list is the
+<a href="../reference/global-evalhook.htm">*evalhook*</a> variable and the
+<a href="../reference/evalhook.htm">evalhook</a> function.</p>
+
+<p>Here are two Nyquist macros from 'evalenv.lsp':</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">getenv</font> () <font color="#008844">; return the current environment</font>
+ '(progv '(*evalhook*) (list #'(lambda (exp env) env))
+ (eval nil)))
+
+(defmacro <font color="#0000CC">eval-env</font> (arg) <font color="#008844">; evaluate in the current environment</font>
+ `(evalhook ,arg nil nil (getenv)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="getenv"></a>
+
+<hr>
+
+<h2>getenv</h2>
+
+<hr>
+
+<p>The 'getenv' macro returns the association list of the current lexical
+environment:</p>
+
+<pre class="example">
+(let ((<font color="#AA5500">v1</font> 1) <font color="#008844">; first variable</font>
+ (<font color="#AA5500">v2</font> 2)) <font color="#008844">; second variable</font>
+ (flet ((<font color="#0000CC">f1</font> (a) a) <font color="#008844">; first function</font>
+ (<font color="#0000CC">f2</font> (b) b)) <font color="#008844">; second function</font>
+ (getenv)))
+
+=> ((((<font color="#AA5500">V2</font> . <font color="#444444">1</font>) (<font color="#AA5500">V1</font> . <font color="#444444">2</font>))) ((<font color="#0000CC">F2</font> . <font color="#444444">#<Closure...></font>) (<font color="#0000CC">F1</font> . <font color="#444444">#<Closure...></font>)))
+</pre>
+
+<p>The asymmetric layout is produced by
+<a href="../reference/print.htm">print</a>, the real structure of the
+lexical environment is a <a href="../reference/cons.htm">cons</a> of two
+association lists:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">print-env</font> ()
+ (let ((env (gensym)))
+ `(let ((,env (getenv)))
+ (format t <font color="#880000">"(~s . ~s)~%"</font> (car ,env) (cdr ,env)))))
+</pre>
+
+<p><b>Note:</b> You could also use
+<a href="lists.htm#print-cons">print-cons</a> instead of
+<a href="../reference/format.htm">format</a> to print really all the
+details of the list, but <a href="../reference/format.htm">format</a> is
+enough for the examples here.</p>
+
+<pre class="example">
+(let ((<font color="#AA5500">v1</font> 1) <font color="#008844">; first variable</font>
+ (<font color="#AA5500">v2</font> 2)) <font color="#008844">; second variable</font>
+ (flet ((<font color="#0000CC">f1</font> (a) a) <font color="#008844">; first function</font>
+ (<font color="#0000CC">f2</font> (b) b)) <font color="#008844">; second function</font>
+ (print-env)))
+
+((((<font color="#AA5500">V2</font> . <font color="#444444">2</font>) (<font color="#AA5500">V1</font> . <font color="#444444">1</font>))) . (((<font color="#0000CC">F2</font> . <font color="#444444">#<Closure...></font>) (<font color="#0000CC">F1</font> . <font color="#444444">#<Closure...></font>))))
+</pre>
+
+<p>The basic <nobr>layout is</nobr>:</p>
+
+<pre class="example">
+((((<font color="#AA5500">V2</font> . value) (<font color="#AA5500">V1</font> . value))) . (((<font color="#0000CC">F2</font> . value) (<font color="#0000CC">F1</font> . value))))
+
+<font color="#444444">((<----- <font color="#AA5500">variable-list</font> ----->) . (<----- <font color="#0000CC">function-list</font> ----->))</font>
+
+(car (getenv)) => (<font color="#AA5500">variable-list</font>)
+(cdr (getenv)) => (<font color="#0000CC">function-list</font>)
+</pre>
+
+<p>The different levels of bindings are maintained via multiple
+sublists:</p>
+
+<pre class="example">
+(let ((<font color="#AA5500">v1</font> 1)) <font color="#008844">; first level variable</font>
+ (let ((<font color="#AA5500">v2</font> 2)) <font color="#008844">; second level variable</font>
+ (flet ((<font color="#0000CC">f1</font> (a) a)) <font color="#008844">; first level function</font>
+ (flet ((<font color="#0000CC">f2</font> (b) b)) <font color="#008844">; second level function</font>
+ (print-env)))))
+
+((((<font color="#AA5500">V2</font> . value)) ((<font color="#AA5500">V1</font> . value))) . (((<font color="#0000CC">F2</font> . value)) ((<font color="#0000CC">F1</font> . value))))
+
+<font color="#444444">(((<--<font color="#AA5500">level2</font>-->) (<--<font color="#AA5500">level1</font>-->)) . ((<--<font color="#0000CC">level2</font>-->) (<--<font color="#0000CC">level1</font>-->)))</font>
+<font color="#444444">((<------ <font color="#AA5500">variable-list</font> ------>) . (<------ <font color="#0000CC">function-list</font> ------>))</font>
+</pre>
+
+<p>Variables appear always in the variable list, functions always in the
+function list:</p>
+
+<pre class="example">
+(let ((<font color="#AA5500">v1</font> 1)) <font color="#008844">; first level variable</font>
+ (flet ((<font color="#0000CC">f1</font> (a) a)) <font color="#008844">; first level function</font>
+ (let ((<font color="#AA5500">v2</font> 2)) <font color="#008844">; second level variable</font>
+ (flet ((<font color="#0000CC">f2</font> (b) b)) <font color="#008844">; second level function</font>
+ (print-env)))))
+
+((((<font color="#AA5500">V2</font> . value)) ((<font color="#AA5500">V1</font> . value))) . (((<font color="#0000CC">F2</font> . value)) ((<font color="#0000CC">F1</font> . value))))
+
+<font color="#444444">(((<--<font color="#AA5500">level2</font>-->) (<--<font color="#AA5500">level1</font>-->)) . ((<--<font color="#0000CC">level2</font>-->) (<--<font color="#0000CC">level1</font>-->)))</font>
+<font color="#444444">((<------ <font color="#AA5500">variable-list</font> ------>) . (<------ <font color="#0000CC">function-list</font> ------>))</font>
+</pre>
+
+<p>The <nobr>inner-most</nobr> bindings always appear at the front of the
+lists:</p>
+
+<pre class="example">
+(let ((<font color="#AA5500">v1</font> 1)) <font color="#008844">; first level variable</font>
+ (let ((<font color="#AA5500">v2</font> 2)) <font color="#008844">; second level variable</font>
+ (flet ((<font color="#0000CC">f1</font> (a) a)) <font color="#008844">; first level function</font>
+ (flet ((<font color="#0000CC">f2</font> (b) b)) <font color="#008844">; second level function</font>
+ (let ((<font color="#AA5500">v3</font> 3)) <font color="#008844">; third level variable</font>
+ (print-env))))))
+
+((((<font color="#AA5500">V3</font> . value)) ((<font color="#AA5500">V2</font> . value)) ((<font color="#AA5500">V1</font> . value))) . (((<font color="#0000CC">F2</font> . value)) ((<font color="#0000CC">F1</font> . value))))
+
+<font color="#444444">(((<--<font color="#AA5500">level3</font>-->) (<--<font color="#AA5500">level2</font>-->) (<--<font color="#AA5500">level1</font>-->)) . ((<--<font color="#0000CC">level2</font>-->) (<--<font color="#0000CC">level1</font>-->)))</font>
+<font color="#444444">((<------------- <font color="#AA5500">variable-list</font> -------------->) . (<------ <font color="#0000CC">function-list</font> ------>))</font>
+</pre>
+
+<p>There may appear several variable bindings in the same sublist:</p>
+
+<pre class="example">
+(let ((<font color="#AA5500">v1</font> 1) (<font color="#AA5500">v2</font> 2)) <font color="#008844">; first level variables</font>
+ (flet ((<font color="#0000CC">f1</font> (a) a) <font color="#008844">; first level functions</font>
+ (<font color="#0000CC">f2</font> (b) b))
+ (let ((<font color="#AA5500">v3</font> 3)) <font color="#008844">; second level variable</font>
+ (print-env))))
+
+((((V3 . value)) ((V2 . value) (V1 . value))) . (((F2 . value) (F1 . value))))
+
+<font color="#444444">(((<--<font color="#AA5500">level2</font>-->) (<--------<font color="#AA5500">level1</font>--------->)) . ((<---------<font color="#0000CC">level1</font>-------->)))</font>
+<font color="#444444">((<------------ <font color="#AA5500">variable-list</font> ------------->) . (<----- <font color="#0000CC">function-list</font> ----->))</font>
+</pre>
+
+<p>The basic principle is always the same:</p>
+
+<pre class="example">
+(((<font color="#AA5500">level n</font> <font color="#008844">...</font>) <font color="#008844">...</font> (<font color="#AA5500">level 1 variables</font>)) . ((<font color="#0000CC">level n</font> <font color="#008844">...</font>) <font color="#008844">...</font> (<font color="#0000CC">level 1 functions</font>)))
+
+(car (getenv)) => ((<font color="#AA5500">level n</font> <font color="#008844">...</font>) (<font color="#AA5500">level n-1</font> <font color="#008844">...</font>) <font color="#008844">...</font> (<font color="#AA5500">level 1 variables</font>))
+(cdr (getenv)) => ((<font color="#0000CC">level n</font> <font color="#008844">...</font>) (<font color="#0000CC">level n-1</font> <font color="#008844">...</font>) <font color="#008844">...</font> (<font color="#0000CC">level 1 functions</font>))
+</pre>
+
+<p>Also the function parameter variables appear in the the lexical
+environment association list:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">test</font> (<font color="#AA0000">parameter-var</font>)
+ (let ((<font color="#AA5500">local-var</font> 'value))
+ (print-env)))
+
+((((<font color="#AA5500">LOCAL-VAR</font> . value)) ((<font color="#AA0000">PARAMETER-VAR</font> . value))) . NIL) <font color="#008844">; NIL = no functions</font>
+
+<font color="#444444">(((<-----<font color="#AA5500">level2</font>------>) (<-------<font color="#AA5500">level1</font>-------->)) . NIL)</font>
+<font color="#444444">((<--------------- <font color="#AA5500">variable-list</font> --------------->) . NIL)</font>
+</pre>
+
+<p>The variables bound by <a href="../reference/let.htm">let</a> appear
+before the function's parameter variables, that's why
+<a href="../reference/let.htm">let</a> bindings 'shadow' parameter variables
+with the same name. <nobr>The 'test'</nobr> function name does not appear in
+the environment list because the function name was
+<a href="../reference/intern.htm">intern</a>ed in the
+<a href="../reference/global-obarray.htm">*obarray*</a> by
+<a href="../reference/defun.htm">defun</a>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="eval-env"></a>
+
+<hr>
+
+<h2>eval-env</h2>
+
+<hr>
+
+<p>This still doen't work:</p>
+
+<pre class="example">
+(setq x 'global) ; define a global variable 'x'
+
+(defun print-x () ; define a function PRINT-X in the global environment
+ (print (getenv)) ; always prints ((NIL)), also with EVAL-ENV or EVALHOOK
+ (print x)) ; always prints GLOBAL, also with EVAL-ENV or EVALHOOK
+
+(let ((x 'local)) ; create a lexical variable 'x'
+ (print-x)) ; evaluate PRINT-X
+=> GLOBAL ; value from the environment, where PRINT-X was defined
+
+(let ((x 'local)) ; create a lexical variable 'x'
+ (eval-env (print-x)) ; evaluate PRINT-X in the current environment
+=> GLOBAL ;wrong ; value from the environment, where PRINT-X was called
+
+(let ((x 'local)) ; create a lexical variable 'x'
+ (eval-env (funcall 'print-x)) ; evaluate PRINT-X in the current environment
+=> GLOBAL ;wrong ; value from the environment, where PRINT-X was called
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lboundp"></a>
+
+<hr>
+
+<h2>lboundp</h2>
+
+<hr>
+
+<p>The 'lboundp' function tests if a valid variable value is bound to a
+symbol in the current lexical environment:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>lboundp</b> <i>symbol</i>)</dt>
+<dd><i>symbol</i> - a quoted lisp symbol<br>
+returns - <a href="../reference/t.htm"> T </a> if a lexical
+variable value is bound to the symbol, <a href="../reference/nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">lboundp</font> (symbol)
+ (cond ((not (or (symbolp symbol)
+ (and (consp symbol)
+ (eq 'quote (car symbol))
+ (symbolp (cadr symbol)))))
+ (error <font color="#880000">"bad argument type"</font> symbol))
+ ((and (consp symbol) (cddr symbol))
+ (error <font color="#880000">"too many arguments"</font>))
+ (t (let ((a-cons (gensym)) (level (gensym)) (binding (gensym)))
+ `(let ((,a-cons (dolist (,level (car (getenv)) nil)
+ (let ((,binding (assoc ,symbol ,level)))
+ (when ,binding (return ,binding))))))
+ (and ,a-cons (not (eq (cdr ,a-cons) '<font color="#AA5500">*unbound*</font>))))))))
+</pre>
+
+<p>The XLISP <a href="../reference/boundp.htm">boundp</a> function only
+can test global variables, interned in the
+<a href="../reference/global-obarray.htm">*obarray*</a>, so it cannot be
+used to test if a symbol has a variable value bound to it in the lexical
+environment:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">test</font> (x) <font color="#008844">; bad example</font>
+ (if (boundp 'x) <font color="#AA0000">; <- global test</font>
+ (print x)
+ (print '*unbound*)))
+
+(test 'hello!) => *UNBOUND* <font color="#AA0000">; bad result</font>
+(test 123) => *UNBOUND* <font color="#AA0000">; bad result</font>
+
+(setq x t) => T <font color="#008844">; create a global variable 'x'</font>
+
+(test 'hello!) => 'HELLO! <font color="#008844">; OK</font>
+(test 123) => 123 <font color="#008844">; OK</font>
+(test '*unbound*) => <font color="#AA0000">error: unbound variable - X ; bad result</font>
+</pre>
+
+<p>Here the same example with 'lboundp':</p>
+
+<pre class="example">
+(defun <font color="#0000CC">test</font> (x) <font color="#008844">; good example</font>
+ (if (lboundp 'x) <font color="#008844">; <- local test</font>
+ (print x)
+ (print '*unbound*)))
+
+(test 'hello!) => 'HELLO! <font color="#008844">; OK</font>
+(test 123) => 123 <font color="#008844">; OK</font>
+(test '*unbound*) => *UNBOUND* <font color="#008844">; OK</font>
+</pre>
+
+<p>The 'lboundp' function cannot test symbol values at the
+<nobr>top-level</nobr>, because there is no lexical environment:</p>
+
+<pre class="example">
+(setq x t) => T <font color="#008844">; create a global variable 'x'</font>
+(lboundp 'x) => NIL <font color="#AA0000">; lexical test fails</font>
+(boundp 'x) => T <font color="#008844">; global test succeeds</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="valuep"></a>
+
+<hr>
+
+<h2>valuep</h2>
+
+<hr>
+
+<p>The 'valuep' function tests if a valid variable value is bound to a
+symbol at any level:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">valuep</font> (symbol)
+ (cond ((not (or (symbolp symbol)
+ (and (consp symbol)
+ (eq 'quote (car symbol))
+ (symbolp (cadr symbol)))))
+ (error <font color="#880000">"bad argument type"</font> ,symbol))
+ ((and (consp symbol) (cddr symbol))
+ (error <font color="#880000">"too many arguments"</font>))
+ (t (let ((a-cons (gensym)) (level (gensym)) (binding (gensym)))
+ `(let ((,a-cons (dolist (,level (car (getenv)) nil)
+ (let ((,binding (assoc ,symbol ,level)))
+ (when ,binding (return ,binding))))))
+ (if ,a-cons
+ (not (eq (cdr ,a-cons) '<font color="#AA5500">*unbound*</font>))
+ (boundp ,symbol)))))))
+</pre>
+
+<p>It's tricky to test if a symbol has a valid variable value bound to
+it because if the symbol is bound to
+<a href="../reference/global-unbound.htm">*unbound*</a> in a lexical
+environment, it still shadows a symbol with the same name in the
+<a href="../reference/global-obarray.htm">*obarray*</a>, making a possibly
+existing global variable inaccessible, like shown in the examples
+below.</p>
+
+<p><b>Note:</b> The lexical environment must be tested first, because this
+is the way how XLISP searches for symbol bindings.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(when (valuep 'x) x) => NIL <font color="#008844">; no global binding of 'x' found</font>
+(setq x 'ok) => OK <font color="#008844">; create a global variable 'x'</font>
+(when (valuep 'x) x) => OK <font color="#008844">; global binding of 'x' found</font>
+
+(let ((x 'local)) <font color="#008844">; create a lexical variable 'x'</font>
+ (when (valuep 'x) x)) <font color="#008844">; try to access the lexical variable</font>
+=> LOCAL <font color="#008844">; lexical binding of 'x' found</font>
+</pre>
+
+<p>XLISP problems with
+<a href="../reference/global-unbound.htm">*unbound*</a>
+lexical variables:</p>
+
+<pre class="example">
+(setq x 'ok) => OK <font color="#008844">; create a global variable 'x'</font>
+(when (valuep 'x) x) => OK <font color="#008844">; global binding of 'x' found</font>
+
+(let ((x '*unbound*)) <font color="#008844">; create an unbound lexical variable 'x'</font>
+ (when (valuep 'x) x)) <font color="#008844">; try to access the global variable</font>
+=> <font color="#AA0000">NIL ; global binding of 'x' NOT found</font>
+
+(let ((x '*unbound*)) <font color="#008844">; create an unbound lexical variable 'x'</font>
+ x) <font color="#008844">; try to access the global variable</font>
+<font color="#AA0000">error: unbound variable - X</font>
+</pre>
+
+<p>The 'valuep' function recognizes if a global variable value is shadowed
+by an <a href="../reference/global-unbound.htm">*unbound*</a> lexical
+variable and returns NIL if the global variable is inaccessible..</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lfboundp"></a>
+
+<hr>
+
+<h2>lfboundp</h2>
+
+<hr>
+
+<p>The 'lfboundp' function tests if a valid function value is bound to a
+symbol in the current lexical environment:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>lfboundp</b> <i>symbol</i>)</dt>
+<dd><i>symbol</i> - a quoted lisp symbol<br>
+returns - <a href="../reference/t.htm"> T </a> if a lexical
+function value is bound to the symbol, <a href="../reference/nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">lfboundp</font> (symbol)
+ (cond ((not (or (symbolp symbol)
+ (and (consp symbol)
+ (eq 'quote (car symbol))
+ (symbolp (cadr symbol)))))
+ (error <font color="#880000">"bad argument type"</font> symbol))
+ ((and (consp symbol) (cddr symbol))
+ (error <font color="#880000">"too many arguments"</font>))
+ (t (let ((a-cons (gensym)) (level (gensym)) (binding (gensym)))
+ `(let ((,a-cons (dolist (,level (cdr (getenv)) nil)
+ (let ((,binding (assoc ,symbol ,level)))
+ (when ,binding (return ,binding))))))
+ (and ,a-cons (not (eq (cdr ,a-cons) '<font color="#AA5500">*unbound*</font>))))))))
+</pre>
+
+<p>The XLISP <a href="../reference/fboundp.htm">fboundp</a> function only
+works with symbols interned in the
+<a href="../reference/global-obarray.htm">*obarray*</a>, so it cannot be
+used to test if a symbol has a function value bound to it in the lexical
+environment:</p>
+
+<pre class="example">
+(flet ((my-function (x) 'hello))
+ (fboundp 'my-function)) <font color="#AA0000">; <- global test</font>
+=> NIL
+
+(flet ((my-function (x) 'hello))
+ (lfboundp 'my-function)) <font color="#008844">; <- local test</font>
+=> T
+</pre>
+
+<p>The 'lfboundp' function cannot test symbol function values at the
+<nobr>top-level</nobr>, because there is no lexical environment:</p>
+
+<pre class="example">
+(lfboundp 'car) => NIL <font color="#AA0000">; lexical test fails</font>
+(fboundp 'car) => T <font color="#008844">; global test succeeds</font>
+</pre>
+
+<p>Problems with <a href="../reference/global-unbound.htm">*unbound*</a>
+lexical functions are less likely then with
+<a href="../reference/global-unbound.htm">*unbound*</a> parameter
+variables, because there is no <nobr>buit-in</nobr> way to bind a lexical
+function to <a href="../reference/global-unbound.htm">*unbound*</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr><a href="predicates.htm#subrp">suprp</a> - is this a built-in function?</nobr></li>
+<li><nobr><a href="predicates.htm#fsubrp">fsubrp</a> - is this a built-in special form?</nobr></li>
+<li><nobr><a href="predicates.htm#closurep">closurep</a> - is this a user-defined function or macro?</nobr></li>
+<li><nobr><a href="predicates.htm#functionp">functionp</a> - is this a build-in or a user-defined function?</nobr></li>
+<li><nobr><a href="predicates.htm#macrop">macrop</a> - is this a user-defined macro?</nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lsymbol-value"></a>
+
+<hr>
+
+<h2>lsymbol-value</h2>
+
+<hr>
+
+<p>The function 'lsymbol-value' returns a variable value from the lexical
+environment:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">lsymbol-value</font> (symbol)
+ (cond ((not (or (symbolp symbol)
+ (and (consp symbol)
+ (eq 'quote (car symbol))
+ (symbolp (cadr symbol)))))
+ (error <font color="#880000">"bad argument type"</font> symbol))
+ ((and (consp ,symbol) (cddr symbol))
+ (error <font color="#880000">"too many arguments"</font>))
+ (t (let ((a-cons (gensym)) (level (gensym)) (binding (gensym)))
+ `(let ((,a-cons (dolist (,level (car (getenv)) nil)
+ (let ((,binding (assoc ,symbol ,level)))
+ (when ,binding (return ,binding))))))
+ (when ,a-cons
+ (if (eq (cdr ,a-cons) '<font color="#AA5500">*unbound*</font>)
+ '*unbound*
+ (cdr ,a-cons))))))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lsymbol-function"></a>
+
+<hr>
+
+<h2>lsymbol-function</h2>
+
+<hr>
+
+<p>The function 'lsymbol-function' returns a function value from the lexical
+environment:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">lsymbol-function</font> (symbol)
+ (cond ((not (or (symbolp symbol)
+ (and (consp symbol)
+ (eq 'quote (car symbol))
+ (symbolp (cadr symbol)))))
+ (error <font color="#880000">"bad argument type"</font> symbol))
+ ((and (consp symbol) (cddr symbol))
+ (error <font color="#880000">"too many arguments"</font>))
+ (t (let ((a-cons (gensym)) (level (gensym)) (binding (gensym)))
+ `(let ((,a-cons (dolist (,level (cdr (getenv)) nil)
+ (let ((,binding (assoc ,symbol ,level)))
+ (when ,binding (return ,binding))))))
+ (when ,a-cons
+ (if (eq (cdr ,a-cons) '<font color="#AA5500">*unbound*</font>)
+ '*unbound*
+ (cdr ,a-cons))))))))
+</pre>
+
+<p>The XLISP function
+<nobr><a href="../reference/symbol-function.htm">symbol-function</a></nobr>
+only works with symbols interned in the
+<a href="../reference/global-obarray.htm">*obarray*</a>, so it cannot return
+a function value, bound to a symbol in the lexical environment:</p>
+
+<pre class="example">
+(flet ((my-function (x) 'hello))
+ (symbol-function 'my-function)) <font color="#AA0000">; <- searches the *obarray*</font>
+=> <font color="#AA0000">error: unbound function - MY-FUNCTION</font>
+
+(flet ((my-function (x) 'hello))
+ (lsymbol-function 'my-function)) <font color="#008844">; <- searches the lexical environment</font>
+=> #<Closure-MY-FUNCTION...>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lmacroexpand-1"></a>
+
+<hr>
+
+<h2>lmacroexpand-1</h2>
+
+<hr>
+
+<pre class="example">
+(defmacro <font color="#0000CC">with-static-env</font> (&rest body)
+ (let ((env (gensym)) (rval (gensym)))
+ `(let ((,env (getenv))) <font color="#008844">; environment snapshot</font>
+ (progv '(*evalhook*)
+ '((lambda (exp env)
+ (labels ((,rval (exp env) <font color="#008844">; recursive eval</font>
+ (format t "exp: ~a env: ~a ,env: ~a~%" exp env ,env)
+ (evalhook exp #',rval NIL ,env)))
+ (format t "exp: ~a env: ~a ,env: ~a~%" exp env ,env)
+ (evalhook exp #',rval NIL ,env))))
+ ,@body))))
+</pre>
+
+<pre class="example">
+(defmacro <font color="#0000CC">with-dynamic-env</font> (&rest body)
+ (let ((env (gensym)) (rval (gensym)))
+ `(let ((,env (getenv))) <font color="#008844">; environment snapshot</font>
+ (progv '(*evalhook*)
+ '((lambda (exp env)
+ (labels ((,rval (exp env) <font color="#008844">; recursive eval</font>
+ (format t "inner exp: ~a env: ~a~%" exp env)
+ (evalhook exp #',rval NIL env)))
+ (format t "outer exp: ~a env: ~a~%" exp env)
+ (evalhook exp #',rval NIL env))))
+ ,@body))))
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">display-env</font> (env &optional (exp nil exp-p))
+ (flet ((display-bindings (name bindings)
+ (format t <font color="#880000">" ~a bindings: ~s~%"</font> name bindings)
+ (let ((frame-counter 1))
+ (dolist (frame bindings)
+ (format t <font color="#880000">" ~a frame ~a: ~a~%"</font> name frame-counter frame)
+ (let ((binding-counter 1))
+ (dolist (binding frame)
+ (when (consp binding)
+ (format t <font color="#880000">" ~a ~a: ~s - value: ~s~%"</font>
+ name binding-counter (car binding) (cdr binding))
+ (incf binding-counter))))
+ (incf frame-counter)))))
+ (when exp-p (format t <font color="#880000">"eval: ~s~%"</font> exp))
+ (format t <font color="#880000">"environment: ~s~%"</font> env)
+ (display-bindings <font color="#880000">"variable"</font> (car env))
+ (display-bindings <font color="#880000">"function"</font> (cdr env))))
+
+(defmacro <font color="#0000CC">debug:env</font> ()
+ '(progv '(*evalhook*) '(nil)
+ (display-env (getenv))))
+
+(defmacro <font color="#0000CC">debug:env</font> ()
+ '(progv '(*evalhook*) '((lambda (exp env)
+ (display-env env)))
+ (eval nil)))
+
+(defmacro <font color="#0000CC">debug:env</font> (&rest body)
+ (when *evalhook*
+ (format t "DEBUG:ENV ")
+ (format t "*evalhook* was already modified~%"))
+ (if (null body)
+ '(progv '(<font color="#AA5500">*evalhook*</font>) '((lambda (exp env)
+ (display-env env)))
+ (eval nil))
+ (let ((init (gensym)) (rval (gensym)))
+ `(let ((,init (getenv))) <font color="#008844">; environment snapshot</font>
+ (progv '(<font color="#AA5500">*evalhook*</font>)
+ '((lambda (exp env)
+ (labels ((,rval (exp env) <font color="#008844">; recursive eval</font>
+ (display-env env exp)
+ (evalhook exp #',rval nil env)))
+ (display-env ,init exp)
+ (evalhook exp #',rval nil ,init))))
+ ,@body)))))
+
+(defmacro <font color="#0000CC">with-evalhook</font> (&rest body)
+ (let ((init (gensym)) (rval (gensym)) (hook (gensym)) debug)
+ `(let ((,init (getenv))) <font color="#008844">; environment snapshot</font>
+ (progv '(<font color="#AA5500">*evalhook*</font>)
+ '((lambda (exp env)
+ (labels ((,rval (exp env) <font color="#008844">; recursive eval</font>
+ ,(print *evalhook*)
+ ,(when T `(funcall ,*evalhook* exp env))
+
+ (evalhook exp #',rval nil env)))
+ (evalhook exp #',rval nil ,init))))
+ ,@body))))
+
+(defmacro <font color="#0000CC">with-current-environment</font> (&rest body)
+ (when <font color="#AA5500">*evalhook*</font> (error <font color="#880000">"*evalhook* already modified"</font>))
+ (let ((init (gensym)) (rval (gensym)) debug)
+ (when (eq :debug (car body)) (setq debug t body (cdr body)))
+ `(let ((,init (getenv))) <font color="#008844">; environment snapshot</font>
+ (progv '(<font color="#AA5500">*evalhook*</font>)
+ '((lambda (exp env)
+ (labels ((,rval (exp env) <font color="#008844">; recursive eval</font>
+ <font color="#008844">;; append environment from snapshot</font>
+ (setq env (cons (append (car env) (car ,init))
+ (append (cdr env) (cdr ,init))))
+ ,(when debug '(display-env env exp))
+ (evalhook exp #',rval nil env)))
+ <font color="#008844">;; start with environment snapshot</font>
+ ,(when debug `(display-env ,init exp))
+ (evalhook exp #',rval nil ,init))))
+ ,@body))))
+
+(defmacro <font color="#0000CC">with-env</font> (&rest body)
+ (let ((init (gensym)) (rval (gensym)))
+ `(let ((,init (getenv))) <font color="#008844">; environment snapshot</font>
+ (progv '(*evalhook*)
+ '((lambda (exp env)
+ (labels ((,rval (exp env) <font color="#008844">; recursive eval</font>
+ (display-env env exp)
+ (evalhook exp #',rval nil env)))
+ (display-env ,init exp)
+ (evalhook exp #',rval nil ,init))))
+ ,@body))))
+</pre>
+
+<pre class="example">
+(with-current-environment
+ (debug:env
+ body))
+
+(progv '(*evalhook)
+ '((lambda (exp env)
+ (labels ((rval (exp env)
+ (append-current-environment)
+ (debug:env ...)
+ (evalhook exp #'rval nil env)))
+ (evalhook exp #'rval nil init)))))
+
+(debug:env
+ (with-current-environment
+ body))
+
+(progv '(*evalhook)
+ '((lambda (exp env)
+ (labels ((rval (exp env)
+</pre>
+
+<pre class="example">
+(defmacro <font color="#0000CC">with-current-environment</font> (&rest body)
+ (when <font color="#AA5500">*evalhook*</font> (error <font color="#880000">"*evalhook* already modified"</font>))
+ (let ((debug nil) (init (gensym)) (rval (gensym)))
+ (when (eq :debug (car body)) (setq debug t body (cdr body)))
+ `(let ((,init (getenv))) <font color="#008844">; environment snapshot</font>
+ (progv '(<font color="#AA5500">*evalhook*</font>)
+ '((lambda (exp env)
+ (labels ((,rval (exp env) <font color="#008844">; recursive eval</font>
+ ,(cond (debug
+ `(setq env
+ (cons (append (car env) (car ,init))
+ (append (cdr env) (cdr ,init))))
+ '(display-env env exp)
+ `(evalhook exp #',rval nil env))
+ (t
+ `(evalhook exp #',rval nil
+ (cons (append (car env) (car ,init))
+ (append (cdr env) (cdr ,init))))))))
+ ,(when debug `(display-env ,init exp))
+ (evalhook exp #',rval nil ,init))))
+ ,@body))))
+</pre>
+
+<pre class="example">
+(setq *rvalhook* nil)
+
+(defmacro <font color="#0000CC">with-current-environment</font> (&rest body)
+ (let ((init (gensym)))
+ `(let ((,init (getenv)))
+ (rval-env #'(lambda (exp env)
+ (cons exp (cons (append (car env) (car ,init))
+ (append (cdr env) (cdr ,init)))))
+ ,@body))))
+
+(defmacro debug:env (&rest body)
+ (rval-env #'(lambda (exp env)
+ (display-env env exp)
+ (cons exp env))
+ ,@body))
+
+(defmacro <font color="#0000CC">run-rvalhooks</font> ()
+ (let ((func (gensym)) (result (gensym)))
+ `(dolist (,func <font color="#AA5500">*rvalhook*</font>)
+ (format t "func: ~a~%" ,func)
+ (format t "exp: ~a~%" exp)
+ (format t "env: ~a~%" env)
+ (let ((,result (eval (list ,func 'exp 'env) )))
+ (format t "result: ~a~%" ,result)
+ (format t "exp: ~a~%" exp)
+ (format t "car: ~a~%" (car ,result))
+ (format t "env: ~a~%" env)
+ (format t "cdr: ~a~%" (cdr ,result))
+ (setq exp (car ,result) env (cdr ,result))
+ ))))
+
+(defmacro <font color="#0000CC">rval-env</font> (function &rest body)
+ (format t "function: ~a~%" function)
+ (format t "body: ~a~%" body)
+ (or <font color="#AA5500">*evalhook*</font> (setq <font color="#AA5500">*rvalhook*</font> nil))
+ (format t "*rvalhook*: ~a~%" *rvalhook*)
+ (if <font color="#AA5500">*rvalhook*</font>
+ `(prog2
+ (push ,function <font color="#AA5500">*rvalhook*</font>)
+ (progn ,@body)
+ (setq <font color="#AA5500">*rvalhook*</font> (remove ,function <font color="#AA5500">*rvalhook*</font>)))
+ (let ((rval (gensym)) (func (gensym)) (result (gensym)))
+ `(prog2
+ (push ,function <font color="#AA5500">*rvalhook*</font>)
+ (progv '(<font color="#AA5500">*evalhook*</font>)
+ `((lambda (exp env)
+ (print 'hallo)
+ (labels ((,rval (exp env)
+ (run-rvalhooks)
+ (evalhook exp #',rval nil env)))
+ ; (run-rvalhooks)
+ (evalhook exp #',rval nil env))))
+ ,@body)
+ (setq <font color="#AA5500">*rvalhook*</font> (remove ,function <font color="#AA5500">*rvalhook*</font>))))))
+</pre>
+
+<p>*rvalhook* must be a list of functions, each taking two arguments 'exp'
+[the Lisp expressions to evaluate] and 'env' [the environment], returning
+a cons of the format <nobr>(exp . env)</nobr>.</p>
+
+<p>In case of an error, the
+<a href="../reference/global-evalhook.htm">*evalhook*</a> variable is
+automatically reset by the XLISP
+<nobr><a href="../reference/top-level.htm">top-level</a></nobr> function.
+This means that if <a href="../reference/global-evalhook.htm">*evalhook*</a>
+is <a href="../reference/nil.htm">NIL</a> and *rvalhook* is
+<nobr>non-<a href="../reference/nil.htm">NIL</a></nobr>, then *rvalhook* is
+invalid and must also be reset to <a href="../reference/nil.htm">NIL</a>
+before pushing the next function <nobr>on it</nobr>.</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">lmacroexpand-1</font> (form)
+ (if (not (and (consp form)
+ (eq 'quote (car form))
+ (symbolp (caadr form))))
+ form <font color="#008844">; if the form isn't '(symbol ... )</font>
+ (let ((a-cons (gensym)) (l-expr (gensym)))
+ `(let ((,a-cons (assoc ',(caadr form) (cadr (getenv)))))
+ (if (null ,a-cons) <font color="#008844">; (caadr form) = macro-name</font>
+ ,form <font color="#008844">; if no lexical binding was found</font>
+ (let ((,l-expr (get-lambda-expression (cdr ,a-cons))))
+ (if (eq 'macro (car ,l-expr)) <font color="#008844">; if l-expr is a macro</font>
+ (with-current-environment
+ <font color="#008844">;; create an *unbound* macro in the *obarray*</font>
+ (eval (append '(defmacro *unbound*) (cdr ,l-expr)))
+ <font color="#008844">;; expand the macro in the current environment</font>
+ (eval (list 'macroexpand-1 <font color="#008844">; (cdadr form) =</font>
+ (list 'quote <font color="#008844">; macro-arguments as list</font>
+ (cons '*unbound* ',(cdadr form))))))
+ ,form))))))) <font color="#008844">; if l-expr is not a macro</font>
+</pre>
+
+<pre class="example">
+(let ((x 1))
+ (macrolet ((test (arg)
+ `(progn
+ (print ,arg)
+ (print ,(eval x)))))
+ (lmacroexpand-1 '(test 'hallo))))
+=>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="known-problems"></a>
+
+<hr>
+
+<h2>Known Problems</h2>
+
+<hr>
+
+<p>A lexical variable with the symbol
+<a href="../reference/global-unbound.htm">*unbound*</a> as a variable value
+bound to it will continue to shadow a global variable with the same name,
+even if the the lexical variable is 'unbound':</p>
+
+<pre class="example">
+(setq x t) => T <font color="#008844">; create a global variable 'x'</font>
+
+(let ((x '*unbound*)) <font color="#008844">; create an unbound lexical variable 'x'</font>
+ (print x)) <font color="#008844">; try to print the global variable</font>
+<font color="#AA0000">error: unbound variable - X</font>
+</pre>
+
+<p>Tested with <nobr>Nyquist 3.03</nobr> in <nobr>December 2010</nobr>.</p>
+
+<p><b>Nyquist Bug:</b> let* causes infinite recursion problems with either
+progv, evalhook, or *evalhook* [still needs more investigation], so this
+doesnt work:</p>
+
+<pre class="example">
+(let* ((init (getenv)))
+ (progv '(*evalhook*)
+ '((lambda (exp env)
+ (labels ((rval (exp env)
+ (print init) <font color="#AA0000">; <- causes infinite recursion</font>
+ (evalhook exp #'rval nil env)))
+ (evalhook exp #'rval nil init))))
+ (eval nil)))
+=> <font color="#AA0000">infinite recursion</font>
+</pre>
+
+while exactly the same form using let instead of let* works:
+
+<pre class="example">
+(let ((init (getenv)))
+ (progv '(*evalhook*)
+ '((lambda (exp env)
+ (labels ((rval (exp env)
+ (print init) <font color="#008844">; <- no infinite recursion</font>
+ (evalhook exp #'rval nil env)))
+ (evalhook exp #'rval nil init))))
+ (eval nil)))
+(NIL) <font color="#008844">; PRINT output</font>
+=> NIL
+</pre>
+
+<p>Bug tested with <nobr>Nyquist 3.03</nobr> in <nobr>December 2010</nobr>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/evaluation.htm b/docsrc/xlisp/xlisp-doc/examples/evaluation.htm new file mode 100644 index 0000000..fc46780 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/evaluation.htm @@ -0,0 +1,131 @@ +<html><head>
+
+<title>Evaluation</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Evaluation</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#with-errset">with-errset</a> - evaluate expressions without entering the <nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr></nobr></li>
+<li><nobr><a href="#apply-star.htm">apply*</a> and <a href="#funcall-star.htm">funcall*</a> - work also with macros and special forms</nobr></li>
+</ol>
+
+<a name="with-errset"></a>
+
+<hr>
+
+<h2>with-errset</h2>
+
+<hr>
+
+<p>Evaluate an expression without entering the
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr>
+on <a href="../reference/error.htm">error</a>
+<nobr>or <a href="../reference/cerror.htm">cerror</a></nobr>:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">with-errset</font> (expr &optional (print-flag nil))
+ `(progv '(<font color="#AA5500">*breakenable*</font>) '(nil)
+ (errset ,expr ,print-flag)))
+</pre>
+
+<p>See <a href="../reference/defmacro.htm">defmacro</a>,
+<a href="../reference/errset.htm">errset</a>,
+<a href="../reference/nil.htm">nil</a>,
+<a href="../reference/lambda-keyword-optional.htm.htm">&optional</a>,
+<a href="../reference/progv.htm">progv</a>.</p>
+
+<p><b>Note:</b> <a href="../reference/errset.htm">errset</a> does not
+protect against the <a href="../reference/break.htm">break</a> function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="apply-star"></a><a name="funcall-star"></a>
+
+<hr>
+
+<h2>apply* and funcall*</h2>
+
+<hr>
+
+<p>In Lisp, macros and <nobr>special forms</nobr> are no functions. This
+means that <a href="../reference/apply.htm">apply</a> and
+<a href="../reference/funcall.htm">funcall</a> only work with functions of
+type SUBR <nobr>[built-in</nobr> function] or CLOSURE [functions defined by
+<a href="defun.htm">defun</a>, <a href="flet.htm">flet</a>,
+<a href="labels.htm">labels</a>, or <a href="lambda.htm">lambda</a>], but
+with macros and <nobr>special forms</nobr> a '<nobr>bad function</nobr>'
+error is signalled. Here are two examples how to work around this
+behaviour:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">apply*</font> (function args)
+ (eval (cons function args)))
+
+(defun <font color="#0000CC">funcall*</font> (function args)
+ (eval (cons function args)))
+</pre>
+
+<p><b>Warning:</b> These functions can produce unwanted
+<nobr>side-effects</nobr> because macros and <nobr>special forms</nobr> do
+not need to conform to functional evaluation rules. Use them on your own
+risk.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
+
diff --git a/docsrc/xlisp/xlisp-doc/examples/examples.htm b/docsrc/xlisp/xlisp-doc/examples/examples.htm new file mode 100644 index 0000000..2140ebe --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/examples.htm @@ -0,0 +1,211 @@ +<html><head><title>XLISP Examples</title></head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+Examples |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>XLISP Examples</h1>
+
+<hr>
+
+<p><b>Nyquist/XLISP</b></p>
+
+<ul>
+<li><nobr><a href="lists.htm">Lists</a></nobr></li>
+<ul>
+<li><nobr>print-cons - print lists as dotted conses</nobr></li>
+<li><nobr>dolist* - a <a href="../reference/dolist.htm">dolist</a> version that can iterate dotted lists</nobr></li>
+</ul>
+<li><nobr><a href="arrays.htm">Arrays</a></nobr></li>
+<ul>
+<li><nobr>make-array* - create multi-dimensional arrays</nobr></li>
+<li><nobr>aref* - access multi-dimensional arrays</nobr></li>
+</ul>
+<li><nobr><a href="circular-lists.htm">Circular Access</a></nobr></li>
+<ul>
+<li><nobr>c-nth - circular list accessor</nobr></li>
+<li><nobr>c-aref - circular array accessor</nobr></li>
+</ul>
+<li><nobr><a href="hash-tables.htm">Hash Tables</a></nobr></li>
+<ul>
+<li><nobr>make-hash-table - create a hash-table</nobr></li>
+<li><nobr>puthash - store a key/value pair in a hash-table</nobr></li>
+<li><nobr>gethash - get a value from a hash-table by using a key</nobr></li>
+<li><nobr>remhash - remove a key/value pair from a hash-table</nobr></li>
+<li><nobr>clrhash - remove all key/value pairs from a hash-table</nobr></li>
+<li><nobr>hash-table-p - is this a hash-table?</nobr></li>
+<li><nobr>hash-table-size - get the number of buckets</nobr></li>
+<li><nobr>hash-table count - get the number of key/value pairs</nobr></li>
+<li><nobr>hash-table-test - get the :test argument given to to make-hash-table</nobr></li>
+<li><nobr>print-hash-table - print a hash-table in human-readable form</nobr></li>
+</ul>
+<li><nobr><a href="strings.htm">Strings and Characters</a></nobr></li>
+<ul>
+<li><nobr>string* - make a string out of everything</nobr></li>
+<li><nobr><a href="posix-chars.htm">POSIX Character Classes</a></nobr></li>
+</ul>
+<li><nobr><a href="sequences.htm">Sequences</a> - lists, strings, and arrays</nobr></li>
+<li><nobr><a href="predicates.htm">Predicates and Comparison</a></nobr></li>
+<li><nobr><a href="files.htm">Files and Directories</a></nobr></li>
+<li><nobr><a href="math.htm">Numbers</a></nobr></li>
+<ul>
+<li><nobr>Non-decimal Number Formats</nobr></li>
+<ul>
+<li><nobr><a href="binary.htm">Binary Integer Numbers</a></nobr></li>
+<li><nobr><a href="octal.htm">Octal Integer Numbers</a></nobr></li>
+<li><nobr><a href="hexadecimal.htm">Hexadecimal Integer Numbers</a></nobr></li>
+</ul>
+<li><nobr>divide-float - divide numbers as floating-point numbers</nobr></li>
+<li><nobr><a href="xlisp/ceiling.htm">ceiling</a> - truncate a number toward positive infinity</nobr></li>
+<li><nobr><a href="xlisp/floor.htm">floor</a> - truncate a number toward negative infinity</nobr></li>
+<li><nobr><a href="xlisp/ash.htm">ash</a> - arithmetic bit-shift left or right</nobr></li>
+<li><nobr><a href="xlisp/bsh.htm">bsh</a> - binary bit-shift left or right</nobr></li>
+<li><nobr>csh - circular bit-shift left or right</nobr></li>
+</ul>
+<li><nobr><a href="reader.htm">Reader</a></nobr></li>
+<ul>
+<li><nobr>read-from-string</nobr></li>
+<li><nobr>*readtable*</nobr></li>
+<ul>
+<li><nobr>print-readtable - print the XLISP *readtable* in human-readable form</nobr></li>
+<li><nobr>get-macro-character</nobr></li>
+<li><nobr>set-macro-character</nobr></li>
+</ul>
+</ul>
+</ul>
+
+<ul>
+<li><nobr><a href="apropos.htm">Apropos</a></nobr></li>
+<li><nobr><a href="macros.htm">Macro Programming</a></nobr></li>
+<li><nobr><a href="evaluation.htm">Evaluation</a></nobr></li>
+<li><nobr><a href="environment.htm">Environment</a></nobr></li>
+<li><nobr><a href="../objects/advanced-objects.htm">Advanced XLISP Objects</a></nobr></li>
+</ul>
+
+<ul>
+<li><nobr><a href="reader.htm">XLISP Reader</a></nobr></li>
+</ul>
+
+<p><b>Common Lisp</b> - written in Nyquist/XLISP</p>
+
+<ul>
+<li><nobr><a href="common-lisp.htm">Where is the Nyquist Common Lisp Library?</a></nobr></li>
+</ul>
+
+<ul>
+<li><nobr>Data and Control Flow</nobr></li>
+<ul>
+<li><nobr>Comparison</nobr></li>
+<ul>
+<li><nobr><a href="../reference/eq.htm">eq</a></nobr> - [Function] - test if arguments are identical</li>
+<li><nobr><a href="../reference/eql.htm">eql</a> - [Function] - test if arguments are identical or same integer value</nobr></li>
+<li><nobr><a href="../reference/equal.htm">equal</a> - [Function] - test if arguments are structurally equivalent</nobr></li>
+<li><nobr><a href="common-lisp/equalp.htm">cl:equalp</a> - [Function] - test arguments with 'equality' functions</nobr></li>
+</ul>
+<li><nobr><a href="common-lisp/multiple-values.htm">Multiple Values</a></nobr></li>
+<ul>
+<li><nobr>XLISP helpers</nobr></li>
+<ul>
+<li><nobr><a href="common-lisp/global-multiple-values.htm">cl:*multiple-values*</a> - [Variable] - signals if a function has returned multiple values</nobr></li>
+<li><nobr><a href="common-lisp/debug-mv.htm">cl:debug:mv</a> - [Function] - debug multiple value expressions</nobr></li>
+</ul>
+<li><nobr>Returning Multiple Values</nobr></li>
+<ul>
+<li><nobr><a href="common-lisp/values.htm">cl:values</a> - [Function] - return results from evaluated arguments as multiple values</nobr></li>
+<li><nobr><a href="common-lisp/values-list.htm">cl:values-list</a> - [Function] - return multiple values from a list unevaluated</nobr></li>
+</ul>
+<li><nobr>Working with Multiple Values</nobr></li>
+<ul>
+<li><nobr><a href="common-lisp/multiple-value-list.htm">cl:multiple-value-list</a> - [Macro] - evaluate an expression and return all values in a list</nobr></li>
+<li><nobr><a href="common-lisp/multiple-value-bind.htm">cl:multiple-value-bind</a> - [Macro] - bind multiple values to multiple <a href="../reference/let.htm">let</a> variables</nobr></li>
+<li><nobr><a href="common-lisp/multiple-value-setq.htm">cl:multiple-value-setq</a> - [Macro] - assign multiple values to multiple variables using <a href="../reference/setq.htm">setq</a></nobr></li>
+<li><nobr><a href="common-lisp/multiple-value-prog1.htm">cl:multiple-value-prog1</a> - [Macro] - eveluate multiple expressions, return the values of the first expression</nobr></li>
+<li><nobr><a href="common-lisp/multiple-value-call.htm">cl:multiple-value-call</a> - [Macro] - apply a function to multiple values collected in a list</nobr></li>
+</ul>
+</ul>
+</ul>
+<li><nobr><a href="common-lisp/numbers.htm">Numbers</a></nobr></li>
+<ul>
+<li><nobr><a href="common-lisp/rounding-and-truncation.htm">Rounding and Truncation</a></nobr></li>
+<ul>
+<li><nobr><a href="common-lisp/round.htm">cl:round</a> - round towards the next integer</nobr></li>
+<li><nobr><a href="common-lisp/truncate.htm">cl:truncate</a> - truncate towards zero</nobr></li>
+<li><nobr><a href="common-lisp/ceiling.htm">cl:ceiling</a> - truncate towards positive infinity</nobr></li>
+<li><nobr><a href="common-lisp/floor.htm">cl:floor</a> - truncate towards negative infinity</nobr></li>
+</ul>
+<li><nobr><a href="common-lisp/remainder-and-modulus.htm">Remainder and Modulus</a></nobr></li>
+<ul>
+<li><nobr><a href="common-lisp/rem.htm">cl:rem</a></nobr></li>
+<li><nobr><a href="common-lisp/mod.htm">cl:mod</a></nobr></li>
+</ul>
+<li><nobr>Exponentiation, Logarithms, and Roots</nobr></li>
+<ul>
+<li><nobr><a href="common-lisp/exp.htm">cl:exp</a> - compute 'e' to the power of 'x'</nobr></li>
+<li><nobr><a href="common-lisp/expt.htm">cl:expt</a> - compute 'x' to the power of 'y'</nobr></li>
+<li><nobr><a href="common-lisp/log.htm">cl:log</a> - logarithms of arbitrary base</nobr></li>
+<li><nobr><a href="common-lisp/sqrt.htm">cl:sqrt</a> - sqare root or arbitrary numbers</nobr></li>
+</ul>
+</ul>
+<li><nobr>Conses</nobr></li>
+<ul>
+<li><nobr>List Membership</nobr></li>
+<ul>
+<li><nobr>cl:member - [Function] - test for membership in lists and sub-elements</nobr></li>
+<li><nobr>cl:member-if - [Function] - search for the first element matching a predicate</nobr></li>
+<li><nobr>cl:member-if-not - [Function] - search for the first element not matching a predicate</nobr></li>
+</ul>
+<li><nobr>Non-destructive Removal</nobr></li>
+<ul>
+<li><nobr>cl:remove</nobr></li>
+<li><nobr>cl:remove-if</nobr></li>
+<li><nobr>cl:remove-if-not</nobr></li>
+</ul>
+<li><nobr>Destructive Removal = Deletion</nobr></li>
+<ul>
+<li><nobr>cl:delete</nobr></li>
+<li><nobr>cl:delete-if</nobr></li>
+<li><nobr>cl:delete-if-not</nobr></li>
+</ul>
+<li><nobr>Lists as Sets</nobr></li>
+<ul>
+<li><nobr>cl:pushnew - [Macro] -</nobr></li>
+<li><nobr>cl:union - [Function]</nobr></li>
+<li><nobr>cl:intersection - [Function]</nobr></li>
+<li><nobr>cl:set-difference - [Function]</nobr></li>
+<li><nobr>cl:set-exclusive-or - [Function]</nobr></li>
+<li><nobr>cl:subsetp - [Function]</nobr></li>
+</ul>
+</ul>
+<li><nobr>Sequences</nobr></li>
+<ul>
+<li><nobr>Subsequences</nobr></li>
+<ul>
+<li><nobr>cl:subseq - subsequences of lists, strings, or arrays</nobr></li>
+</ul>
+<li><nobr>Properties of elements in sequences:</nobr></li>
+<ul>
+<li><nobr>cl:find</nobr></li>
+<li><nobr>cl:count</nobr></li>
+<li><nobr>cl:position</nobr></li>
+</ul>
+<li><nobr>Predicates for testing sequences:</nobr></li>
+<ul>
+<li><nobr>cl:every</nobr></li>
+<li><nobr>cl:some</nobr></li>
+<li><nobr>cl:notevery</nobr></li>
+<li><nobr>cl:notany</nobr></li>
+</ul>
+<li><nobr>Functions to modify sequences:</nobr></li>
+<ul>
+<li><nobr>cl:map</nobr></li>
+</ul>
+</ul>
+</ul>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/files.htm b/docsrc/xlisp/xlisp-doc/examples/files.htm new file mode 100644 index 0000000..a43f4fe --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/files.htm @@ -0,0 +1,459 @@ +<html><head>
+
+<title>Files and Directories</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Files and Directories</h1>
+
+<hr>
+
+<ul>
+<li><nobr>Interactive Functions</nobr></li>
+<ul>
+<li><nobr><a href="#pwd">pwd</a> - returns the current working directory</nobr></li>
+<li><nobr><a href="#cd">cd</a> - changes the current working directory</nobr></li>
+</ul>
+<li><nobr>Testing Files and Directories</nobr></li>
+<ul>
+<li><nobr><a href="#directory-exists-p">directory-exists-p</a> - tests if a directory exists</nobr></li>
+<li><nobr><a href="#file-exists-p">file-exists-p</a> - tests if a file exists</nobr></li>
+<li><nobr><a href="#filename-exists-p">filename-exists-p</a> - tests if a file or directory exists</nobr></li>
+</ul>
+<li><nobr>Testing Filenames</nobr></li>
+<ul>
+<li><nobr><a href="#absolute-filename-p">absolute-filename-p</a> - tests if a string is an absolute filename</nobr></li>
+</ul>
+<li><nobr>System Environment Variables</nobr></li>
+<ul>
+<li><nobr><a href="#windows-p">windows-p</a> - tests if the operation system is a Windows system</nobr></li>
+<li><nobr><a href="#user-home-directory">user-home-directory</a> - returns path to the user's HOME directory</nobr></li>
+<li><nobr><a href="#expand-tilde">expand-tilde</a> - replaces "~/" with the user's HOME directory</nobr></li>
+</ul>
+</ul>
+
+<a name="pwd"></a>
+
+<hr>
+
+<h2>pwd</h2>
+
+<hr>
+
+<p>The 'pwd' function returns the current working directory:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">pwd</font> ()
+ (setdir <font color="#880000">"."</font>))
+</pre>
+
+<p>Ok, this function does not belong to the masterpieces of computer
+science, but (pwd) is much easier to remember than <nobr>(setdir
+".")</nobr>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cd"></a>
+
+<hr>
+
+<h2>cd</h2>
+
+<hr>
+
+<p>The 'cd' function changes the current working directory. <nobr>The
+directory</nobr> name must be given as a string:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">cd</font> (string)
+ (cond ((not (stringp string))
+ (error <font color="#880000">"argument must be a string"</font> string))
+ ((string= <font color="#880000">"."</font> string)
+ (setdir <font color="#880000">"."</font>))
+ (t
+ (let ((orig-dir (setdir <font color="#880000">"."</font>))
+ (new-dir (setdir string)))
+ (when (string/= orig-dir new-dir)
+ new-dir)))))
+</pre>
+
+<p>Possible actions and return values are:</p>
+
+<ul>
+
+<li><p>It the argument is not a string, then an error will be
+raised.</p></li>
+
+<li><p>If the directory name is ".", then the name of the current
+working directory is returned as a string. This is the same effect as if the
+directory has been changed to itself.</p></li>
+
+<li><p>If the directory has successfully been changed to the given
+directory, then the name of the new working directory is returned as a
+string.</p></li>
+
+<li><p>If the given directory has not been found, then NIL <nobr>[=
+false]</nobr> is returned.</p></li>
+
+</ul>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="directory-exists-p"></a>
+
+<hr>
+
+<h2>directory-exists-p</h2>
+
+<hr>
+
+<p>The '<nobr>directory-exists-p</nobr>' function tests if a directory
+exists. <nobr>The directory</nobr> name must be given as a string:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">directory-exists-p</font> (string)
+ (cond ((not (stringp string))
+ (error <font color="#880000">"argument must be a string"</font> string))
+ ((string= <font color="#880000">"."</font> string)
+ (setdir <font color="#880000">"."</font>))
+ (t
+ (let ((orig-dir (setdir <font color="#880000">"."</font>))
+ (new-dir (setdir string)))
+ (when (string/= orig-dir new-dir)
+ (setdir orig-dir)
+ new-dir)))))
+</pre>
+
+<p>Possible actions and return values are:</p>
+
+<ul>
+
+<li><p>It the argument is not a string, then an error will be
+raised.</p></li>
+
+<li><p>If the directory name is ".", then the absolute name of the
+current working directory is returned as a string. <nobr>This is</nobr> not
+a very useful test, but makes the return values consistent.</p></li>
+
+<li><p>If the directory has been found, then the absolute name of the
+directory is returned as a string.</p></li>
+
+<li><p>If the directory has not been found, then NIL <nobr>[= false]</nobr>
+is returned.</p></li>
+
+</ul>
+
+<p>The '<nobr>directory-exists-p</nobr>' function is nearly the same as the
+<a href="#cd">cd</a> function above. <nobr>The only</nobr> difference is
+that the working directory will automatically be changed back to the initial
+directory.</p>
+
+<p>On Unix, with <nobr>soft-links</nobr>, the absolute name of the target
+directory <nobr>[i.e. not</nobr> the name of the <nobr>link-file</nobr>
+itself, but the name of the directory the link <nobr>points to]</nobr> is
+returned.</p>
+
+<p><div class="box">
+
+<p><b>Implementation Notes</b></p>
+
+<p>The Nyquist 'setdir' function always returns absolute directory names,
+even if a relative directory name has been given as a string by the user.
+That's why it's not possible to reliably compare the return value of
+<nobr>(setdir string)</nobr> directly with 'string'. Instead the absolute
+name of the initial working directory, returned by <nobr>(setdir
+".")</nobr>, is compared to the absolute name, returned when
+<nobr>(setdir string)</nobr> tries to change the directory. <nobr>If
+both</nobr> return values are the same, then <nobr>(setdir string)</nobr>
+has failed because the directory has not been found.</p>
+
+<p>If the directory string is ".", then this trick doesn't work,
+because the initial directory is the same as the target directory, so even
+if the directory has 'successfully' been changed to itself, both return
+values still would be the same. This is one of the reasons why "."
+has a separate 'cond' clause. The other reason is of course that it makes
+not really much sense to change a directory to itself, that's why we save
+the work and just return the absolute name of the current working
+directory.</p>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="file-exists-p"></a>
+
+<hr>
+
+<h2>file-exists-p</h2>
+
+<hr>
+
+<p>The '<nobr>file-exists-p</nobr>' function tests if a file exists.
+<nobr>The file</nobr> name must be given as a string:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">file-exists-p</font> (string)
+ (if (not (stringp string))
+ (error <font color="#880000">"argument must be a string"</font> string)
+ (unless (directory-exists-p string)
+ (let (file-stream)
+ (unwind-protect
+ (setq file-stream (open string))
+ (when file-stream (close file-stream)))
+ (when file-stream string)))))
+</pre>
+
+<p>On Unix systems a directory is a special kind of file, so on Unix the
+XLisp 'open' function can open directories, too. That's why we first must
+make sure that no directory exists with the same name as the file that we
+are looking for.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="filename-exists-p"></a>
+
+<hr>
+
+<h2>filename-exists-p</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">filename-exists-p</font> (string)
+ (if (not (stringp string))
+ (error <font color="#880000">"argument must be a string"</font> string)
+ (or (directory-exists-p string)
+ (file-exists-p string)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="absolute-filename-p"></a>
+
+<hr>
+
+<h2>absolute-filename-p</h2>
+
+<hr>
+
+<p>The 'absolute-filename-p' function tests if a string is an absolute file
+or directory name:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">absolute-filename-p</font> (string)
+ (if (not (stringp string))
+ (error <font color="#880000">"argument must be a string"</font> string)
+ (let ((end (length string)))
+ (when (or (and (>= end 1) <font color="#008844">; Unix "/..."</font>
+ (char= #\/ (char string 0)))
+ (and (>= end 3) <font color="#008844">; Windows "[a-zA-Z]:[\/]..."</font>
+ (let ((char (char string 0)))
+ <font color="#008844">;; upper- or lowercase character a-z, A-Z</font>
+ (and (> (char-code (char-downcase char)) 96)
+ (< (char-code (char-downcase char)) 123)))
+ (char= #\: (char string 1))
+ (let ((char (char string 2)))
+ (or (char= #\\ char)
+ (char= #\/ char)))))
+ string))))
+</pre>
+
+
+<p>Note that it is only tested whether the beginning of the string
+matches the beginning of an absolute file or directory name. <nobr>It
+is</nobr> not tested whether the string reperesents a meaningful name.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="system-environment-variables"></a>
+
+<hr>
+
+<h2>System Environment Variables</h2>
+
+<a name="get-env"></a>
+
+<hr>
+
+<h2>get-env</h2>
+
+<hr>
+
+<p>[This function works only with <nobr>Audacity 1.3.13</nobr> and
+above.]</p>
+
+<p><div class="box">
+
+<dl>
+
+<dt><p><nobr>(<b>get-env</b> "<i>environment-variable</i>")</nobr></p></dt>
+
+
+
+
+</dl>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="windows-p"></a>
+
+<hr>
+
+<h2>windows-p</h2>
+
+<hr>
+
+<p>[This function works only with <nobr>Audacity 1.3.13</nobr> and
+above.]</p>
+
+<p>The '<nobr>windows-p</nobr>' function tests if the underlying operation
+system is a Microsoft <nobr>Windows[tm]</nobr> system:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">windows-p</font> ()
+ (let* ((home (let ((drive (get-env <font color="#880000">"HOMEDRIVE"</font>))
+ (path (get-env <font color="#880000">"HOMEPATH"</font>)))
+ (if (and drive path)
+ (strcat drive path)
+ (get-env <font color="#880000">"UserProfile"</font>))))
+ (path (get-env <font color="#880000">"PATH"</font>)))
+ (when home <font color="#008844">; if HOMEDRIVE + HOMEPATH or UserProfile exist</font>
+ (if path <font color="#008844">; search for Windows :\ drive-letter patterns</font>
+ (string-search ":\\" path)
+ (error <font color="#880000">"no PATH environment variable found"</font>)))))
+</pre>
+
+<p>Nquist has a <nobr>*file-separator*</nobr> variable, that could be used
+much easier to detect the operation system:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">windows-p</font> ()
+ (char= <font color="#AA5500">*file-separator*</font> #\\))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="user-home-directory"></a>
+
+<hr>
+
+<h2>user-home-directory</h2>
+
+<hr>
+
+<p>[This function works only with <nobr>Audacity 1.3.13</nobr> and
+above.]</p>
+
+<p>The '<nobr>user-home-directory</nobr>' function returns the path to the
+user's home directory on Linux, Mac, and Windows:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">user-home-directory</font> ()
+ (or (get-env <font color="#880000">"HOME"</font>)
+ (let ((drive (get-env <font color="#880000">"HOMEDRIVE"</font>))
+ (path (get-env <font color="#880000">"HOMEPATH"</font>)))
+ (when (and drive path)
+ (strcat drive path)))
+ (get-env <font color="#880000">"UserProfile"</font>)))
+</pre>
+
+<p>If the user's home directory could be identified, then the path to the
+home directory is returned as a string. <nobr>If the</nobr> user's home
+directory could not be identified, then <nobr>NIL [= false]</nobr> is
+returned.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(user-home-directory) <font color="#444444">=></font> <font color="#008844">"/home/edgar" ; Linux</font>
+(user-home-directory) <font color="#444444">=></font> <font color="#008844">"C:\\Documents and Settings\\Edgar" ; Windows</font>
+</pre>
+
+<p>On Windows there is no HOME variable defined by Windows itself, but most
+programs will respect a HOME variable, if one had been defined by the user.
+This means that on Windows, if a HOME variable exists, the HOME variable
+will be used instead of HOMEDRIVE and HOMEPATH or 'UserProfile'.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="expand-tilde"></a>
+
+<hr>
+
+<h2>expand-tilde</h2>
+
+<hr>
+
+<p>[This function works only with <nobr>Audacity 1.3.13</nobr> and
+above.]</p>
+
+<pre class="example">
+(defun <font color="#0000CC">expand-filename</font> (string)
+ (cond ((not (stringp string))
+ (error <font color="#880000">"argument must be a string"</font> string))
+ ((and (> (length string) 1)
+ (char= #\~ (char string 0))
+ (or (char= #\/ (char string 1))
+ (char= #\\ (char string 1))))
+ (strcat (user-home-directory)
+ (subseq string 1)))
+ (t string)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
+
diff --git a/docsrc/xlisp/xlisp-doc/examples/hash-tables.htm b/docsrc/xlisp/xlisp-doc/examples/hash-tables.htm new file mode 100644 index 0000000..3a74ffa --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/hash-tables.htm @@ -0,0 +1,496 @@ +<html><head>
+
+<title>Hash Tables</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Hash Tables</h1>
+
+<hr>
+
+<p>The internal XLISP 'hash' function from 'xlsym.c':</p>
+
+<pre class="example">
+<font color="#008844">/* hash - hash a symbol name string */</font>
+int <font color="#0000CC">hash</font>(char *str, int len)
+{
+ int i;
+ for (i = 0; *str; )
+ i = (i << 2) ^ *str++;
+ i %= len;
+ return (i < 0 ? -i : i);
+}
+</pre>
+
+<p>In XLISP this would look like:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">lisp-hash</font> (string table-size)
+ (let ((i 0))
+ (dotimes (index (length string))
+ (setq i (logxor (bsh i 2) (char-code (char string index)))))
+ (setq i (rem i table-size))
+ (if (minusp i) (- i) i)))
+</pre>
+
+<p>A <a href="../reference/hash.htm">hash</a> function is a kind of random
+number generator, where the same input always produces the same output
+number. <nobr>The XLISP</nobr> <a href="../reference/hash.htm">hash</a>
+function computes equally distributed integer numbers in a given range from
+the characters of an input string.</p>
+
+<p>A very simple example:</p>
+
+<ol>
+
+<li><p>We want to store <nobr>4 strings</nobr> in <nobr>2 lists</nobr>,
+stored in <nobr>2 array</nobr> elements:</p>
+
+<pre class="example">
+> (setq my-array (make-array 2))
+#(NIL NIL) <font color="#008844">; NIL NIL = two empty lists</font>
+</pre>
+
+<p>If the array index is computed by the
+<a href="../reference/hash.htm">hash</a> function, then the equally
+distributed numbers make sure that every list will contain approximately
+the same number of strings:</p>
+
+<pre class="example">
+> (dolist (string '("a" "b" "c" "d") my-array)
+ (push string (aref my-array (<font color="#AA0000">hash</font> string (length my-array)))))
+#(("d" "b") ("c" "a"))
+</pre>
+
+<p>The order of the strings in the array was computed by the
+<a href="../reference/hash.htm">hash</a> function, it is not the same order
+as given to <a href="../reference/dolist.htm">dolist</a>.</p></li>
+
+<li><p><nobr>If we</nobr> now search for a string in the lists then the
+<a href="../reference/hash.htm">hash</a> function will tell us the number of
+the array element with the list containing the string because the same input
+string to the <a href="../reference/hash.htm">hash</a> function always
+produces the same output number, as long as the same
+'<nobr>table-size</nobr>' [the same number of array elements] is used:</p>
+
+<pre class="example">
+> (dolist (string '("a" "b" "c" "d"))
+ (format t "~s = ~s~%" string
+ (aref my-array (<font color="#AA0000">hash</font> string (length my-array)))))
+"a" = ("c" "a")
+"b" = ("d" "b")
+"c" = ("c" "a")
+"d" = ("d" "b")
+NIL
+</pre>
+
+<p>The <a href="../reference/hash.htm">hash</a> function will always find
+the correct list as long as the number of array elements has not
+changed.</p> </li>
+
+</ol>
+
+<p>The two main tasks of the <a href="../reference/hash.htm">hash</a>
+<nobr>function are</nobr>:</p>
+
+<ol>
+
+<li><p>Make sure that all lists contain approximately the same number of
+elements, independent from the characters in the input strings, no matter if
+the strings are very similar or completely different. With the
+<a href="../reference/hash.htm">hash</a> function it will nearly never
+happen that one list contains all strings while all other lists are
+empty.</p></li>
+
+<li><p>With the same 'name' and '<nobr>table-size</nobr>' arguments the
+<a href="../reference/hash.htm">hash</a> function will always return exactly
+the same integer number, so a string can always be found no matter in what
+order the strings are stored in the lists of the array.</p></li>
+
+</ol>
+
+<p>Now we can find strings stored in lists, but we want to store and find
+arbitrary things. Therefore we replace the ordinary lists with association
+lists:</p>
+
+<pre class="example">
+> (setq my-array (make-array 2))
+#(() ())
+
+> (dolist (a-cons '(("a" . 1) ("b" . 2) ("c" . 3) ("d" . 4)) my-array)
+ (push a-cons (aref my-array (<font color="#AA0000">hash</font> (car a-cons) (length my-array)))))
+#((("d" . 4) ("b" . 2)) (("c" . 3) ("a" . 1)))
+</pre>
+
+<p>We now have an array like this:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td></td>
+ <td align="center"><nobr>Array </nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td align="right"><nobr><code> </code>0<code> </code></nobr></td>
+ <td class="button"><nobr>Association List 1</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td class="button"><nobr><code>(("d" . 4) ("b" . 2))</code></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td align="right"><nobr><code> </code>1<code> </code></nobr></td>
+ <td class="button"><nobr>Association List 2</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td class="button"><nobr><code>(("c" . 3) ("a" . 1))</code></nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>The association lists give the flexibility to store an arbitrary number
+of <nobr>key/value</nobr> pairs, we are not limited by the fixed number of
+array elements, while the array together with the
+<a href="../reference/hash.htm">hash</a> function gives much more speed than
+a single association list if we want to manage a big number of
+ <nobr>key/value pairs</nobr>.</p>
+
+<p>With a big number of key/value pairs it is faster to keep them in many
+small association lists than in one single <nobr>big list</nobr>. Arrays
+provide random access, where every element can be accessed in the same time,
+while a list can only be searched from the beginning up to the matching
+element. <nobr>The longer</nobr> the list, the slower the search
+becomes.</p>
+
+<p>With the <a href="../reference/hash.htm">hash</a> function we find the
+association list containing <nobr>the key</nobr>:</p>
+
+<pre class="example">
+> (dolist (key '("a" "b" "c" "d"))
+ (format t "~s = ~s~%" key
+ (aref my-array (<font color="#AA0000">hash</font> key (length my-array)))))
+"a" = (("c" . 3) ("a" . 1))
+"b" = (("d" . 4) ("b" . 2))
+"c" = (("c" . 3) ("a" . 1))
+"d" = (("d" . 4) ("b" . 2))
+NIL
+</pre>
+
+<p>With the <a href="../reference/assoc.htm">assoc</a> function we find the
+<nobr>key/value pair</nobr>:</p>
+
+<pre class="example">
+> (dolist (key '("a" "b" "c" "d"))
+ (format t "~s = ~s~%" key
+ (<font color="#AA0000">assoc</font> key (aref my-array (<font color="#AA0000">hash</font> key (length my-array)))
+ :test #'equal)))
+"a" = ("a" . 1)
+"b" = ("b" . 2)
+"c" = ("c" . 3)
+"d" = ("d" . 4)
+NIL
+</pre>
+
+<p>With the <a href="../reference/cdr.htm">cdr</a> function we get the
+value:</p>
+
+<pre class="example">
+> (dolist (key '("a" "b" "c" "d"))
+ (format t "~s = ~s~%" key
+ (<font color="#AA0000">cdr</font> (<font color="#AA0000">assoc</font> key (aref my-array (<font color="#AA0000">hash</font> key (length my-array)))
+ :test #'equal))))
+"a" = 1
+"b" = 2
+"c" = 3
+"d" = 4
+NIL
+</pre>
+
+<p>And now we have our first working <nobr>hash-table</nobr>.</p>
+
+<p>But we still have one problem. <nobr>The
+<a href="../reference/hash.htm">hash</a></nobr> function works only with
+symbols or strings, while <a href="../reference/assoc.htm">assoc</a> can
+also work with numbers, strings and even lists as 'key' argument. <nobr>To
+make</nobr> our <nobr>hash-table</nobr> work with all types
+<a href="../reference/assoc.htm">assoc</a> can handle, we must make the
+<a href="../reference/hash.htm">hash</a> function happy and convert the
+'key' argument with <a href="../reference/format.htm">format</a> into a
+string before computing the <nobr>hash index:</nobr></p>
+
+<pre class="example">
+> (setq my-array (make-array 2))
+#(() ())
+
+> (dolist (a-cons '((#\x . 1) ((y z) . 2) (12 . 3) (6.5 . 4)) my-array)
+ (push a-cons (aref my-array (<font color="#AA0000">hash</font> (<font color="#AA0000">format</font> nil "~s" (car a-cons))
+ (length my-array)))))
+#(((12 . 3) (#\x . 1)) ((6.5 . 4) ((Y Z) . 2)))
+
+> (dolist (key '(#\x (y z) 12 6.5))
+ (format t "~s = ~s~%" key
+ (<font color="#AA0000">cdr</font> (<font color="#AA0000">assoc</font> key (aref my-array (<font color="#AA0000">hash</font> (<font color="#AA0000">format</font> nil "~s" key)
+ (length my-array)))
+ :test #'equal))))
+#\x = 1
+(Y Z) = 2
+12 = 3
+6.5 = 4
+NIL
+</pre>
+
+<p>Wonderful.</p>
+
+<p>A final quirk still needs to be solved. Maybe you have noticed the :test
+argument to <a href="../reference/assoc.htm">assoc</a>. Like with all Lisp
+functions providing :test arguments, the
+<a href="../reference/assoc.htm">assoc</a> :test defaults to
+<a href="../reference/eql.htm">eql</a> [because
+<a href="../reference/eq.htm">eq</a> is unreliable with numbers, and
+<a href="../reference/eql.htm">eql</a> is faster
+<nobr>than <a href="../reference/equal.htm">equal</a>]</nobr>, but
+<a href="../reference/eql.htm">eql</a> doesn't work with
+<nobr>floating-point</nobr> numbers, strings and lists, so we had to
+<nobr>use <a href="../reference/equal.htm">equal</a></nobr>.</p>
+
+<p>The typical Lisp solution is to provide a :test argument to the
+'make-hash-table' function, so the programmer can choose which function to
+use. <nobr>The :test</nobr> argument to 'make-hash-table' becomes a property
+of the <nobr>hash-table</nobr> itself, so the :test only needs to be given
+once, at the time when the <nobr>hash-table</nobr> is created, and not every
+time the <nobr>hash-table</nobr> is accessed afterwards.</p>
+
+<p>We have the problem that <nobr>hash-tables</nobr> are no
+<nobr>built-in</nobr> XLISP data type and we want use
+<nobr>make-hash-table</nobr> in the same way
+<nobr>as <a href="../reference/make-array.htm">make-array</a></nobr>:</p>
+
+<pre class="example">
+(setq my-hash-table (make-hash-table <font color="#0000CC">size</font> :test #'equal))
+</pre>
+
+<p>Here the make-hash-table function has no access to the property list of
+the '<nobr>my-hash-table</nobr>' symbol, so the only solution is to make the
+:test function become part of the <nobr>hash-table</nobr> itself:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td></td>
+ <td align="center"><nobr>Array </nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td align="right"><nobr><code> </code>0<code> </code></nobr></td>
+ <td class="button"><nobr>Test Function</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><nobr>the :test argument to
+ <a href="../reference/assoc.htm">assoc</a></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td align="right"><nobr><code> </code>1<code> </code></nobr></td>
+ <td class="button"><nobr>Association List 1</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><nobr>((<i>key1</i> . <i>value1</i>)
+ ... (<i>keyN</i> . <i>valueN</i>))</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td align="right"><nobr><code> </code>2<code> </code></nobr></td>
+ <td class="button"><nobr>Association List 2</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><nobr>((<i>key1</i> . <i>value1</i>)
+ ... (<i>keyN</i> . <i>valueN</i>))</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td align="right"><nobr><code> </code>3<code> </code></nobr></td>
+ <td class="button"><nobr>Association List 3</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><nobr>((<i>key1</i> . <i>value1</i>)
+ ... (<i>keyN</i> . <i>valueN</i>))</nobr></td>
+</tr>
+<tr>
+ <td></td>
+ <td align="center"><nobr>...<code> </code></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td align="right"><nobr><code> </code><i>n</i><code> </code></nobr></td>
+ <td class="button"><nobr>Association List <i>n</i></nobr></td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><nobr>((<i>key1</i> . <i>value1</i>)
+ ... (<i>keyN</i> . <i>valueN</i>))</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>This is the final layout of our <nobr>hash-tables</nobr>, so we can start
+to implement the <nobr>hash-table</nobr> functions.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="make-hash-table"></a>
+
+<hr>
+
+<h2>make-hash-table</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">make-hash-table</font> (size &optional (test #'eql))
+ (and (< size 1) (error <font color="#880000">"hash-table minimum size is 1"</font> size))
+ (let ((hash-table (make-array (1+ size))))
+ (setf (aref hash-table 0) test)
+ hash-table))
+
+(defun <font color="#0000CC">gethash</font> (key hash-table)
+ (let* ((size (1- (length hash-table)))
+ (index (1+ (hash (format nil "~s" key) size)))
+ (a-list (aref hash-table index))
+ (test (aref hash-table 0)))
+ (cdr (assoc key a-list :test test))))
+
+(defun <font color="#0000CC">puthash</font> (key value hash-table)
+ (let* ((size (1- (length hash-table)))
+ (index (1+ (hash (format nil "~s" key) size)))
+ (a-list (aref hash-table index))
+ (test (aref hash-table 0))
+ (a-cons (assoc key a-list :test test)))
+ (setf (aref hash-table index)
+ (cons (cons key value)
+ (if a-cons
+ (remove-if #'(lambda (x)
+ (funcall test key (car x)))
+ a-list)
+ a-list)))))
+
+(defun <font color="#0000CC">remhash</font> (key hash-table)
+ (let* ((size (1- (length hash-table)))
+ (index (1+ (hash (format nil "~s" key) size)))
+ (a-list (aref hash-table index))
+ (test (aref hash-table 0))
+ (a-cons (assoc key a-list :test test)))
+ (and a-cons
+ (setf (aref hash-table index)
+ (remove-if #'(lambda (x)
+ (funcall test key (car x)))
+ a-list)))
+ a-cons))
+
+(defun <font color="#0000CC">clrhash</font> (hash-table)
+ (let ((size (1- (length hash-table))))
+ (do ((index 1 (1+ index)))
+ ((> index size))
+ (setf (aref hash-table index) nil))
+ hash-table))
+
+(defun <font color="#0000CC">hash-table-p</font> (expr)
+ (and (arrayp expr) <font color="#008844">; expression is an array</font>
+ (> (length expr) 1) <font color="#008844">; with more than one elements</font>
+ (fboundp (aref expr 0)) <font color="#008844">; first element is a function</font>
+ (let ((size (1- (length expr)))) <font color="#008844">; all other</font>
+ (do ((index 1 (1+ index))) <font color="#008844">; elements are lists</font>
+ ((or (> index size)
+ (not (listp (aref expr index))))
+ (> index size))))))
+
+(defun <font color="#0000CC">hash-table-count</font> (hash-table)
+ (let ((size (1- (length hash-table)))
+ (entries 0))
+ (do ((index 1 (1+ index)))
+ ((> index size))
+ (setf entries (+ entries (length (aref hash-table index)))))
+ entries))
+
+(defun <font color="#0000CC">hash-table-size</font> (hash-table)
+ (1- (length hash-table)))
+
+(defun <font color="#0000CC">hash-table-test</font> (hash-table)
+ (aref hash-table 0))
+
+(defun <font color="#0000CC">print-hash-table</font> (hash-table)
+ (if (not (arrayp hash-table))
+ (format t <font color="#880000">";; Not an array: ~s~%"</font> hash-table)
+ (dotimes (index (length hash-table))
+ (let ((element (aref hash-table index)))
+ (cond ((not (listp element))
+ (format t <font color="#880000">";; array element ~a: ~s~%"</font> index element))
+ ((null element)
+ (format t <font color="#880000">";; bucket ~a: ()~%"</font> index))
+ (t
+ (format t <font color="#880000">";; bucket ~a:~%"</font> index)
+ (let ((entry-counter 1))
+ (dolist (entry element)
+ (format t <font color="#880000">";; ~a.~a: ~s~%"</font> index entry-counter entry)
+ (incf entry-counter)))))))))
+</pre>
+
+
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
+
diff --git a/docsrc/xlisp/xlisp-doc/examples/hexadecimal.htm b/docsrc/xlisp/xlisp-doc/examples/hexadecimal.htm new file mode 100644 index 0000000..4b483b0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/hexadecimal.htm @@ -0,0 +1,151 @@ +<html><head>
+
+<title>Hexadecimal Integer Numbers</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Hexadecimal Integer Numbers</h1>
+
+<hr>
+
+<p>XLISP provides the <a href="../manual/xlisp.htm#hexadecimal">#x</a>
+<nobr>read-macro</nobr> for hexadecimal numbers:</p>
+
+<pre class="example">
+#x0 => 0 #x8 => 8 #x10 => 16
+#x1 => 1 #x9 => 9 #x11 => 17
+#x2 => 2 #xa => 10 #x12 => 18
+#x3 => 3 #xb => 11 #x13 => 19
+#x4 => 4 #xc => 12 #x14 => 20
+#x5 => 5 #xd => 13 #x15 => 21
+#x6 => 6 #xe => 14 #x16 => 22
+#x7 => 7 #xf => 15 #x17 => 23
+</pre>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>hex-string</b> <i>integer</i> [<i>all</i>])</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>all</i> - a boolean expression<br>
+returns - the <i>integer</i> in hexadecimal form as string</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">hex-string</font> (integer &optional all)
+ (if (integerp integer)
+ (let ((fmt (if all
+ (or (dolist (bits '(16 32 64 128) nil)
+ (let ((fixnum (round (expt 2.0 (1- bits)))))
+ (and (plusp (1- fixnum))
+ (minusp fixnum)
+ (return (format nil <font color="#880000">"%.~ax"</font> (/ bits 4))))))
+ (error <font color="#880000">"integer limit not found"</font>))
+ <font color="#880000">"%x"</font>)))
+ (progv '(<font color="#AA5500">*integer-format*</font>) (list fmt)
+ (format nil <font color="#880000">"~a"</font> integer)))
+ (error <font color="#880000">"not an integer"</font> integer)))
+</pre>
+
+<p>The '<nobr>hex-string</nobr>' function converts the 'integer' argument
+into hexadecimal form and returns is as a string. <nobr>If the</nobr>
+optional 'all' argument is not given or
+<a href="../reference/nil.htm">NIL</a>, leading zeros are not included in
+the string. <nobr>If the</nobr> optional 'all' argument is
+<nobr>non-<a href="../reference/nil.htm">NIL</a></nobr>, all digits of the
+internal representation of the 'integer' argument, including leading zeros,
+are contained in the string. This is useful for debugging integer overflow
+and <nobr>bit-wise</nobr> functions.</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>hex</b> <i>integer</i> [<i>all</i>])</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>all</i> - a boolean expression<br>
+prints - the <i>integer</i> in hexadecimal form<br>
+returns - the <i>integer</i> argument</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">hex</font> (integer &optional all)
+ (if (integerp integer)
+ (format t <font color="#880000">"#x~a~%"</font> (hex-string integer all))
+ (format t <font color="#880000">";; not an integer~%"</font>))
+ integer)
+</pre>
+
+<p>The 'hex' function prints the 'integer' argument in hexadecimal form on
+the screen. Together with the
+<a href="../manual/xlisp.htm#hexadecimal">#x</a> <nobr>read-macro</nobr>
+this can be used for interactive hexadecimal computations.</p>
+
+<pre class="example">
+> (hex 12345678)
+#xbc614e
+12345678
+
+> (hex (+ #x1f #xa3))
+#xc2
+194
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/lists.htm b/docsrc/xlisp/xlisp-doc/examples/lists.htm new file mode 100644 index 0000000..34f9053 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/lists.htm @@ -0,0 +1,580 @@ +<html><head>
+
+<title>Lists</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Lists</h1>
+
+<hr>
+
+<p>Lists are also <a href="sequences.htm">Sequences</a>.</p>
+
+<ul>
+<li><nobr><a href="#print-cons">print-cons</a> - print lists as conses</nobr></li>
+<li><nobr><a href="#dolist-star">dolist*</a> - a <a href="../reference/dolist.htm">dolist</a> version that can iterate dotted lists</nobr></li>
+<li><nobr>List Accessors</nobr></li>
+<ul>
+<li><nobr><a href="#cl-list-accessor">cl:list:unary-accessor</a></nobr></li>
+<li><nobr><a href="#cl-list-accessor">cl:list:binary-accessor</a></nobr></li>
+</ul>
+<li><nobr>List Membership</nobr></li>
+<ul>
+<li><nobr><a href="#cl-member">cl:member</a> - [Function] - test for membership in lists and sub-elements</nobr></li>
+<li><nobr><a href="#cl-member-if">cl:member-if</a> - [Function] - search for the first element matching a predicate</nobr></li>
+<li><nobr><a href="#cl-member-if-not">cl:member-if-not</a> - [Function] - search for the first element not matching a predicate</nobr></li>
+</ul>
+<li><nobr>Non-destructive Removal</nobr></li>
+<ul>
+<li><nobr>cl:remove</nobr></li>
+<li><nobr>cl:remove-if</nobr></li>
+<li><nobr>cl:remove-if-not</nobr></li>
+</ul>
+<li><nobr>Destructive Removal = Deletion</nobr></li>
+<ul>
+<li><nobr>cl:delete</nobr></li>
+<li><nobr>cl:delete-if</nobr></li>
+<li><nobr>cl:delete-if-not</nobr></li>
+</ul>
+<li><nobr>Lists as Sets</nobr></li>
+<ul>
+<li><nobr><a href="#cl-pushnew">cl:pushnew</a> - [Macro] -</nobr></li>
+<li><nobr><a href="#cl-union">cl:union</a></nobr> - [Function]</li>
+<li><nobr><a href="#cl-intersection">cl:intersection</a> - [Function]</nobr></li>
+<li><nobr><a href="#cl-set-difference">cl:set-difference</a> - [Function]</nobr></li>
+<li><nobr><a href="#cl-set-exclusive-or">cl:set-exclusive-or</a> - [Function]</nobr></li>
+<li><nobr><a href="#cl-subsetp">cl:subsetp</a> - [Function]</nobr></li>
+</ul>
+</ul>
+
+<a name="print-cons"></a>
+
+<hr>
+
+<h2>print-cons</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">print-cons</font> (item)
+ (labels ((cons-string (item)
+ (case (type-of item)
+ (array (let ((end (length item))
+ (result <font color="#880000">""</font>))
+ (dotimes (index end)
+ (let ((string (cons-string (aref item index))))
+ (setq result
+ (if (eql 0 index)
+ (format nil <font color="#880000">"#(~a"</font> string)
+ (format nil <font color="#880000">"~a ~a"</font> result string)))))
+ (format nil <font color="#880000">"~a)"</font> result)))
+ (character (format nil <font color="#880000">"~s"</font> item))
+ (cons (format nil <font color="#880000">"(~a . ~a)"</font>
+ (cons-string (car item))
+ (cons-string (cdr item))))
+ (string (format nil <font color="#880000">"\"~a\""</font> item))
+ (t item))))
+ (format t <font color="#880000">"~a~%"</font> (cons-string item))
+ item))
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+> (print-cons '(1 2 3))
+(1 . (2 . (3 . NIL)))
+(1 2 3)
+</pre>
+
+<p>The 'print-cons' function is useful for debugging association lists,
+where <a href="../reference/print.htm">print</a> often fails to display the
+correct layout:</p>
+
+<pre class="example">
+> (print-cons (cons '((1 . 2) (3 . 4)) '((a . b) (c . d))))
+(((1 . 2) . ((3 . 4) . NIL)) . ((A . B) . ((C . D) . NIL)))
+(((1 . 2) (3 . 4)) (A . B) (C . D)) <font color="#008844">; <- output of PRINT</font>
+</pre>
+
+<p>Do not think that <a href="../reference/print.htm">print</a> is bad, it
+saves you from reading things like this:</p>
+
+<pre class="example">
+> (print-cons '(defun hello-world ()
+ (print "Hello World!")))
+(DEFUN . (HELLO-WORLD . (NIL . ((PRINT . ("Hello World!" . NIL)) . NIL))))
+(DEFUN HELLO-WORLD NIL (PRINT "Hello World!")) <font color="#008844">; <- output of PRINT</font>
+</pre>
+
+<p>Test this if you don't believe:</p>
+
+<pre class="example">
+> (DEFUN . (HELLO-WORLD . (NIL . ((PRINT . ("Hello World!" . NIL)) . NIL))))
+HELLO-WORLD
+
+> (hello-world)
+"Hello World!"
+</pre>
+
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="dolist-star"></a>
+
+<hr>
+
+<h2>dolist*</h2>
+
+<hr>
+
+<p>A <a href="../reference/dolist.htm">dolist</a> version that can iterate
+dotted lists:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">dolist*</font> (fargs &rest body)
+ (let ((list (gensym)))
+ `(let ((,list ,(second fargs)))
+ (if (not (listp ,list))
+ (error <font color="#880000">"not a list"</font> ,list)
+ (do ((,(first fargs) (first ,list)
+ (if (consp ,list) (first ,list) ,list)))
+ ((null ,list))
+ (setq ,list (and (consp ,list) (rest ,list)))
+ ,@body)))))
+</pre>
+
+<pre class="example">
+(dolist (i '(1 2 3)) (print i)) <font color="#008844">; prints 1 2 3</font>
+(dolist* (i '(1 2 3)) (print i)) <font color="#008844">; prints 1 2 3</font>
+
+(dolist (i '(1 2 . 3)) (print i)) <font color="#008844">; prints 1 2</font>
+(dolist* (i '(1 2 . 3)) (print i)) <font color="#008844">; prints 1 2 3</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-member"></a>
+
+<hr>
+
+<h2>cl:member</h2>
+
+<hr>
+
+<p>XLISP already has the <a href="../reference/member.htm">member</a>
+function to for search elements in lists:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<a href="../reference/member.htm">member</a> <i>expr list</i> [{:test | :test-not} <i>test</i>])</dt>
+<dd><i>expr</i> - the expression to find [an atom or a list]<br>
+<i>list</i> - the list to search<br>
+<i>test</i> - optional test function, default is <a href="../reference/eql.htm">eql</a><br>
+returns - the remainder of the list starting with <i>expr</i></dd>
+</dl>
+
+</div></p>
+
+<nobr>The 'cl:member' function provides an additional :key argument for
+accessing <nobr>sub-elements</nobr> in the list:</nobr>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>cl:member</b> <i>expr list</i> [{:test | :test-not} <i>test</i> :key <i>key</i>])</dt>
+<dd><i>expr</i> - the expression to find [an atom or a list]<br>
+<i>list</i> - the list to search<br>
+<i>test</i> - an optional test function, default is <a href="../reference/eql.htm">eql</a><br>
+<i>key</i> - an optional accessor function for sub-elements in the list<br>
+returns - the remainder of the list starting with <i>expr</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:member</font> (expr list &key test test-not key)
+ (and test test-not (error <font color="#880000">"both :TEST and :TEST-NOT specified"</font>))
+ (if key
+ (cond (test
+ (member expr list
+ :test #'(lambda (x y)
+ (funcall test x (funcall key y)))))
+ (test-not
+ (member expr list
+ :test-not #'(lambda (x y)
+ (funcall test-not x (funcall key y)))))
+ (t (member expr list
+ :test #'(lambda (x y)
+ (eql x (funcall key y))))))
+ (cond (test (member expr list :test test))
+ (test-not (member expr list :test-not test-not))
+ (t (member expr list)))))
+</pre>
+
+<p>Test if the number 4 matches the first or the second element in several
+sublists:</p>
+
+<pre class="example">
+(cl:member 4 '((1 2) (3 4) (5 6)) :key #'first) => NIL <font color="#008844">; no match</font>
+(cl:member 4 '((1 2) (3 4) (5 6)) :key #'second) => ((3 4) (5 6)) <font color="#008844">; number found</font>
+</pre>
+
+<p>Subtle differences between XLISP and Common Lisp:</p>
+
+<pre class="example">
+<font color="#008844">;; Lisp Form XLISP Common Lisp</font>
+(member 1 '(1 2 . 3)) => (1 2 . 3) => (1 2 . 3)
+(member 2 '(1 2 . 3)) => (2 . 3) => (2 . 3)
+(member 3 '(1 2 . 3)) => NIL => <font color="#AA0000">error: not a proper list</font>
+</pre>
+
+
+<p>Here is a 'cl:member' version that behaves <nobr>error-conform</nobr> to
+<nobr>Common Lisp</nobr> but produces an unintelligible backtrace in case of
+Lisp errors. <nobr>I also</nobr> have found no way how to macroexpand
+macrolets, so debugging this function is a real pain.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:member</font> (expr list &key test test-not key)
+ (and test test-not (error <font color="#880000">"both :TEST and :TEST-NOT specified"</font>))
+ (macrolet ((internal-loop (list)
+ `(do ()
+ <font color="#008844">;; termination test</font>
+ ((or (not (consp list))
+ ,(if key
+ (cond (test `(funcall ,test ,expr (funcall ,key (car list))))
+ (test-not `(not (funcall ,test ,expr (funcall ,key (car list)))))
+ (t `(eql ,expr (funcall ,key (car list)))))
+ (cond (test `(funcall ,test ,expr (car list)))
+ (test-not `(not (funcall ,test ,expr (car list))))
+ (t `(eql ,expr (car list))))))
+ <font color="#008844">;; return value</font>
+ (if (not (listp list))
+ (error <font color="#AA0000">"a proper list must not end with"</font> list)
+ list))
+ <font color="#008844">;; body</font>
+ (setq list (cdr list)))))
+ (internal-loop list)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-member-if"></a>
+
+<hr>
+
+<h2>cl:member-if</h2>
+
+<hr>
+
+<p>Here are two functions to search for elements that satisfy a given
+predicate:</p>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>member-if</b> <i>predicate list</i> [:key <i>key</i>])</nobr></dt>
+<dd><i>predicate</i> - a test function with one argument<br>
+<i>list</i> - the list to search<br>
+<i>key</i> - optional accessor function for sub-elements in the list<br>
+returns - the remainder of the list starting with the first matching element</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:member-if-not</font> (predicate list &key key)
+ (member nil list :test (if key
+ #'(lambda (x y)
+ (funcall predicate (funcall key y)))
+ #'(lambda (x y)
+ (funcall predicate y)))))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-member-if-not"></a>
+
+<hr>
+
+<h2>cl:member-if-not</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>member-if-not</b> <i>predicate list</i> [:key <i>key</i>])</nobr></dt>
+<dd><i>predicate</i> - a test function with one argument<br>
+<i>list</i> - the list to search<br>
+<i>key</i> - optional accessor function for sub-elements in the list<br>
+returns - the remainder of the list starting with the first non-matching element</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:member-if-not</font> (predicate list &key key)
+ (member nil list :test-not (if key
+ #'(lambda (x y)
+ (funcall predicate (funcall key y)))
+ #'(lambda (x y)
+ (funcall predicate y)))))))
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:member-if #'plusp '(-2 -1 0 1 2)) => (1 2) <font color="#008844">; 1 = first positive number</font>
+(cl:member-if-not #'minusp '(-2 -1 0 1 2)) => (0 1 2) <font color="#008844">; 0 = first non-negative number</font>
+</pre>
+
+<p>More test functions see <a href="predicates.htm">Predicates</a>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-list-accessor"></a>
+
+<hr>
+
+<h2>cl:list:accessor</h2>
+
+<hr>
+
+<p>The 'lists as sets' functions have common :test, <nobr>:test-not</nobr>
+and :key parameters:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:list:accessor</font> (test test-not &optional key)
+ (if (and test test-not)
+ (error <font color="#880000">"both :TEST and :TEST-NOT specified"</font>))
+ (if key
+ (cond (test `(lambda (x y)
+ (funcall ,test (funcall ,key x)
+ (funcall ,key y))))
+ (test-not `(lambda (x y)
+ (not (funcall ,test-not (funcall ,key x)
+ (funcall ,key y)))))
+ (t `(lambda (x y)
+ (eql (funcall ,key x) (funcall ,key y)))))
+ (cond (test `(lambda (x y)
+ (funcall ,test x y)))
+ (test-not `(lambda (x y)
+ (not (funcall ,test-not x y))))
+ (t `(lambda (x y)
+ (eql x y))))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-pushnew"></a>
+
+<hr>
+
+<h2>cl:pushnew</h2>
+
+<hr>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-union"></a>
+
+<hr>
+
+<h2>cl:union</h2>
+
+<hr>
+
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>union</b> <i>list1 list2</i> [{:test | :test-not} <i>test</i> :key <i>key</i>])</nobr></dt>
+<dd><i>listN</i> - a list of symbols or numbers<br>
+returns - the union of <i>list1</i> and <i>list2</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">union</font> (a b)
+ (let (result)
+ (dolist (element a)
+ (unless (member element result)
+ (push element result)))
+ (dolist (element b)
+ (unless (member element result)
+ (push element result)))
+ result))
+</pre>
+
+<p>The 'cl:union' function returns a list that contains every element that
+occurs in either 'list1' or 'list2'.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-intersection"></a>
+
+<hr>
+
+<h2>cl:intersection</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(intersection <i>list1 list2</i> [{:test | :test-not} <i>test</i> :key <i>key</i>])</nobr></dt>
+<dd><i>listN</i> - a list of symbols or numbers<br>
+returns - the intersection of <i>list1</i> and <i>list2</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">intersection</font> (a b)
+ (let (result)
+ (dolist (element a)
+ (when (member element b)
+ (push element result)))
+ result))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-set-difference"></a>
+
+<hr>
+
+<h2>cl:set-difference</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>set-difference</b> <i>list1 list2</i>)</nobr></dt>
+<dd><i>listN</i> - a list of symbols or numbers<br>
+returns - the set-difference of <i>list1</i> and <i>list2</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">set-difference</font> (a b)
+ (remove-if #'(lambda (element)
+ (member element b))
+ a))
+</pre>
+
+<p>An element of list1 appears in the result if and only if it does not
+match any element of list2.</p>
+
+<pre class="example">
+(set-difference '(1 2 3) '(2 3 4)) => (1)
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-set-exclusive-or"></a>
+
+<hr>
+
+<h2>cl:set-exclusive-or</h2>
+
+<hr>
+
+<p>The result contains precisely those elements of list1 and list2 that
+appear in no matching pair.</p>
+
+<pre class="example">
+(set-exclusive-or '(1 2 3) '(2 3 4)) => (1 4)
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-subsetp"></a>
+
+<hr>
+
+<h2>cl:subsetp</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>subsetp</b> <i>list1 list2</i>)</nobr></dt>
+<dd><i>listN</i> - a list of symbols or numbers<br>
+returns - <a href="t.htm"> T </a> if <i>list1</i> is a subset of <i>list2</i>, NIL otherwise</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">subsetp</font> (a b)
+ (let ((result t))
+ (dolist (element a)
+ (when (not (member element b)
+ (setf result nil)
+ (return))))
+ result))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
+
diff --git a/docsrc/xlisp/xlisp-doc/examples/macros.htm b/docsrc/xlisp/xlisp-doc/examples/macros.htm new file mode 100644 index 0000000..1781381 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/macros.htm @@ -0,0 +1,302 @@ +<html><head>
+
+<title>Macros</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Macro Programming</h1>
+
+<hr>
+
+<ul>
+<li><nobr><a href="#with-unique-names">with-unique-names</a> - create local <a href="../reference/gensym.htm">gensym</a> variables</nobr></li>
+</ul>
+
+<p><div class="box">
+
+<p><b>Note:</b> The best book for Lisp macro programming is Paul
+Graham's '<nobr>On Lisp</nobr>', available for free under:</p>
+
+<ul>
+<li><nobr><a href="http://www.paulgraham.com/onlisp.html"
+>http://www.paulgraham.com/onlisp.html</a></nobr></li>
+</ul>
+
+</div></p>
+
+<a name="with-unique-names"></a>
+
+<hr>
+
+<h2>with-unique-names</h2>
+
+<hr>
+
+<p>See <a href="http://www.cliki.net/WITH-UNIQUE-NAMES"
+>http://www.cliki.net/WITH-UNIQUE-NAMES</a>. This macro also appears in
+<nobr>Chapter 11</nobr> of Paul Graham's
+<nobr><a href="http://www.paulgraham.com/onlisp.html">On Lisp</a></nobr>
+under the name '<nobr>with-gensyms</nobr>'.</p>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>with-unique-names</b> (<i>symbols</i>) <i>body</i>)</nobr></dt>
+<dd><i>symbols</i> - a list of Lisp symbols, representing variable names<br>
+<i>body</i> - some Lisp code to execute<br>
+returns - the <i>body</i> with all <i>symbols</i> bound to different
+<a href="../reference/gensym.htm">gensym</a>s</dd>
+</dl>
+
+</div></p>
+
+<p>The '<nobr>with-unique-names</nobr>' macro helps to avoid name clashes in
+Lisp macros.</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">with-unique-names</font> (symbols &rest body)
+ `(let ,(mapcar #'(lambda (x) `(,x (gensym))) symbols) ,@body))
+</pre>
+
+<p>The '<nobr>with-unique-names</nobr>' macro belongs to the category of
+<nobr>write-only</nobr> code. <nobr>No matter</nobr> how you write it, it's
+nearly impossible to understand its meaning by reading the macro definition.
+<nobr>It's easier</nobr> to understand if you look at the macro
+expansion:</p>
+
+<pre class="example">
+> (macroexpand-1 '(with-unique-names (a b c)
+ `(let ((,a 1) (,b 2) (,c 3))
+ (list ,a ,b ,c))))
+
+(let ((a (gensym)) (b (gensym)) (c (gensym)))
+ `(let ((,a 1) (,b 2) (,c 3))
+ (list ,a ,b ,c)))
+</pre>
+
+<p>This translates in practice to the following idea:</p>
+
+<pre class="example">
+(let ((a (gensym)) (b (gensym)) (c (gensym))) <font color="#008844">; outside the expansion</font>
+ `(let ((<font color="#AA5500">gensym1</font> 1) (<font color="#AA5500">gensym2</font> 2) (<font color="#AA5500">gensym3</font> 3)) <font color="#008844">; inside the expansion</font>
+ (list <font color="#AA5500">gensym1 gensym2 gensym3</font>)))
+</pre>
+
+<p>The variable names 'a', 'b', and 'c' have been replaced inside the macro
+expansion by three <a href="../reference/gensym.htm">gensym</a>s. This way a
+variable name inside the macro expansion cannot accidentally collide with a
+variable of the same name in the environment of the macro's expansion like
+shown here:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">print-macro</font> (x) <font color="#008844">; bad example</font>
+ `(let ((<font color="#AA0000">macro-var</font> 'macro))
+ (print ,x)))
+
+> (let ((<font color="#AA0000">local-var</font> 'let)) <font color="#008844">; this works</font>
+ (print local-var)
+ (print-macro local-var))
+LET <font color="#008844">; printed by PRINT</font>
+LET <font color="#008844">; printed by PRINT-MACRO</font>
+
+> (let ((<font color="#AA0000">macro-var</font> 'let)) <font color="#008844">; this doesn't</font>
+ (print macro-var)
+ (print-macro macro-var))
+LET <font color="#008844">; printed by PRINT</font>
+MACRO <font color="#008844">; printed by PRINT-MACRO</font>
+</pre>
+
+<p>The reason for this behaviour is that the '<nobr>print-macro</nobr>'
+<nobr>expands to:</nobr></p>
+
+<pre class="example">
+> (let ((<font color="#AA0000">local-var</font> 'let)) <font color="#008844">; this works</font>
+ (print local-var)
+ (let ((<font color="#AA0000">macro-var</font> 'macro))
+ (print local-var)))
+LET <font color="#008844">; LOCAL-VAR inside the first LET</font>
+LET <font color="#008844">; LOCAL-VAR inside the second LET</font>
+
+> (let ((<font color="#AA0000">macro-var</font> 'let)) <font color="#008844">; this doesn't</font>
+ (print macro-var)
+ (let ((<font color="#AA0000">macro-var</font> 'macro))
+ (print macro-var)))
+LET <font color="#008844">; MACRO-VAR inside the first LET</font>
+MACRO <font color="#008844">; MACRO-VAR inside the second LET</font>
+</pre>
+
+<p>Now the same example with unique names. Note the
+<a href="..reference/backquote.htm">comma</a> before the
+'<nobr>macro-var</nobr>' inside the
+<nobr><a href="../reference/let.htm">let</a> form of the macro
+definition:</nobr></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">print-macro</font> (x) <font color="#008844">; good example</font>
+ (with-unique-names (<font color="#AA0000">macro-var</font>)
+ `(let ((,<font color="#AA0000">macro-var</font> 'macro))
+ (print ,x))))
+
+> (let ((<font color="#AA0000">macro-var</font> 'let)) <font color="#008844">; now it works</font>
+ (print macro-var)
+ (print-macro macro-var))
+LET <font color="#008844">; printed by PRINT</font>
+LET <font color="#008844">; printed by PRINT-MACRO</font>
+</pre>
+
+<p>The reason why it works is that the '<nobr>print-macro</nobr>' now
+<nobr>expands to:</nobr></p>
+
+<pre class="example">
+> (let ((<font color="#AA0000">macro-var</font> 'let)) <font color="#008844">; works</font>
+ (print macro-var)
+ (let ((<font color="#AA5500">gensym</font> 'macro))
+ (print macro-var)))
+LET <font color="#008844">; MACRO-VAR inside the first LET</font>
+LET <font color="#008844">; MACRO-VAR inside the second LET</font>
+</pre>
+
+<nobr>Now '<nobr>macro-var</nobr>' can even be used as a variable name
+inside the macro definition without colliding with the
+'<nobr>macro-var</nobr>' bound
+<nobr>by <a href="../reference/let.htm">let</a>:</nobr></nobr>
+
+<pre class="example">
+(defmacro <font color="#0000CC">print-macro</font> (x) <font color="#008844">; good example</font>
+ (with-unique-names (<font color="#AA0000">macro-var</font>)
+ `(let ((,<font color="#AA0000">macro-var</font> 'macro))
+ (print ,<font color="#AA0000">macro-var</font>)
+ (print ,x))))
+
+> (let ((<font color="#AA0000">macro-var</font> 'let)) <font color="#008844">; works</font>
+ (print macro-var)
+ (print-macro macro-var))
+LET <font color="#008844">; MACRO-VAR printed inside LET</font>
+MACRO <font color="#008844">; GENSYMed MACRO-VAR, printed inside PRINT-MACRO</font>
+LET <font color="#008844">; MACRO-VAR bound by LET, printed inside PRINT-MACRO</font>
+</pre>
+
+<p>The expansion of the '<nobr>print-macro</nobr>' shows why this works:</p>
+
+<pre class="example">
+> (let ((<font color="#AA0000">macro-var</font> 'let)) <font color="#008844">; works</font>
+ (print macro-var)
+ (let ((<font color="#AA5500">gensym</font> 'macro))
+ (print <font color="#AA5500">gensym</font>)
+ (print macro-var)))
+LET <font color="#008844">; MACRO-VAR printed inside LET</font>
+MACRO <font color="#008844">; GENSYMed MACRO-VAR printed inside PRINT-MACRO</font>
+LET <font color="#008844">; MACRO-VAR bound by LET, printed inside PRINT-MACRO</font>
+</pre>
+
+<p>You can give as many variable names as you like to
+'<nobr>with-unique-names</nobr>', the
+<a href="../reference/gensym.htm">gensym</a> management is done
+automatically:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">print-macro</font> (x y z)
+ (with-unique-names (a b c)
+ `(let ((,a 1) (,b 2) (,c 3))
+ (format t <font color="#880000">"outside: a: ~a b: ~a c: ~a~%"</font> ,x ,y ,z)
+ (format t <font color="#880000">" inside: a: ~a b: ~a c: ~a~%"</font> ,a ,b ,c))))
+
+> (let ((a 'a) (b 'b) (c 'c))
+ (print-macro a b c))
+outside: a: A b: B c: C
+ inside: a: 1 b: 2 c: 3
+</pre>
+
+<p>Two things you still have to care about:</p>
+
+<ol>
+
+<li><p>The 'unique names' should not use the same smbol names as the
+parameter variables of the macro, otherwise you will have the same
+'shadowing' effect like in ordinary Lisp functions. This is not a real
+problem because when writing a macro you can see the parameter names before
+your eyes, while you usually cannot see the variable names of the
+environment, where the macro will be expanded. <nobr>You also</nobr> do not
+have to care which variable names had been used in a macro if you call the
+macro from arbitrary Lisp code, where you usually cannot see the code of the
+macro definition.</p></li>
+
+<li><p>The local <a href="../reference/gensym.htm">gensym</a>ed variables
+now themselves must be expanded by writing a
+<a href="../reference/backquote.htm">comma</a> in front of each when they appear
+inside a <a href="../reference/backquote.htm">backquote</a> scope.
+This sometimes can lead to tricky situations, because the
+<a href="../reference/backquote.htm">comma</a> expansion of the symbol does not
+produce the variable's value, instead it produces the name of the
+<a href="../reference/gensym.htm">gensym</a>, which holds the value.
+<nobr>But this</nobr> is a general phenomenon of
+<a href="../reference/gensym.htm">gensym</a>s in Lisp macro programming
+and not a bug of the '<nobr>with-unique-names</nobr>' macro.</p></li>
+
+</ol>
+
+<p>The alternative would be writing:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">print-macro</font> (x y z)
+ (let ((a (gensym)) (b (gensym)) (c (gensym)))
+ `(let ((,a 1) (,b 2) (,c 3))
+ (format t <font color="#880000">"outside: a: ~a b: ~a c: ~a~%"</font> ,x ,y ,z)
+ (format t <font color="#880000">" inside: a: ~a b: ~a c: ~a~%"</font> ,a ,b ,c))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/math.htm b/docsrc/xlisp/xlisp-doc/examples/math.htm new file mode 100644 index 0000000..b1a6414 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/math.htm @@ -0,0 +1,824 @@ +<html><head>
+
+<title>Math</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Math</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#number-types">Number Types</a></nobr></li>
+<li><nobr><a href="#integer-limits">Integer Limits</a></nobr></li>
+<li><nobr><a href="#rounding-and-truncation">Rounding and Truncation</a></nobr></li>
+<ul>
+<li><nobr><a href="#cl-round">cl:round</a> - round towards the next integer</nobr></li>
+<li><nobr><a href="#cl-truncate">cl:truncate</a> - truncate towards zero</nobr></li>
+<li><nobr><a href="#cl-ceiling">cl:ceiling</a> - truncate towards positive infinity</nobr></li>
+<li><nobr><a href="#cl-floor">cl:floor</a> - truncate towards negative infinity</nobr></li>
+</ul>
+<li><nobr><li><nobr><a href="#remainder-and-modulus">Remainder and Modulus</a></nobr></li></nobr></li>
+<ul>
+<li><nobr><a href="#cl-rem">cl:rem</a></nobr></li>
+<li><nobr><a href="#cl-mod">cl:mod</a></nobr></li>
+</ul>
+<li><nobr>Power and Roots</nobr></li>
+<ul>
+<li><nobr><a href="#cl-exp">cl:exp</a> - compute 'e' to the power of 'x'</nobr></li>
+<li><nobr><a href="#cl-expt">cl:expt</a> - compute 'x' to the power of 'y'</nobr></li>
+<li><nobr><a href="#cl-log">cl:log</a></nobr></li>
+<li><nobr><a href="#cl-sqrt">cl:sqrt</a></nobr></li>
+</ul>
+</ol>
+
+<hr>
+
+<h2>Number Types</h2>
+
+<hr>
+
+<p>Nyquist/XLISP only knows two types of numers:</p>
+
+<ul>
+<li><nobr><b>fixnum</b> - integer numbers</nobr></li>
+<li><nobr><b>flonum</b> - floating-point numbers</nobr></li>
+</ul>
+
+<p>In Nyquist/XLISP, there are no ratios or complex numbers. Even if the
+math functions on this page are modelled after <nobr>Common Lisp</nobr>, no
+attempt is made to emulate these numbers.</p>
+
+<a name="integer-limits"></a>
+
+<hr>
+
+<h2>Integer Limits</h2>
+
+<hr>
+
+<pre class="example">
+(setq <font color="#AA5500">*most-positive-fixnum*</font> 2147483647)
+(setq <font color="#AA5500">*most-negative-fixnum*</font> -2147483648)
+</pre>
+
+<p><b>Note:</b> these are the limits for <nobr>32-bit</nobr> machines.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">fixnum-bits</font> ()
+ (dolist (bits '(15 31 63) nil)
+ (let ((fixnum (round (expt 2.0 bits))))
+ (and (plusp (1- fixnum))
+ (minusp fixnum)
+ (return (1+ bits))))))
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">fixnum-limits</font> ()
+ (if (dolist (bits '(15 31 63) nil)
+ (let* ((negative (round (expt 2.0 bits)))
+ (positive (1- negative)))
+ (when (and (plusp positive)
+ (minusp negative))
+ (setq most-positive-fixnum positive
+ most-negative-fixnum negative)
+ (return t))))
+ most-positive-fixnum
+ (error <font color="#880000">"fixnum limit not found"</font>)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="print-float"></a>
+
+<hr>
+
+<h2>print-float</h2>
+
+<hr>
+
+<p>The '<nobr>print-float</nobr>' function prints
+<nobr>floating-point</nobr> numbers ending in '.0' as
+<nobr>floating-point</nobr> numbers and not as integers:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">print-float</font> (item)
+ (if (not (floatp item))
+ item
+ (let ((string (format nil <font color="#880000">"~a"</font> item)))
+ (if (not (string-search <font color="#880000">"."</font> string))
+ (strcat string <font color="#880000">".0"</font>)
+ string))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="divide-float"></a>
+
+<hr>
+
+<h2>divide-float</h2>
+
+<hr>
+
+<p>An easy way to force a sequence of integers to be divided as floating
+point numbers is to insert the number 1.0 after the first argument in the
+list of arguments to the divider function or to explicitely convert the
+first argument into a floating point number by using the XLISP <a
+href="float.htm">float</a> function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">divide-float</font> (&rest args)
+ (if (null args)
+ (error <font color="#880000">"too few arguments"</font>)
+ (apply #'/ (cons (float (first args)) (rest args)))))
+</pre>
+
+<p>See <a href="apply.htm">apply</a>, <a href="cons.htm">cons</a>,
+<a href="defun.htm">defun</a>, <a href="error.htm">error</a>,
+<a href="first.htm">first</a>, <a href="float.htm">float</a>,
+<a href="if.htm">if</a>, <a href="null.htm">null</a>,
+<a href="rest.htm">rest</a>,
+<a href="lambda-keyword-rest.htm">&rest</a>.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(divide-float 1) => 1.0
+(divide-float 1 2) => 0.5
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="rounding-and-truncation"></a>
+
+<hr>
+
+<h2>Rounding and Truncation</h2>
+
+<hr>
+
+<p>The <a href="#cl-round">cl:round</a>,
+<a href="#cl-truncate">cl:truncate</a>,
+<a href="#cl-ceiling">cl:ceiling</a> and
+<a href="#cl-floor">cl:floor</a> functions divide a number by a divisor,
+returning a quotient and a remainder:</p>
+
+<p><div class="box">
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="#cl-round">cl:round</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="#cl-truncate">cl:truncate</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="#cl-ceiling">cl:ceiling</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="#cl-floor">cl:floor</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+</tbody></table></p>
+
+<p><nobr>
+<i>quotient</i> * <i>divisor</i> + <i>remainder</i> = <i>number</i></nobr></p>
+
+</div></p>
+
+<p>The 'quotient' always represents a mathematical integer. <nobr>The
+'remainder'</nobr> is an integer if both 'number' and 'divisor' arguments
+are integers, and a <nobr>floating-point</nobr> number if either the
+'number' or the 'divisor' or both are <nobr>floating-point</nobr>
+numbers.</p>
+
+<p>With Nyquist/XLISP, the 'quotient' is always directly returned by the
+function, while a list:</p>
+
+<pre class="example">
+(<font color="#0000CC">quotient remainder</font>)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="values.htm#cl-global-multiple-values">cl:*multiple-values*</a> is
+set to <a href="../reference/t.htm"> T </a> to signal that
+<a href="values.htm">Multiple Values</a> are returned.</p>
+
+Examples:
+
+<pre class="example">
+(cl:round 3.5) => 4 <font color="#008844">; *rslt* = ( 4 -0.5)</font>
+(cl:truncate 3.5) => 3 <font color="#008844">; *rslt* = ( 3 0.5)</font>
+(cl:ceiling 3.5) => 4 <font color="#008844">; *rslt* = ( 4 -0.5)</font>
+(cl:floor 3.5) => 3 <font color="#008844">; *rslt* = ( 3 0.5)</font>
+
+(cl:round -3.5) => -4 <font color="#008844">; *rslt* = (-4 0.5)</font>
+(cl:truncate -3.5) => -3 <font color="#008844">; *rslt* = (-3 -0.5)</font>
+(cl:ceiling -3.5) => -3 <font color="#008844">; *rslt* = (-3 -0.5)</font>
+(cl:floor -3.5) => -4 <font color="#008844">; *rslt* = (-4 0.5)</font>
+</pre>
+
+Force integer division:
+
+<pre class="example">
+(cl:truncate 3.0 2.0) => 1
+(/ (truncate 3.0) (truncate 2.0)) => 1
+(/ 3 4) => 1
+</pre>
+
+<p><div class="box">
+
+<p><b>Implementation Notes</b></p>
+
+<pre class="example">
+(defun <font color="#0000CC">name</font> (number &optional (divisor (if (<font color="#AA0000">integerp</font> number) 1 1.0)))
+ ... )
+</pre>
+
+<p>The <a href="../reference/integerp.htm">integerp</a> test in the
+parameter list signals an error if the 'number' argument is not a number,
+also the <nobr><a href="../reference/division.htm"> / </a>
+[division]</nobr> function signals errors if the 'divisor' argument is zero
+or not a number, so we do not explicitely need to test the arguments.</p>
+
+<p>The <nobr><a href="#cl-ceiling">cl:ceiling</a></nobr> and <nobr><a
+href="#cl-floor">cl:floor</a></nobr> functions test if 'number' is an
+integer multiple of 'divisor' by comparing the results of an integer
+division and a <nobr>floating-point</nobr> division:</p>
+
+<pre class="example">
+(let ((<font color="#AA0000">i-quotient</font> (/ (truncate number) (truncate divisor)))
+ (<font color="#AA0000">f-quotient</font> (/ (float number) divisor)))
+ (if (= <font color="#AA0000">i-quotient f-quotient</font>)
+ ...
+</pre>
+
+<p>I'm not sure if this really catches all cases <nobr>[e.g.
+regarding</nobr> floating point precision], but have found no problems so
+far.</p>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-round"></a>
+
+<hr>
+
+<h2>cl:round</h2>
+
+<hr>
+
+<p>The '<nobr>cl:round</nobr>' function truncates towards the next
+integer:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>round</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of runding the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the round operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:round</font> (number &optional (divisor
+ (if (integerp number) 1 1.0)
+ divisor-p))
+ (let* ((x (/ (float number) divisor))
+ (quotient (cond ((and (not divisor-p) (integerp number)) number)
+ ((= number divisor) 1)
+ ((plusp x) (truncate (+ x 0.5)))
+ ((= (- x 0.5) (truncate (- x 0.5)))
+ (if (minusp x)
+ (1- (truncate x))
+ (truncate x)))
+ (t (truncate (- x 0.5))))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The '<nobr>cl:round</nobr>' function computes a quotient that has been rounded to the
+nearest mathematical integer. <nobr>If the</nobr> mathematical quotient is
+exactly halfway between two integers, [that is, it has the form
+<nobr>'integer+1/2']</nobr>, then the quotient has been rounded to the even
+[divisible <nobr>by two]</nobr> integer. <nobr>See
+<a href="#rounding-and-truncation">Rounding and Truncation</a></nobr>
+above for more details.</p>
+
+<pre class="example">
+(round 3.5) => 4
+(round -3.5) => -3
+
+(cl:round 3.5) => 4 <font color="#008844">; *rslt* = ( 4 -0.5)</font>
+(cl:round -3.5) => -4 <font color="#008844">; *rslt* = (-4 0.5)</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-truncate"></a>
+
+<hr>
+
+<h2>cl:truncate</h2>
+
+<hr>
+
+<p>The '<nobr>cl:truncate</nobr>' function truncates towards zero:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>truncate</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of truncating the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the truncate operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:truncate</font> (number &optional (divisor (if (integerp number) 1 1.0)))
+ (let ((quotient (truncate (/ (float number) divisor))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The '<nobr>cl:truncate</nobr>' function computes a quotient that has been
+truncated towards zero. That is, the quotient represents the mathematical
+integer of the same sign as the mathematical quotient, and that has the
+greatest integral magnitude not greater than that of the mathematical
+quotient. <nobr>See
+<a href="#rounding-and-truncation">Rounding and Truncation</a></nobr>
+above for more details.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-ceiling"></a>
+
+<hr>
+
+<h2>cl:ceiling</h2>
+
+<hr>
+
+<p>The '<nobr>cl:ceiling</nobr>' function truncates towards positive
+infinity:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>ceiling</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of truncating the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the truncate operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:ceiling</font> (number &optional (divisor
+ (if (integerp number) 1 1.0)
+ divisor-p))
+ (let ((quotient
+ (cond ((and (not divisor-p) (integerp number)) number)
+ ((= number divisor) 1)
+ (t (let ((i-quotient (/ (truncate number) (truncate divisor)))
+ (f-quotient (/ (float number) divisor)))
+ (if (or (= i-quotient f-quotient) <font color="#008844">; integer result</font>
+ (not (plusp f-quotient)))
+ (truncate f-quotient)
+ (1+ (truncate f-quotient))))))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The '<nobr>cl:ceiling</nobr>' function computes a quotient that has been
+truncated toward positive infinity. That is, the quotient represents the
+smallest mathematical integer that is not smaller than the mathematical
+result. <nobr>See
+<a href="#rounding-and-truncation">Rounding and Truncation</a></nobr>
+above for more details.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-floor"></a>
+
+<hr>
+
+<h2>cl:floor</h2>
+
+<hr>
+
+<p>The '<nobr>cl:floor</nobr>' function truncates towards negative infinity:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>floor</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of truncating the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the truncate operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:floor</font> (number &optional (divisor
+ (if (integerp number) 1 1.0)
+ divisor-p))
+ (let ((quotient
+ (cond ((and (not divisor-p) (integerp number)) number)
+ ((= number divisor) 1)
+ (t (let ((i-quotient (/ (truncate number) (truncate divisor)))
+ (f-quotient (/ (float number) divisor)))
+ (if (or (= i-quotient f-quotient) <font color="#008844">; integer result</font>
+ (not (minusp f-quotient)))
+ (truncate f-quotient)
+ (1- (truncate f-quotient))))))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The <nobr>'cl:floor</nobr>' function computes a quotient that has been
+truncated toward negative infinity. That is, the quotient represents the
+largest mathematical integer that is not larger than the mathematical
+quotient. <nobr>See
+<a href="#rounding-and-truncation">Rounding and Truncation</a></nobr>
+above for more details.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="remainder-and-modulus"></a>
+
+<hr>
+
+<h2>Remainder and Modulus</h2>
+
+<hr>
+
+<p>The <a href="#cl-mod">cl:mod</a> and <a href="#cl-rem">cl:rem</a>
+function are generalizations of the modulus and remainder functions.
+<nobr>The <a href="#cl-mod">cl:mod</a></nobr> function performs the
+<a href="#cl-floor">cl:floor</a> operation on its arguments and returns the
+remainder of the <a href="#cl-floor">cl:floor</a> operation.
+<nobr>The <a href="#cl-rem">cl:rem</a></nobr> function performs the
+<a href="cl-truncate">cl:truncate</a> operation on its arguments and returns
+the remainder of the <a href="cl-truncate">cl:truncate</a> operation.
+<nobr>The <a href="#cl-mod">cl:mod</a></nobr> and
+<a href="#cl-rem">cl:rem</a> functions are the modulus and remainder
+functions when the 'number' and 'divisor' arguments both are integers.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-rem"></a>
+
+<hr>
+
+<h2>cl:rem</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>rem</b> <i>number divisor</i>)</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+<i>divisor</i> - an integer or floating-point number<br>
+returns - the remainder of a <a href="cl-truncate">cl:truncate</a> operation</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:rem</font> (number divisor)
+ (if (= (abs number) (abs divisor))
+ (if (and (integerp number) (integerp divisor)) 0 0.0)
+ (let ((quotient (truncate (/ (float number) divisor))))
+ (- number (* quotient divisor)))))
+</pre>
+
+<p>The '<nobr>cl:rem</nobr>' function performs the
+<a href="cl-truncate">cl:truncate</a> operation on its arguments and returns
+the remainder of the <a href="cl-truncate">cl:truncate</a> operation.
+<nobr>The result</nobr> is either zero or an integer or
+<nobr>floating-point</nobr> number with the same sign as the 'number'
+argument. <nobr>If both</nobr> arguments are integer numbers, the
+'<nobr>cl:rem</nobr>' function is equal to the mathematical remainder
+function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-mod"></a>
+
+<hr>
+
+<h2>cl:mod</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>mod</b> <i>number divisor</i>)</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+<i>divisor</i> - an integer or floating-point number<br>
+returns - the remainder of a <a href="#cl-floor">cl:floor</a> operation</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:mod</font> (number divisor)
+ (if (= (abs number) (abs divisor))
+ (if (and (integerp number) (integerp divisor)) 0 0.0)
+ (let* ((i-quotient (/ (truncate number) (truncate divisor)))
+ (f-quotient (/ (float number) divisor))
+ (quotient (if (or (= i-quotient f-quotient) <font color="#008844">; integer result</font>
+ (not (minusp f-quotient)))
+ (truncate f-quotient)
+ (1- (truncate f-quotient)))))
+ (- number (* quotient divisor)))))
+</pre>
+
+<p>The '<nobr>cl:mod</nobr>' function performs the
+<a href="#cl-floor">cl:floor</a> operation on its arguments and returns the
+remainder of the <a href="#cl-floor">cl:floor</a> operation. <nobr>The
+result</nobr> is either zero or an integer or <nobr>floating-point</nobr>
+number with the same sign as the 'divisor' argument. <nobr>If both</nobr>
+arguments are integer numbers, the '<nobr>cl:rem</nobr>' function is equal
+to the mathematical modulus function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-exp"></a>
+
+<hr>
+
+<h2>cl:exp</h2>
+
+<hr>
+
+<p>The '<nobr>cl:exp</nobr>' function does the same as the Nyquist/XLISP
+<a href="../reference/exp.htm">exp</a> function, but it also accepts
+integer numbers as argument:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>exp</b> <i>power</i>)</dt>
+<dd><i>power</i> - an integer or floating-point number<br>
+returns - the result of <nobr>'e' [2.7128]</nobr> to the power of <i>power</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:exp</font> (x)
+ (exp (float x)))
+</pre>
+
+<p>The '<nobr>cl:exp</nobr>' function computes <nobr>'e' [2.7128]</nobr>
+raised to the specified 'power'. <nobr>The result</nobr> is always a
+<nobr>floating-point</nobr> number.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-expt"></a>
+
+<hr>
+
+<h2>cl:expt</h2>
+
+<hr>
+
+<p>The '<nobr>cl:expt</nobr>' function computes the result of 'x' to the
+power <nobr>of 'y'</nobr>:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>expt</b> <i>base power</i>)</dt>
+<dd><i>base</i> - the base<br>
+<i>power</i> - the exponent<br>
+returns - the result of <i>base</i> to the power of <i>power</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:expt</font> (x y)
+ (let ((power (expt (float x) y)))
+ (if (and (integerp x) (integerp y))
+ (round power)
+ power)))
+</pre>
+
+<p>See <a href="../reference/and.htm">and</a>,
+<a href="../reference/defun.htm">defun</a>,
+<a href="../reference/expt.htm">expt</a>,
+<a href="../reference/float.htm">float</a>,
+<nobr><a href="../reference/if.htm"> if </a></nobr>,
+<a href="../reference/integerp.htm">integerp</a>,
+<a href="../reference/let.htm">let</a>,
+<a href="../reference/power.htm">power</a>,
+<a href="../reference/round.htm">round</a>.</p>
+
+<p>The '<nobr>cl:expt</nobr>' function accepts integer and floating point
+numbers as arguments. <nobr>If both</nobr> arguments are integer numbers,
+the result will be an integer number, <nobr>if one</nobr> or both arguments
+are <nobr>floating-point</nobr> numbers, the result will be a
+<nobr>floating-point</nobr> number. <nobr>In contrast</nobr> to the
+Nyquist/XLISP <a href="../reference/expt.htm">expt</a> function, the
+'<nobr>cl:expt</nobr>' function specifies exactly two arguments.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-log"></a>
+
+<hr>
+
+<h2>cl:log</h2>
+
+<hr>
+
+<p>The '<nobr>cl:log</nobr>' function does the same as the Nyquist/XLISP
+<a href="../reference/log.htm">log</a> function, but also accepts
+integer numbers and has an optional 'base' argument:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>log</b> <i>number</i> [<i>base</i>])</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+<i>base</i> - an integer or floating-point number<br>
+returns - the the logarithm of <i>number</i> in base <i>base</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:log</font> (number &optional base)
+ (if base
+ (if (zerop base)
+ 0.0
+ (/ (log (float number)) (log (float base))))
+ (log (float number))))
+</pre>
+
+<p>The '<nobr>cl:log</nobr>' function returns the logarithm of 'number' in
+base 'base'. <nobr>If 'base'</nobr> is not supplied its value <nobr>is
+'e'</nobr>, the base of the natural logarithms. <nobr>If the</nobr> 'base'
+argument is zero, then 'cl:log' returns zero. <nobr>The result</nobr> is
+always a <nobr>floating-point</nobr> number.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-sqrt"></a>
+
+<hr>
+
+<h2>cl:sqrt</h2>
+
+<hr>
+
+<p>The '<nobr>cl:sqrt</nobr>' function does the same as the Nyquist/XLISP
+<a href="../reference/sqrt.htm">sqrt</a> function, but it also accepts
+integer numbers as argument:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>sqrt</b> <i>number</i>)</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+returns - the square root of <i>number</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:sqrt</font> (x)
+ (sqrt (float x)))
+</pre>
+
+<p><nobr>The result</nobr> is always a <nobr>floating-point</nobr>
+number.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/octal.htm b/docsrc/xlisp/xlisp-doc/examples/octal.htm new file mode 100644 index 0000000..f72ba4d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/octal.htm @@ -0,0 +1,148 @@ +<html><head>
+
+<title>Octal Integer Numbers</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Octal Integer Numbers</h1>
+
+<hr>
+
+<p>XLISP provides the <a href="../manual/xlisp.htm#octal">#o</a>
+<nobr>read-macro</nobr> for octal numbers:</p>
+
+<pre class="example">
+#o0 => 0 #o10 => 8 #o20 => 16
+#o1 => 1 #o11 => 9 #o21 => 17
+#o2 => 2 #o12 => 10 #o22 => 18
+#o3 => 3 #o13 => 11 #o23 => 19
+#o4 => 4 #o14 => 12 #o24 => 20
+#o5 => 5 #o15 => 13 #o25 => 21
+#o6 => 6 #o16 => 14 #o26 => 22
+#o7 => 7 #o17 => 15 #o27 => 23
+</pre>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>oct-string</b> <i>integer</i> [<i>all</i>])</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>all</i> - a boolean expression<br>
+returns - the <i>integer</i> in octal form as string</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">oct-string</font> (integer &optional all)
+ (if (integerp integer)
+ (let ((fmt (if all
+ (or (dolist (bits '(16 32 64 128) nil)
+ (let ((fixnum (round (expt 2.0 (1- bits)))))
+ (and (plusp (1- fixnum))
+ (minusp fixnum)
+ (return (format nil <font color="#880000">"%.~ao"</font>
+ (1+ (/ bits 3)))))))
+ (error <font color="#880000">"integer limit not found"</font>))
+ <font color="#880000">"%o"</font>)))
+ (progv '(<font color="#AA5500">*integer-format*</font>) (list fmt)
+ (format nil <font color="#880000">"~a"</font> integer)))
+ (error <font color="#880000">"not an integer"</font> integer)))
+</pre>
+
+<p>The '<nobr>oct-string</nobr>' function converts the 'integer' argument
+into octal form and returns is as a string. <nobr>If the</nobr>
+optional 'all' argument is not given or
+<a href="../reference/nil.htm">NIL</a>, leading zeros are not included in
+the string. <nobr>If the</nobr> optional 'all' argument is
+<nobr>non-<a href="../reference/nil.htm">NIL</a></nobr>, all digits of the
+internal representation of the 'integer' argument, including leading zeros,
+are contained in the string. This is useful for debugging integer overflow
+and <nobr>bit-wise</nobr> functions.</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>oct</b> <i>integer</i> [<i>all</i>])</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>all</i> - a boolean expression<br>
+prints - the <i>integer</i> in octal form<br>
+returns - the <i>integer</i> argument</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">oct</font> (integer &optional all)
+ (if (integerp integer)
+ (format t <font color="#880000">"#o~a~%"</font> (oct-string integer all))
+ (format t <font color="#880000">";; not an integer~%"</font>))
+ integer)
+</pre>
+
+<p>The 'oct' function prints the 'integer' argument in octal form on
+the screen. Together with the
+<a href="../manual/xlisp.htm#octal">#o</a> <nobr>read-macro</nobr>
+this can be used for interactive octal computations.</p>
+
+<pre class="example">
+> (oct 12345678)
+#o57060516
+12345678
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/posix-chars.htm b/docsrc/xlisp/xlisp-doc/examples/posix-chars.htm new file mode 100644 index 0000000..9e6c4e0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/posix-chars.htm @@ -0,0 +1,459 @@ +<html><head>
+
+<title>Characters and Strings</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>POSIX Character Classes</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#posix-character-classes">POSIX Character Classes</a></nobr></li>
+<li><nobr><a href="#internal-functions">Internal Functions</a></nobr></li>
+<li><nobr><a href="#user-functions">User Functions</a></nobr></li>
+</ol>
+
+<hr>
+
+<h2>POSIX Character Classes</h2>
+
+<hr>
+
+<p>The functions on this page implement tests for the standard POSIX
+character classes, where all functions return the tested character if the
+test succeeds, or <a href="../reference/nil.htm">NIL</a></nobr> if the test
+fails.</p>
+
+<p>The <nobr>built-in</nobr> XLISP character test functions
+<a href="../reference/upper-case-p.htm">upper-case-p</a>,
+<a href="../reference/lower-case-p.htm">lower-case-p</a>,
+<a href="../reference/both-case-p.htm">both-case-p</a>,
+<a href="../reference/alphanumericp.htm">alphanumericp</a>, return the
+boolean values <a href="../reference/t.htm"> T </a> or
+<a href="../reference/nil.htm">NIL</a> instead of the tested character,
+while <a href="../reference/digit-char-p.htm">digit-char-p</a> returns an
+integer <nobr>or <a href="../reference/nil.htm">NIL</a></nobr>, what is
+handy if you want to convert arbitrary Lisp symbols into numbers without
+producing an error, but all this is impractical for writing a string
+parser.</p>
+
+<p><nobr>The <a href="#internal-functions">Internal Functions</a></nobr>
+do not check if the argument is a character and therefore are faster than
+the <nobr><a href="#user-functions">User Functions</a></nobr>. Also note
+that XLISP is limited to ASCII characters, so there is no way to find out if
+an unicode character is upper- or lowercase if the character code is greater
+than <nobr>ASCII 127</nobr>.</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td colspan="3"><nobr><b>POSIX</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><b>Internal</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><b>User Function</b></nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>alnum</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-alnum-p">char:alnum-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#alnum-character-p">alnum-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>alphanumeric = [a-z], [A-Z], [0-9]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>alpha</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-alpha-p">char:alpha-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#alpha-character-p">alpha-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>alphabetic = [a-z], [A-Z]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>blank</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-blank-p">char:blank-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#blank-character-p">blank-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>space and horizontal-tab</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>cntrl</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-cntrl-p">char:cntrl-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#cntrl-character-p">cntrl-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>code-chars 0-31 and 127</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>digit</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-digit-p">char:digit-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#digit-character-p">digit-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>decimal = [0-9]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>graph</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-graph-p">char:graph-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#graph-character-p">graph-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>graphical = alnum + punct</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>lower</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-lower-p">char:lower-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#lower-character-p">lower-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>lowercase = [a-z]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>print</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-print-p">char:print-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#print-character-p">print-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>printable = alnum + punct + space</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>punct</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-punct-p">char:punct-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#punct-character-p">punct-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>punctuation marks</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>space</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-space-p">char:space-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#space-character-p">space-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>characters producing whitespace</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>upper</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-upper-p">char:upper-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#upper-character-p">upper-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>uppercase = [A-Z]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>xdigit</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-xdigit-p">char:xdigit-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#xdigit-character-p">xdigit-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>hexadecimal = [0-9], [a-f], [A-F]</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>The main difference is:</p>
+
+<pre class="example">
+> (char:alnum-p 'nonsense-value)
+<font color="#AA0000">error: bad argument type - NONSENSE-VALUE</font>
+
+> (alnum-character-p 'nonsense-value)
+NIL
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="internal-functions"></a>
+
+<hr>
+
+<h2>Internal Functions</h2>
+
+<hr>
+
+<p>The internal functions are based on <nobr>built-in</nobr> XLISP
+functions, there are no external dependencies.</p>
+
+<a name="char-alnum-p"></a>
+
+<pre class="example">
+<font color="#008844">;; alphanumeric characters = a-z, A-z, 0-9</font>
+
+(defun <font color="#0000CC">char:alnum-p</font> (char)
+ (and (alphanumericp char)
+ char))
+<a name="char-alpha-p"></a>
+<font color="#008844">;; alphabetic characters = a-z, A-Z</font>
+
+(defun <font color="#0000CC">char:alpha-p</font> (char)
+ (and (both-char-p char)
+ char))
+<a name="char-blank-p"></a>
+<font color="#008844">;; blanks = space and horizontal-tab</font>
+
+(defun <font color="#0000CC">char:blank-p</font> (char)
+ (and (or (char= char #\Space)
+ (char= char #\Tab))
+ char))
+<a name="char-cntrl-p"></a>
+<font color="#008844">;; control characters = code-chars 0-31 and 127</font>
+
+(defun <font color="#0000CC">char:cntrl-p</font> (char)
+ (let ((code (char-code char)))
+ (and (or (<= 0 code 31)
+ (= code 127))
+ char)))
+<a name="char-digit-p"></a>
+<font color="#008844">;; decimal digits = 0-9</font>
+
+(defun <font color="#0000CC">char:digit-p</font> (char)
+ (and (digit-char-p char)
+ char))
+<a name="char-graph-p"></a>
+<font color="#008844">;; graphical characters = alnum + punct</font>
+
+(defun <font color="#0000CC">char:graph-p</font> (char)
+ (and (<= 33 (char-code char) 126)
+ char))
+<a name="char-lower-p"></a>
+<font color="#008844">;; lowercase characters = a-z</font>
+
+(defun <font color="#0000CC">char:lower-p</font> (char)
+ (and (lower-case-p char)
+ char))
+<a name="char-print-p"></a>
+<font color="#008844">;; printable characters = alnum + punct + space</font>
+
+(defun <font color="#0000CC">char:print-p</font> (char)
+ (and (<= 32 (char-code char) 126)
+ char))
+<a name="char-punct-p"></a>
+<font color="#008844">;; punctuation marks</font>
+
+(defun <font color="#0000CC">char:punct-p</font> (char)
+ (let ((code (char-code char)))
+ (and (or (<= 33 code 47) <font color="#008844">; ! " # $ % & ' ( ) * + , - . /</font>
+ (<= 58 code 64) <font color="#008844">; : ; < = > ? @</font>
+ (<= 91 code 96) <font color="#008844">; [ \ ] ^ _ `</font>
+ (<= 123 code 126)) <font color="#008844">; { | } ~</font>
+ char)))
+<a name="char-space-p"></a>
+<font color="#008844">;; characters producing whitespace</font>
+<font color="#008844">;;</font>
+<font color="#008844">;; 9 = horizontal tab 10 = line feed 11 = vertical tab</font>
+<font color="#008844">;; 12 = form feed 13 = carriage return 32 = space</font>
+
+(defun <font color="#0000CC">char:space-p</font> (char)
+ (and (member (char-code char) '(9 10 11 12 13 32))
+ char))
+<a name="char-upper-p"></a>
+<font color="#008844">;; uppercase characters = A-Z</font>
+
+(defun <font color="#0000CC">char:upper-p</font> (char)
+ (and (upper-case-p char)
+ char))
+<a name="char-xdigit-p"></a>
+<font color="#008844">;; hexadecimal digits = 0-9, a-f, A-F</font>
+
+(defun <font color="#0000CC">char:xdigit-p</font> (char)
+ (and (or (digit-char-p char)
+ (let ((code (char-code char)))
+ (or (<= 65 code 70) <font color="#008844">; A-Z</font>
+ (<= 97 code 102)))) <font color="#008844">; a-z</font>
+ char))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="user-functions"></a>
+
+<hr>
+
+<h2>User Functions</h2>
+
+<hr>
+
+<p>The user functions are based on the
+<nobr><a href="#internal-functions">Internal Functions</a></nobr> above.
+There are no other dependencies.</p>
+
+<a name="alnum-character-p"></a>
+
+<pre class="example">
+<font color="#008844">;; alphanumeric characters = a-z, A-z, 0-9</font>
+
+(defun <font color="#0000CC">alnum-character-p</font> (char)
+ (and (characterp char)
+ (char:alnum-p char)))
+<a name="alpha-character-p"></a>
+<font color="#008844">;; alphabetic characters = a-z, A-Z</font>
+
+(defun <font color="#0000CC">alpha-character-p</font> (char)
+ (and (characterp char)
+ (char:alpha-p char)))
+<a name="blank-character-p"></a>
+<font color="#008844">;; blanks = space and horizontal-tab</font>
+
+(defun <font color="#0000CC">blank-character-p</font> (char)
+ (and (characterp char)
+ (char:blank-p char)))
+<a name="cntrl-character-p"></a>
+<font color="#008844">;; control characters = code-chars 0-31 and 127</font>
+
+(defun <font color="#0000CC">cntrl-character-p</font> (char)
+ (and (characterp char)
+ (char:cntrl-p char)))
+<a name="digit-character-p"></a>
+<font color="#008844">;; decimal digits = 0-9</font>
+
+(defun <font color="#0000CC">digit-character-p</font> (char)
+ (and (characterp char)
+ (char:digit-p char)))
+<a name="graph-character-p"></a>
+<font color="#008844">;; graphical characters = alnum + punct</font>
+
+(defun <font color="#0000CC">graph-character-p</font> (char)
+ (and (characterp char)
+ (char:graph-p char)))
+<a name="lower-character-p"></a>
+<font color="#008844">;; lowercase characters = a-z</font>
+
+(defun <font color="#0000CC">lower-character-p</font> (char)
+ (and (characterp char)
+ (char:lower-p char)))
+<a name="print-character-p"></a>
+<font color="#008844">;; printable characters = alnum + punct + space</font>
+
+(defun <font color="#0000CC">print-character-p</font> (char)
+ (and (characterp char)
+ (char:print-p char)))
+<a name="punct-character-p"></a>
+<font color="#008844">;; punctuation marks</font>
+
+(defun <font color="#0000CC">punct-character-p</font> (char)
+ (and (characterp char)
+ (char:punct-p char)))
+<a name="space-character-p"></a>
+<font color="#008844">;; characters producing whitespace</font>
+
+(defun <font color="#0000CC">space-character-p</font> (char)
+ (and (characterp char)
+ (char:space-p char)))
+<a name="upper-character-p"></a>
+<font color="#008844">;; uppercase characters = A-Z</font>
+
+(defun <font color="#0000CC">upper-character-p</font> (char)
+ (and (characterp char)
+ (char:upper-p char)))
+<a name="xdigit-character-p"></a>
+<font color="#008844">;; hexadecimal digits = 0-9, a-f, A-F</font>
+
+(defun <font color="#0000CC">xdigit-character-p</font> (char)
+ (and (characterp char)
+ (char:xdigit-p char)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/predicates.htm b/docsrc/xlisp/xlisp-doc/examples/predicates.htm new file mode 100644 index 0000000..5846f2d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/predicates.htm @@ -0,0 +1,526 @@ +<html><head>
+
+<title>Predicates</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Predicates and Comparison</h1>
+
+<hr>
+
+<p>Lisp has extensive support for <nobr>run-time</nobr> tests.</p>
+
+<p><nobr><b>Generalized Lisp Functions</b> - slower than the build-ins, but no errors</nobr></p>
+
+<ol>
+<li><nobr><a href="#built-in-xlisp-functions">Built-in XLISP Functions</a></nobr></li>
+<li><nobr>Generalized Comparison - one or more arguments</nobr></li>
+<ul>
+<li><nobr><a href="#equalp">equalp</a> - compares expressions with 'equality' functions.</nobr></li>
+</ul>
+<li><nobr>Symbol Predicates - one argument</nobr></li>
+<ul>
+<li><nobr><a href="#variablep">variablep</a> - is this a symbol with a variable value bound to it?</nobr></li>
+<li><nobr><a href="#functionp">functionp</a> - is this a function or a symbol with a function value bound to it?</nobr></li>
+<li><nobr><a href="#specialp">specialp</a> - is this a special form or a symbol with a special form bound to it?</nobr></li>
+<li><nobr><a href="#subrp">macrop</a> - is this a Lisp macro or a symbol with a Lisp macro bound to it?</nobr></li>
+</ul>
+<li><nobr>Function Predicates - one argument</nobr></li>
+<ul>
+<li><nobr><a href="#subrp">subrp</a> - is this a build-in function?</nobr></li>
+<li><nobr><a href="#fsubrp">fsubrp</a> - is this a build-in special form?</nobr></li>
+<li><nobr><a href="#closurep">closurep</a> - is this a user-defined function?</nobr></li>
+</ul>
+<li><nobr>Character Predicates - one argument</nobr></li>
+<ul>
+<li><nobr><a href="strings.htm#posix">POSIX Character Classes</a></nobr></li>
+</ul>
+</ol>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="built-in-xlisp-functions"></a>
+
+<hr>
+
+<h2>Built-in XLISP Functions</h2>
+
+<hr>
+
+<ol>
+<li><nobr><b>Boolean Predicates</b> - one argument [all types]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/not.htm">not</a> - does this expression evaluate to false?</nobr></li>
+</ul>
+<li><nobr><b>Generalized Comparison</b> - two arguments [all types]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/eq.htm">eq</a> - are the expressions identical?</nobr></li>
+<li><nobr><a href="../reference/eql.htm">eql</a> - are the expressions identical or equal numbers?</nobr></li>
+<li><nobr><a href="../reference/equal.htm">equal</a> - do the <a href="../reference/print.htm">print</a>ed expressions look the same?</nobr></li>
+</ul>
+<li><nobr><b>Type Predicates</b> - one argument [all types]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/atom.htm">atom</a> - is this an atom?</nobr></li>
+<li><nobr><a href="../reference/symbolp.htm">symbolp</a> - is this a symbol?</nobr></li>
+<ul>
+<li><nobr><b>Symbol Predicates</b> - one argument [error if not a symbol]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/boundp.htm">boundp</a> - has the symbol a variable value?</nobr></li>
+<li><nobr><a href="../reference/fboundp.htm">fboundp</a> - has the symbol a function value?</nobr></li>
+</ul>
+</ul>
+<li><nobr><a href="../reference/numberp.htm">numberp</a> - is this a number?</nobr></li>
+<ul>
+<li><nobr><b>Number Predicates</b> - one argument [error if not a number]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/plusp.htm">plusp</a> - is the number positive?</nobr></li>
+<li><nobr><a href="../reference/minusp.htm">minusp</a> - is the number negative?</nobr></li>
+<li><nobr><a href="../reference/zerop.htm">zerop</a> - is the number equal to zero?</nobr></li>
+<li><nobr><a href="../reference/integerp.htm">integerp</a> - is the number an integer?</nobr></li>
+<ul>
+<li><nobr><b>Integer Predicates</b> - one argument [error if not an integer]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/evenp.htm">evenp</a> - is the integer even?</nobr></li>
+<li><nobr><a href="../reference/oddp.htm">oddp</a> - is the integer odd?</nobr></li>
+</ul>
+</ul>
+<li><nobr><a href="../reference/floatp.htm">floatp</a> - is the number a floating-point number?</nobr></li>
+</ul>
+<li><nobr><b>Numerical Comparison</b> - one or more arguments [error if not numbers only]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/number-lessp.htm"> < </a> - true if all numbers are monotonically increasing</nobr></li>
+<li><nobr><a href="../reference/number-not-greaterp.htm"> <= </a> - true if all numbers are monotonically nondecreasing</nobr></li>
+<li><nobr><a href="../reference/number-equal.htm"> = </a> - true if all all numbers are the same value</nobr></li>
+<li><nobr><a href="../reference/number-not-equal.htm"> /= </a> - true if no two numbers have the same value</nobr></li>
+<li><nobr><a href="../reference/number-not-lessp.htm"> >= </a> - true if all numbers are monotonically nonincreasing</nobr></li>
+<li><nobr><a href="../reference/number-greaterp.htm"> > </a> - true if all numbers are monotonically decreasing</nobr></li>
+</ul>
+</ul>
+<li><nobr><a href="../reference/null.htm">null</a> - is this an empty list?</nobr></li>
+<li><nobr><a href="../reference/consp.htm">consp</a> - is it a non-empty list?</nobr></li>
+<li><nobr><a href="../reference/listp.htm">listp</a> - is this a list?</nobr></li>
+<ul>
+<li><nobr><b>List Predicates</b> - one argument [error if not a list]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/endp.htm">endp</a> - is this the end of a list?</nobr></li>
+</ul>
+</ul>
+<li><nobr><a href="../reference/stringp.htm">stringp</a> - is this a string?</nobr></li>
+<ul>
+<li><nobr><b>String Comparison</b> - one or more arguments [error if not strings only]</nobr></li>
+<ul>
+<li><nobr>Case Sensitive</nobr></li>
+<ul>
+<li><nobr><a href="../reference/string-lessp-s.htm">string<</a> - test for less than in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/string-not-greaterp-s.htm">string<=</a> - test for less than or equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/string-equal-s.htm">string=</a> - test for equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/string-not-equal-s.htm">string/=</a> - test for not equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/string-not-lessp-s.htm">string>=</a> - test for greater than or equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/string-greaterp-s.htm">string></a> - test for greater than in ASCII ordering</nobr></li>
+</ul>
+<li><nobr>Case Insensitive</nobr></li>
+<ul>
+<li><nobr><a href="../reference/string-lessp-i.htm">string-lessp</a> - is this less than in ASCII ordering ?</nobr></li>
+<li><nobr><a href="../reference/string-not-greaterp-i.htm">string-not-greaterp</a> - is this not greater than in ASCII ordering ?</nobr></li>
+<li><nobr><a href="../reference/string-equal-i.htm">string-equal</a> - is this equal in ASCII ordering ?</nobr></li>
+<li><nobr><a href="../reference/string-not-equal-i.htm">string-not-equal</a> - is this not equal in ASCII ordering ?</nobr></li>
+<li><nobr><a href="../reference/string-not-lessp-i.htm">string-not-lessp</a> - is this not less than in ASCII ordering ?</nobr></li>
+<li><nobr><a href="../reference/string-greaterp-i.htm">string-greaterp</a> - is this greater than in ASCII ordering ?</nobr></li>
+</ul>
+<li><nobr>See also <a href="strings.htm#unicode">Unicode</a> examples.</nobr></li>
+</ul>
+</ul>
+<li><nobr><a href="../reference/characterp.htm">characterp</a> - is this a character?</nobr></li>
+<ul>
+<li><nobr><b>Character Predicates</b> - one argument [error if not a character]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/upper-case-p.htm">upper-case-p</a> - is this an upper case character?</nobr></li>
+<li><nobr><a href="../reference/lower-case-p.htm">lower-case-p</a> - is this a lower case character?</nobr></li>
+<li><nobr><a href="../reference/both-case-p.htm">both-case-p</a> - is this an alphabetic [either case] character?</nobr></li>
+<li><nobr><a href="../reference/digit-char-p.htm">digit-char-p</a> - is this a digit character?</nobr></li>
+<li><nobr><a href="../reference/alphanumericp.htm">alphanumericp</a> - is this an alphabetic or a digit character?</nobr></li>
+<li><nobr>See also <a href="strings.htm#posix">POSIX Character Classes</a>.</nobr></li>
+</ul>
+<li><nobr><b>Character Comparison</b> - one or more arguments [error if not characters only]</nobr></li>
+<ul>
+<li><nobr>Case Sensitive</nobr></li>
+<ul>
+<li><nobr><a href="../reference/char-lessp-s.htm">char<</a> - test for less than in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/char-not-greaterp-s.htm">char<=</a> - test for less than or equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/char-equal-s.htm">char=</a> - test for equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/char-not-equal-s.htm">char/=</a> - test for not equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/char-not-lessp-s.htm">char>=</a> - test for greater than or equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/char-greaterp-s.htm">char></a> - test for greater than in ASCII ordering</nobr></li>
+</ul>
+<li><nobr>Case Insensitive</nobr></li>
+<ul>
+<li><nobr><a href="../reference/char-lessp-i.htm">char-lessp</a> - is this less than in ASCII ordering?</nobr></li>
+<li><nobr><a href="../reference/char-not-greaterp-i.htm">char-not-greaterp</a> - is this not greater than in ASCII ordering ?</nobr></li>
+<li><nobr><a href="../reference/char-equal-i.htm">char-equal</a> - is this equal in ASCII ordering?</nobr></li>
+<li><nobr><a href="../reference/char-not-equal-i.htm">char-not-equal</a> - is this not equal in ASCII ordering?</nobr></li>
+<li><nobr><a href="../reference/char-not-lessp-i.htm">char-not-lessp</a> - is this not less than in ASCII ordering ?</nobr></li>
+<li><nobr><a href="../reference/char-greaterp-i.htm">char-greaterp</a> - is this greater than in ASCII ordering?</nobr></li>
+</ul>
+<li><nobr>See also <a href="strings.htm#unicode">Unicode</a> examples.</nobr></li>
+</ul>
+</ul>
+<li><nobr><a href="../reference/arrayp.htm">arrayp</a> - is this an array?</nobr></li>
+<li><nobr><a href="../reference/streamp.htm">streamp</a> - is this a stream?</nobr></li>
+<li><nobr><a href="../reference/objectp.htm">objectp</a> - is this an object?</nobr></li>
+<li><nobr>filep - is this a file?</nobr></li>
+<li><nobr>soundp - is this a sound?</nobr></li>
+</ul>
+</ol>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="equalp"></a>
+
+<hr>
+
+<h2>equalp</h2>
+
+<hr>
+
+<p>Two expressions are 'equalp':</p>
+
+<ul>
+
+<li><p>If two numbers <nobr>are
+<a href="../reference/number-equal.htm"> = </a></nobr>
+numerical equal.</p></li>
+
+<li><p>If two characters are
+<nobr><a href="../reference/char-equal.htm">char-equal</a></nobr>.</p></li>
+
+<li><p>If two strings are <nobr><a
+href="../reference/string-equal.htm">string-equal</a></nobr>.</p></li>
+
+<li><p>If the two <a href="../reference/car.htm">car</a>s in conses are
+'equalp' and the two <a href="../reference/cdr.htm">cdr</a>s in conses
+are 'equalp'.</p></li>
+
+<li><p>If two arrays have the same number of elements and dimensions, and
+the corresponding elements in all dimensions are 'equalp'.</p></li>
+
+</ul>
+
+<pre class="example">
+(defun <font color="#0000CC">equalp</font> (expr-1 expr-2)
+ (or (equal expr-1 expr-2)
+ (and (numberp expr-1) (numberp expr-2) (= expr-1 expr-2))
+ (let ((type (type-of expr-1)))
+ (when (eq type (type-of expr-2))
+ (case type
+ (character (char-equal expr-1 expr-2))
+ (string (string-equal expr-1 expr-2))
+ (cons (do ((x (first expr-1)
+ (if (consp expr-1) (first expr-1) expr-1))
+ (y (first expr-2)
+ (if (consp expr-2) (first expr-2) expr-2)))
+ ((or (null expr-1)
+ (null expr-2)
+ (not (equalp x y)))
+ (and (null expr-1)
+ (null expr-2)))
+ (setq expr-1 (and (consp expr-1) (rest expr-1))
+ expr-2 (and (consp expr-2) (rest expr-2)))))
+ (array (let ((end (length expr-1)))
+ (when (eql end (length expr-2))
+ (dotimes (index end t)
+ (and (not (equalp (aref expr-1 index)
+ (aref expr-2 index)))
+ (return nil)))))))))))
+</pre>
+
+<p><b>cons:</b> I used <a href="../reference/do.htm">do</a> instead of
+recursion because XLISP has only two kilobytes stack size. <nobr>The
+(<a href="../reference/consp.htm">consp</a> <i>expr</i>)</nobr> tests are
+necessary because in a dotted list the last
+<a href="../reference/rest.htm">rest</a> element is not a cons.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(equalp 1 1.0) => T
+(equalp #\a #\A) => T
+(equalp "Abc" "aBc") => T
+(equalp '(1 #\a "Abc") '(1.0 #\A "aBc")) => T
+(equalp #(1 #\a "Abc") #(1.0 #\A "aBc")) => T
+</pre>
+
+<p>Nested expressions only match if the nesting matches:</p>
+
+<pre class="example">
+(equalp '(1 <font color="#AA0000">(</font>2 3<font color="#AA0000">)</font>) '(1.0 <font color="#AA0000">(</font>2.0 3.0<font color="#AA0000">)</font>) => T
+(equalp '(1 <font color="#AA0000">(</font>2 3<font color="#AA0000">)</font>) '(<font color="#AA0000">(</font>1.0 2.0<font color="#AA0000">)</font> 3.0) => NIL
+(equalp '(<font color="#AA0000">(</font>1 2<font color="#AA0000">)</font> 3) '(<font color="#AA0000">(</font>1.0 2.0<font color="#AA0000">)</font> 3.0) => T
+(equalp '(<font color="#AA0000">(</font>1 2<font color="#AA0000">)</font> 3) '(1.0 <font color="#AA0000">(</font>2.0 3.0<font color="#AA0000">)</font>) => NIL
+</pre>
+
+<p>A character does not match a string with the same character:</p>
+
+<pre class="example">
+(equalp #\a "a") => NIL
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="variablep"></a>
+
+<hr>
+
+<h2>variablep</h2>
+
+<hr>
+
+<p>The 'variablep' macro tests if a Lisp expression evaluates to a symbol
+with a valid variable value bound to it in the current global or lexical
+environment:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">variablep</font> (expr)
+ `(and (symbolp ,expr)
+ (valuep ,expr)))
+</pre>
+
+<p>Depends on <a href="environment.htm#valuep">valuep</a>, see
+<a href="../reference/and.htm">and</a>,
+<a href="../reference/defmacro.htm">defmacro</a>,
+<a href="../reference/symbolp.htm">symbolp</a>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="functionp"></a>
+
+<hr>
+
+<h2>functionp</h2>
+
+<hr>
+
+<p>The 'functionp' macro tests if a Lisp expression eveluates to a function
+or a symbol with a valid function value bound to it in the current global or
+lexical environment:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">functionp</font> (expr)
+ `(case (type-of ,expr)
+ (closure (eq 'lambda (car (get-lambda-expression ,expr))))
+ (subr t)
+ (symbol (and (or (lfboundp ,expr) (fboundp ,expr))
+ (functionp (function ,(if (consp expr) (cadr expr) expr)))))
+ (t nil)))
+</pre>
+
+<p>Depends on <a href="environment.htm#lfboundp">lfboundp</a>, see
+<a href="../reference/and.htm">and</a>,
+<a href="../reference/caar.htm">cadr</a>,
+<a href="../reference/car.htm">car</a>,
+<a href="../reference/case.htm">case</a>,
+<a href="../manual/xlisp.htm#data-types">closure</a>,
+<a href="../reference/defmacro.htm">defmacro</a>,
+<a href="../reference/eq.htm">eq</a>,
+<a href="../reference/fboundp.htm">fboundp</a>,
+<a href="../reference/function.htm">function</a>,
+<nobr><a href="../reference/get-lambda-expression.htm">get-lambda-expression</a></nobr>,
+<a href="../reference/lambda.htm">lambda</a>,
+<a href="../reference/nil.htm">nil</a>,
+<a href="../reference/or.htm">or</a>,
+<a href="../manual/xlisp.htm#data-types">subr</a>,
+<a href="../manual/xlisp.htm#data-types">symbol</a>,
+<nobr><a href="../reference/t.htm"> t </a></nobr>,
+<nobr><a href="../reference/type-of.htm">type-of</a></nobr>.</p>
+
+<p>The awkward <nobr>(function ,(if (consp expr) (cadr expr) expr))</nobr>
+construct is necessary because the
+<a href="../reference/function.htm">function</a> special form needs a
+<nobr>pre-evaluated</nobr> argument, what must be
+done at <nobr>macro-expansion</nobr> time, so an additional
+<nobr><a href="../reference/consp.htm">consp</a></nobr> test is
+needed if the 'expr' argument is a list at all, otherwise
+<a href="../reference/cadr.htm">cadr</a> will produce an error.</p>
+
+Examples:
+
+<pre class="example">
+(functionp #'car) => T <font color="#008844">; subr = built-in function</font>
+(functionp 'car) => T <font color="#008844">; symbol with a function value</font>
+
+(functionp #'and) => NIL <font color="#008844">; fsubr = built-in special form</font>
+(functionp "and") => NIL <font color="#008844">; string</font>
+
+(defun a () nil) => A <font color="#008844">; closure = user-defined function</font>
+(functionp #'a) => T <font color="#008844">; closure</font>
+(functionp 'a) => T <font color="#008844">; symbol with a function value</font>
+
+(setq b #'a) => A <font color="#008844">; function A stored in variable B</font>
+(fboundp 'b) => NIL <font color="#008844">; no function B found</font>
+(fboundp b) => T <font color="#008844">; variable B evaluates to function A</font>
+
+(functionp #'(lambda () nil)) => T <font color="#008844">; closure</font>
+(functionp '(lambda () nil)) => NIL <font color="#008844">; list</font>
+(functionp (lambda () nil)) => T <font color="#008844">; closure</font>
+
+(functionp #'functionp) => NIL <font color="#008844">; macro</font>
+
+(let ((x nil)) <font color="#008844">; lexical variable</font>
+ (functionp x))
+=> NIL
+
+(flet ((y () nil)) <font color="#008844">; lexical closure</font>
+ (functionp y))
+=> T
+
+(labels ((z () nil)) <font color="#008844">; lexical closure</font>
+ (functionp z))
+=> T
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="specialp"></a>
+
+<hr>
+
+<h2>specialp</h2>
+
+<hr>
+
+<pre class="example">
+(defmacro <font color="#0000CC">specialp</font> (expr)
+ `(case (type-of ,expr)
+ (fsubr t)
+ (symbol (and (or (lfboundp ,expr) (fboundp ,expr))
+ (functionp (function ,(if (consp expr) (cadr expr) expr)))))
+ (t nil)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="macrop"></a>
+
+<hr>
+
+<h2>macrop</h2>
+
+<hr>
+
+<pre class="example">
+(defmacro <font color="#0000CC">macrop</font> (expr)
+ `(case (type-of ,expr)
+ (closure (eq 'macro (car (get-lambda-expression ,expr))))
+ (symbol (and (or (lfboundp ,expr) (fboundp ,expr))
+ (macrop (function ,(if (consp expr) (cadr expr) expr)))))
+ (t nil)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="subrp"></a>
+
+<hr>
+
+<h2>subrp</h2>
+
+<hr>
+
+<p>The 'subrp' function returns T if the symbol is a build-in function.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">subrp</font> (symbol)
+ (eq 'subr (type-of symbol)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="fsubrp"></a>
+
+<hr>
+
+<h2>fsubrp</h2>
+
+<hr>
+
+<p>The 'fsubrp' function returns T if the symbol is a build-in special
+function.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">fsubrp</font> (symbol)
+ (eq 'fsubr (type-of symbol)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="closurep"></a>
+
+<hr>
+
+<h2>closurep</h2>
+
+<hr>
+
+<p>The 'closurep' function returns T if the symbol is a user-defined
+function.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">closurep</font> (symbol)
+ (eq 'closure (type-of symbol)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
+
diff --git a/docsrc/xlisp/xlisp-doc/examples/reader.htm b/docsrc/xlisp/xlisp-doc/examples/reader.htm new file mode 100644 index 0000000..8321c48 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/reader.htm @@ -0,0 +1,311 @@ +<html><head>
+
+<title>XLISP reader</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Reader</h1>
+
+<hr>
+
+
+
+<hr>
+
+<h2>read-from-string</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">read-from-string</font> (string)
+ (read (make-string-input-stream string)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="global-readtable"></a>
+
+<hr>
+
+<h2>*readtable*</h2>
+
+<hr>
+
+<p>The <a href="../reference/global-readtable.htm">*readtable*</a> system
+variable contains the reader table array. <nobr>The table</nobr> is
+<nobr>128 entries</nobr> <nobr>[0..127]</nobr> for each of the
+<nobr>7-bit</nobr> ASCII characters that XLISP
+<nobr>can <a href="../reference/read.htm">read</a></nobr>.</p>
+
+<ul>
+<li><nobr><a href="../reference/read.htm">read</a> - function to read a lisp expression</nobr></li>
+<li><nobr><a href="../reference/global-readtable.htm">*readtable*</a> - system variable, holding the readtable</nobr></li>
+<ul>
+<li><nobr><a href="../reference/nil.htm">NIL</a> - invalid character</nobr></li>
+<li><nobr><a href="../reference/keyword-constituent.htm">:constituent</a> - symbol constituent</nobr></li>
+<li><nobr><a href="../reference/keyword-sescape.htm">:sescape</a> - whitespace character</nobr></li>
+<li><nobr><a href="../reference/keyword-mescape.htm">:mescape</a> - multiple escape character</nobr></li>
+<li><nobr><a href="../reference/keyword-white-space.htm">:white-space</a> - single escape character</nobr></li>
+<li><nobr><a href="../reference/keyword-tmacro.htm">:tmacro</a> - terminating readmacro</nobr></li>
+<li><nobr><a href="../reference/keyword-nmacro.htm">:nmacro</a> - non-terminating readmacro</nobr></li>
+</ul>
+</ul>
+
+<p>See also the
+<nobr><a href="../manual/xlisp.htm#lexical-conventions">Lexical Conventions</a></nobr>
+and <a href="../manual/xlisp.htm#the-readtable">Readtable</a> sections in the
+<nobr>XLISP 2.0</nobr> manual.</p>
+
+<a name="print-readtable"></a>
+
+<hr>
+
+<h2>print-readtable</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">print-readtable</font> ()
+ (dotimes (index 128)
+ (format t <font color="#880000">"ASCII-~a ~a = ~a~%"</font>
+ (cond ((<= 0 index 9) (format nil "00~a" index))
+ ((<= 10 index 99) (format nil "0~a" index))
+ (t index))
+ (if (< 31 index 127)
+ (code-char index)
+ (case index
+ (0 "[null] ")
+ (1 "[start of heading] ")
+ (2 "[start of text] ")
+ (3 "[end of text] ")
+ (4 "[end of transmission] ")
+ (5 "[enquiry] ")
+ (6 "[acknowledge] ")
+ (7 "[terminal bell] ")
+ (8 "[backspace] ")
+ (9 "[horizontal tab] ")
+ (10 "[line feed] ")
+ (11 "[vertical tab] ")
+ (12 "[form feed] ")
+ (13 "[carriage return] ")
+ (14 "[shift out] ")
+ (15 "[shift in] ")
+ (16 "[data link escape] ")
+ (17 "[device control 1, xon] ")
+ (18 "[device control 2] ")
+ (19 "[device control 3, xoff]")
+ (20 "[device control 4] ")
+ (21 "[negative acknowledge] ")
+ (22 "[synchronous idle] ")
+ (23 "[end transmission block]")
+ (24 "[cancel line] ")
+ (25 "[end of medium] ")
+ (26 "[substitute] ")
+ (27 "[escape] ")
+ (28 "[file separator] ")
+ (29 "[group separator] ")
+ (30 "[record separator] ")
+ (31 "[unit separator] ")
+ (127 "[delete]")))
+ (aref <font color="#AA5500">*readtable*</font> index))))
+</pre>
+
+<hr>
+
+<h2>get-macro-character</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>get-macro-character</b> <i>char</i>)</dt>
+<dd><i>char</i> - a character<br>
+returns - the code associated with the
+<a href="../reference/global-readtable.htm">*readtable*</a> entry or
+<a href="../reference/nil.htm">NIL</a></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">get-macro-character</font> (char)
+ (if (consp (aref <font color="#AA5500">*readtable*</font> (char-code char)))
+ (cdr (aref <font color="#AA5500">*readtable*</font> (char-int char)))
+ nil))
+</pre>
+
+<p> The '<nobr>get-macro-character</nobr>' function returns the code that
+will be executed when the specified character 'char' is encountered by the
+XLISP reader.</p>
+
+<p>The 'get-macro-character' function will return a
+<a href="../reference/nil.htm">NIL</a> value if the table entry is
+<nobr><a href="../reference/nil.htm">NIL</a> ,</nobr>
+<nobr><a href="../reference/keyword-constituent.htm">:constituent</a> ,</nobr>
+<nobr><a href="../reference/keyword-sescape.htm">:sescape</a> ,</nobr>
+<a href="../reference/keyword-mescape.htm">:mescape</a> or
+<a href="../reference/keyword-white-space.htm">:white-space</a>. If the table entry is
+<a href="../reference/keyword-tmacro.htm">:tmacro</a> or
+<nobr><a href="../reference/keyword-nmacro.htm">:nmacro</a> ,</nobr> then the code
+associated with the entry is returned.
+<a href="../reference/keyword-tmacro.htm">:tmacro</a> is used for a terminating
+read-macro. <a href="../reference/keyword-nmacro.htm">:nmacro</a> is used for a
+non-terminating read-macro. 'get-macro-character' does not differentiate
+whether the code returned is a
+<a href="../reference/keyword-tmacro.htm">:tmacro</a> or an
+<a href="../reference/keyword-nmacro.htm">:nmacro</a>.</p>
+
+<p>The function returned may be a built-in read-macro function or a user
+defined <a href="../reference/lambda.htm">lambda</a> expression. The function
+takes two parameters, an input stream specification, and an integer that is
+the character value. The function should return
+<a href="../reference/nil.htm">NIL</a> if the character is 'white-space' or a
+value <a href="../reference/cons.htm">cons</a>ed with
+<a href="../reference/nil.htm">NIL</a> to return the value.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(get-macro-character #\() => #<Subr-(null): #...></font>
+(get-macro-character #\#) => #<Subr-(null): #...></font>
+(get-macro-character #\Space) => NIL</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<a name="set-macro-character"></a>
+
+<hr>
+
+<h2>set-macro-character</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>set-macro-character</b> <i>char function</i> [<i>termination-flag</i>])</dt>
+<dd><i>char</i> - a character expression<br>
+<i>function</i> - a function definition<br>
+<i>termination-flag</i> - an expression, <a href="../reference/nil.htm">NIL</a> or
+non-<a href="../reference/nil.htm">NIL</a><br>
+returns - always returns <a href="../reference/t.htm"> T </a></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">set-macro-character</font> (char function &optional terminate-p)
+ (setf (aref <font color="#AA5500">*readtable*</font> (char-code char))
+ (cons (if terminate-p :tmacro :nmacro) function))
+ t)
+</pre>
+
+<p>The '<nobr>set-macro-character</nobr>' function installs the code that
+will be executed when the specified character 'char' is encountered by the
+XLISP reader.</p>
+
+<p>The 'set-macro-character' function only allows you to put in a
+terminating read-macro function <a href="../reference/keyword-tmacro.htm">:tmacro</a> or
+a non-terminating read-macro-function
+<a href="../reference/keyword-nmacro.htm">:nmacro</a>. If the 'termflag' is present and
+non-<nobr><a href="../reference/nil.htm">NIL</a> ,</nobr> then the 'function'
+will be put in <a href="../reference/global-readtable.htm">*readtable*</a> as a
+<a href="../reference/keyword-tmacro.htm">:tmacro</a> entry. If 'termflag' is not present
+or <nobr><a href="../reference/nil.htm">NIL</a> ,</nobr> then 'function' will
+be put in <a href="../reference/global-readtable.htm">*readtable*</a> as a
+<a href="../reference/keyword-nmacro.htm">:nmacro</a> entry. The 'function' can be a
+built-in read-macro function or a user defined
+<a href="../reference/defun.htm">defun</a> symbol or a
+<a href="../reference/lambda.htm">lambda</a> expression.</p>
+
+<p>The 'function' takes two parameters, an input stream specification, and
+an integer that is the character value. The 'function' should return
+<a href="../reference/nil.htm">NIL</a> if the character is 'white-space' or a
+value <a href="../reference/cons.htm">cons</a>ed with
+<a href="../reference/nil.htm">NIL</a> to return the value. The function
+'set-macro-character' always returns
+<a href="../reference/t.htm"> T </a>.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+> (print "hi") % comment
+"hi"
+"hi"
+<font color="#AA0000">error: unbound variable - %</font> <font color="#008844">; % is interpreted as a variable</font>
+
+> (setq readtable-backup *readtable*)
+#( ... very-long-value ... )
+
+> (set-macro-character #\% (get-macro-character #\;) t)
+T
+
+> (print "hi") % comment
+"hi" <font color="#008844">; no error because</font>
+"hi" <font color="#008844">; % is now a comment character</font>
+
+> (setq *readtable* readtable-backup)
+#( ... very-long-value ... )
+</pre>
+
+<p><b>Important:</b> before manipulating the XLISP
+<a href="../reference/global-readtable.htm">*readtable*</a> it's always a
+good idea to store the original contents in some other variable.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/sequences.htm b/docsrc/xlisp/xlisp-doc/examples/sequences.htm new file mode 100644 index 0000000..fb69a4b --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/sequences.htm @@ -0,0 +1,563 @@ +<html><head>
+
+<title>Sequences</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Sequences</h1>
+
+<hr>
+
+<p>Sequences are <a href="lists.htm">Lists</a>,
+<a href="strings.htm">Strings</a>,
+<nobr>or <a href="arrays.htm">Arrays</a></nobr>.</p>
+
+<ul>
+<li><nobr><a href="#sequencep">sequencep</a> - test if a Lisp object is a sequence</nobr></li>
+<li><nobr><a href="#length">length</a> - the length of a sequence</nobr></li>
+<li><nobr><a href="#identity">identity</a> - do nothing, just return the value</nobr></li>
+<li><nobr><a href="#cl-subseq">cl:subseq</a> - subsequences of lists, strings, or arrays</nobr></li>
+<li><nobr>Properties of elements in sequences:</nobr></li>
+<ul>
+<li><nobr>find</nobr></li>
+<li><nobr>count</nobr></li>
+<li><nobr>position</nobr></li>
+</ul>
+<li><nobr>Predicates for testing sequences:</nobr></li>
+<ul>
+<li><nobr>every</nobr></li>
+<li><nobr>some</nobr></li>
+<li><nobr>notevery</nobr></li>
+<li><nobr>notany </nobr></li>
+</ul>
+<li><nobr>Functions to modify sequences:</nobr></li>
+<ul>
+<li><nobr>map</nobr></li>
+<li><nobr>flatten</nobr></li>
+</ul>
+</ul>
+
+<a name="sequencep"></a>
+
+<hr>
+
+<h2>sequencep</h2>
+
+<hr>
+
+<p>The following example demonstrates how a XLISP expression can be tested
+for being a sequence:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">sequencep</font> (x)
+ (and (lboundp 'x) <font color="#008844">; not *unbound*</font>
+ (or (and (listp x) <font color="#008844">; a list or NIL</font>
+ (consp (last x))) <font color="#008844">; but not a dotted list</font>
+ (stringp x) <font color="#008844">; or a string</font>
+ (arrayp x)))) <font color="#008844">; or an array</font>
+</pre>
+
+<p>Depends on <a href="environment.htm#lboundp">lboundp</a>,
+see also <a href="../reference/and.htm">and</a>,
+<a href="../reference/arrayp.htm">arrayp</a>,
+<a href="../reference/consp.htm">consp</a>,
+<a href="../reference/defun.htm">defun</a>,
+<a href="../reference/last.htm">last</a>,
+<a href="../reference/listp.htm">listp</a>,
+<a href="../reference/or.htm">or</a>,
+<a href="../reference/stringp.htm">stringp</a>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="length"></a>
+
+<hr>
+
+<h2>length</h2>
+
+<hr>
+
+<p>XLISP already knows sequences, even if the manual doesn't explicitely
+<nobr>tell you:</nobr></p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<a href="../reference/length.htm">length</a> <i>expr</i>)</dt>
+<dd><i>expr</i> - expression, evaluating to a list, string, or array<br>
+returns - the length of the list, string, or array</dd>
+</dl>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="identity"></a>
+
+<hr>
+
+<h2>identity</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">identity</font> (x)
+ x)
+</pre>
+
+<p>The 'identity' function is handy if a mapping function needs a '<nobr>do
+nothing</nobr>, just return the value' function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-subseq"></a>
+
+<hr>
+
+<h2>cl:subseq</h2>
+
+<hr>
+
+<p>XLISP already has a <a href="../reference/subseq.htm">subseq</a> function
+returning a subsequence of a string:</p>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<a href="../reference/subseq.htm">subseq</a> <i>string start</i> [<i>end</i>])</nobr></dt>
+<dd><i>string</i> - a string expression<br>
+<i>start</i> - the position of the first element, an integer<br>
+<i>end</i> - the position following last element, defaults to the end of the sequence<br>
+returns - the substring between <i>start</i> and <i>end</i></dd>
+</dl>
+
+</div></p>
+
+<p>The 'cl:subseq' function works like
+<a href="../reference/subseq.htm">subseq</a>, but returns subsequences of
+lists, strings, and arrays:</p>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(cl:<b>subseq</b> <i>sequence start</i> [<i>end</i>])</nobr></dt>
+<dd><i>sequence</i> - a list, string, or array<br>
+<i>start</i> - the position of the first element, an integer<br>
+<i>end</i> - the position following last element, defaults to the end of the sequence<br>
+returns - the subsequence in the same type as <i>sequence</i></dd>
+</dl>
+
+</div></p>
+
+<p>The 'cl:subseq' function creates a sequence that is a copy of the
+subsequence of 'sequence' bounded by 'start' and 'end'. 'cl:subseq' always
+allocates a new sequence for a result, it never shares storage with an old
+sequence. <nobr>The resulting</nobr> subsequence is always of the same type
+as the input sequence.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:subseq</font> (sequence start &optional (end nil end-p))
+ (let ((type (type-of sequence)))
+ (if (not (member type '(nil cons string array)))
+ (error <font color="#880000">"not a sequence"</font> sequence)
+ (let* ((length (length sequence))
+ (end (or end length)))
+ (cond ((or (> start length) (minusp start))
+ (error <font color="#880000">"start index out of bounds"</font> start))
+ ((and end-p (or (> end length) (minusp end)))
+ (error <font color="#880000">"end index out of bounds"</font> end))
+ ((> start end)
+ (error (format nil <font color="#880000">"bad range start ~a end ~a"</font> start end)))
+ (t (case type
+ (nil nil)
+ (cons (if (not (consp (last sequence)))
+ <font color="#008844">;; a dotted list is not a sequence</font>
+ (error <font color="#880000">"not a proper sequence"</font> sequence)
+ (if (>= start end)
+ nil
+ (nthcdr start
+ (if end-p
+ (reverse
+ (nthcdr (- length end)
+ (reverse sequence)))
+ sequence)))))
+ (string (subseq sequence start end))
+ (array (if (>= start end)
+ (make-array 0)
+ (let ((new-array (make-array (- end start))))
+ (do ((n-index 0 (1+ n-index))
+ (s-index start (1+ s-index)))
+ ((>= s-index end))
+ (setf (aref new-array n-index)
+ (aref sequence s-index)))
+ new-array))))))))))
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:subseq "012345" 2) => "2345"
+(cl:subseq "012345" 3 5) => "34"
+
+(cl:subseq '(0 1 2 3 4 5) 2) => (2 3 4 5)
+(cl:subseq '(0 1 2 3 4 5) 3 5) => (3 4)
+
+(cl:subseq #(0 1 2 3 4 5) 2) => #(2 3 4 5)
+(cl:subseq #(0 1 2 3 4 5) 3 5) => #(3 4)
+</pre>
+
+<p>In XLISP, neither <a href="../reference/subseq.htm">subseq</a> nor
+'cl:subseq' can be used as arguments to
+<a href="../reference/setf.htm">setf</a>.
+<nobr>See <a href="#cl-replace">cl:replace</a></nobr> below how to replace
+subsequences.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-replace"></a>
+
+<hr>
+
+<h2>cl:replace</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(cl:<b>replace</b> <i>sequence1 sequence2</i> &key <i>start1 end1 start2 end2</i>)</nobr></dt>
+<dd><i>sequenceN</i> - a list, string, or array<br>
+<i>startN</i> - the position of the first element in <i>sequenceN</i>, an integer<br>
+<i>endN</i> - the position following last element in <i>sequenceN</i>, defaults to the end of <i>sequenceN</i><br>
+returns - the subsequence in the same type as <i>sequence</i></dd>
+</dl>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<h2>map</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+
+<dt><nobr><b>map</b> <i>result-type function</i> <i>sequence-1</i> [<i>sequence-2</i> ...]</nobr></dt>
+<dd><i>result-type</i> - list, string, or array<br>
+<i>function</i> - a function, applied to each element of each sequenceN<br>
+<i>sequenceN</i> - a list, string, or array<br>
+returns - a sequence where each element is the result of applying the function to each element of each sequenceN</dd>
+</dl>
+
+<dl>
+
+</div></p>
+
+<p>The 'sequence:string' function can handle lists and arrays containing not
+only characters but also strings, because XLISP Unicode characters are
+represented as strings.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">sequence:string</font> (sequence)
+ (if (stringp sequence)
+ sequence
+ (let ((result <font color="#880000">""</font>))
+ (flet ((strcat-element (element)
+ (let ((string (cond ((stringp element) element)
+ ((characterp element) (string element))
+ (t (error <font color="#880000">"not a character or string"</font>
+ element)))))
+ (setq result (strcat result string)))))
+ (case (type-of sequence)
+ (array (let ((end (length sequence)))
+ (dotimes (index end)
+ (if (eq (aref sequence index) '*unbound*)
+ (error <font color="#880000">"not a character or string"</font> '*unbound*)
+ (strcat-element (aref sequence index))))))
+ (cons (let ((end (length sequence)))
+ (if (not (consp (last sequence)))
+ (error <font color="#880000">"not a proper sequence"</font> sequence)
+ (dotimes (index end)
+ (if (eq (nth index sequence) '*unbound*)
+ (error <font color="#880000">"not a character or string"</font> '*unbound*)
+ (strcat-element (nth index sequence)))))))
+ (nil nil)
+ (t (error <font color="#880000">"not a sequence"</font> sequence)))
+ result))))
+
+(defun <font color="#0000CC">list-to-string</font> (list)
+ (let ((string ""))
+ (dolist (element list string)
+ (setq string (strcat string (if (consp element)
+ (list-to-string element)
+ (format nil "~a" element)))))))
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">sequence:vector</font> (sequence)
+ (if (not (boundp 'sequence))
+ (error <font color="#880000">"not a sequence"</font> '*unbound*)
+ (let ((type (type-of sequence)))
+ (if (not (member type '(array cons nil string)))
+ (error <font color="#880000">"not a sequence"</font> sequence)
+ (let* ((end (length sequence))
+ (result (make-array end)))
+ (unless (zerop end)
+ (case type
+ (array (dotimes (index end)
+ (setf (aref result index)
+ (if (eq (aref sequence index) '*unbound*)
+ '*unbound*
+ (aref sequence index)))))
+ (cons (if (not (consp (last sequence)))
+ (error <font color="#880000">"not a proper sequence"</font> sequence)
+ (dotimes (index end)
+ (setf (aref result index)
+ (if (eq (nth index sequence) '*unbound*)
+ '*unbound*
+ (nth index sequence))))))
+ (string (dotimes (index end)
+ (setf (aref result index)
+ (char sequence index))))))
+ result)))))
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">sequence:array</font> (sequence)
+ (let ((type (type-of sequence)))
+ (if (not (member type '(array cons nil string)))
+ (error <font color="#880000">"not a sequence"</font> sequence)
+ (let* ((end (length sequence))
+ (result (make-array end)))
+ (if (zerop end)
+ result
+ (labels ((array-element (element index)
+ (setf (aref result index)
+ (if (or (consp element) (arrayp element))
+ (sequence:array element)
+ element))))
+ (case type
+ (array (dotimes (index end)
+ (if (eq (aref sequence index) '*unbound*)
+ (setf (aref result index) '*unbound*)
+ (array-element (aref sequence index) index))))
+ (cons (if (not (consp (last sequence)))
+ (error <font color="#880000">"not a proper sequence"</font> sequence)
+ (dotimes (index end)
+ (if (eq (nth index sequence) '*unbound*)
+ (setf (aref result index) '*unbound*)
+ (array-element (nth index sequence) index)))))
+ (string (dotimes (index end)
+ (setf (aref result index)
+ (char sequence index)))))
+ result))))))
+
+
+(defun <font color="#0000CC">list-to-array</font> (list)
+ (let* ((end (length list))
+ (array (make-array end)))
+ (dotimes (index end array)
+ (let ((element (nth index list)))
+ (setf (aref array index) (if (consp element)
+ (list-to-array element)
+ element))))))
+
+(defun <font color="#0000CC">list-from-input</font> (input)
+ (let (result)
+ (dolist (element input) <font color="#008844">; input is always a list</font>
+ (format t ";; ~s ~s~%" element (type-of element))
+ (case (type-of element)
+ (nil (push element result))
+ (cons (if (consp (last element))
+ (push element result)
+ (error <font color="#880000">"not a proper list"</font> element)))
+ (array (let (local (end (length element)))
+ (dotimes (index end)
+ (push (aref element index) local))
+ (push (reverse local) result)))
+ (string (let (local (end (length element)))
+ (dotimes (index end)
+ (push (char element index) local))
+ (push (reverse local) result)))
+ (t (error <font color="#880000">"not a sequence"</font> element))))
+ (reverse result)))
+
+(defun <font color="#0000CC">list-from-input*</font> (input &optional recursion-p)
+ (let (result)
+ (labels ((test (element)
+ (if (member (type-of element) '(array cons string))
+ (list-from-input* element t)
+ (if (or recursion-p (null element))
+ element
+ (error <font color="#880000">"not a sequence"</font> element)))))
+ (format t ";; ~s~%" input)
+ (case (type-of input)
+ (nil (push input result))
+ (cons (if (consp (last input))
+ (dolist (element input)
+ (push (test element) result))
+ (error <font color="#880000">"not a proper list"</font> input)))
+ (array (let ((end (length input)))
+ (dotimes (index end)
+ (push (test (aref input index)) result))))
+ (string (let ((end (length input)))
+ (dotimes (index end)
+ (push (test (char input index)) result))))
+ (t (error <font color="#880000">"not a sequence"</font> input)))
+ (reverse result))))
+
+(defun <font color="#0000CC">map</font> (result-type function &rest sequences)
+ (if (not (member result-type '(list string array)))
+ (error <font color="#880000">"invalid result type"</font> result-type)
+ (let* ((input-list (list-from-input sequences))
+ (result (if function
+ (apply #'mapcar (cons function input-list))
+ (if (rest sequences)
+ input-list
+ (first input-list)))))
+ (case result-type
+ (list result)
+ (string (list-to-string result))
+ (array (list-to-array result))))))
+
+(defun <font color="#0000CC">mapcar*</font> (function &rest lists)
+ (unless (or (null lists)
+ (dolist (list lists nil)
+ (and (null list) (return t))))
+ (let ((end (length lists))
+ (result nil))
+ (do ((stop nil) (recurse t t)) (stop)
+ (let (local)
+ (dotimes (index end)
+ (let ((first (first (nth index lists)))
+ (rest (rest (nth index lists))))
+ (push first local)
+ (unless (consp first) (setq recurse nil))
+ (setf (nth index lists) rest)
+ (when (null rest) (setq stop t))))
+ (setq local (reverse local))
+ (format t ";; local: ~a~%" local)
+ (format t ";; lists: ~a~%" lists)
+ (format t ";; recurse: ~a~%" recurse)
+ (if recurse
+ (push (apply #'mapcar* (cons function local)) result)
+ (push (apply function local) result))))
+ (reverse result))))
+
+(defun <font color="#0000CC">map*</font> (result-type function &rest sequences)
+ (if (not (member result-type '(list string array)))
+ (error <font color="#880000">"invalid result type"</font> result-type)
+ (let* ((input-list (list-from-input* sequences))
+ (result (if function
+ (apply #'mapcar* (cons function input-list))
+ (if (rest sequences)
+ input-list
+ (first input-list)))))
+ (format t ";; ~s~%" input-list)
+ (case result-type
+ (list result)
+ (string (list-to-string result))
+ (array (list-to-array result))))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<dt><nobr><b>find</b> <i>item sequence</i> &key <i>from-end test test-not start end key</i> ⇒ <i>element</i></nobr></dt>
+<dt><nobr><b>find-if</b> predicate sequence &key from-end start end key ⇒ element</nobr></dt>
+<dt><nobr><b>find-if-not</b> predicate sequence &key from-end start end key ⇒ element</nobr></dt>
+
+<dd><p>Search for an element of the sequence bounded by start and end that
+satisfies the predicate or that satisfies the test or test-not, as
+appropriate.</p></dd>
+
+<dt><nobr><b>count</b> item sequence &key from-end start end key test test-not ⇒ n</nobr></dt>
+<dt><nobr><b>count-if</b> predicate sequence &key from-end start end key ⇒ n</nobr></dt>
+<dt><nobr><b>count-if-not</b> predicate sequence &key from-end start end key ⇒ n</nobr></dt>
+
+<dd><p>Count and return the number of elements in the sequence bounded by
+start and end that satisfy the test. </p></dd>
+
+<dt><b>position</b> item sequence &key from-end test test-not start end key ⇒ position</dt>
+<dt><b>position-if</b> predicate sequence &key from-end start end key ⇒ position</dt>
+<dt><b>position-if-not</b> predicate sequence &key from-end start end key ⇒ position</dt>
+
+<dd><p>Search sequence for an element that satisfies the test. The position
+returned is the index within sequence of the leftmost (if from-end is true)
+or of the rightmost (if from-end is false) element that satisfies the test;
+otherwise nil is returned. The index returned is relative to the left-hand
+end of the entire sequence, regardless of the value of start, end, or
+from-end.</p></dd>
+
+</dl>
+
+<pre class="example">
+(defun <font color="#0000CC">list-find</font> (element list &key from-end test test-not start end)
+ (when from-end (setq list (reverse-list)))
+ (first (cond (test (member element list :test test))
+ (test-not (member element list :test-not test-not))
+ (t (member element list)))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/strings.htm b/docsrc/xlisp/xlisp-doc/examples/strings.htm new file mode 100644 index 0000000..1842c08 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/strings.htm @@ -0,0 +1,802 @@ +<html><head>
+
+<title>Characters and Strings</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Characters and Strings</h1>
+
+<hr>
+
+<p>Strings are also <a href="sequences.htm">Sequences</a>.</p>
+
+<ul>
+<li><nobr><a href="#make-string">make-string</a> - make a string of a specific number of characters</nobr></li>
+<li><nobr><a href="#string-star">string*</a> - make a string out of arbitrary Lisp expressions</nobr></li>
+<li><nobr><a href="#posix">POSIX Character Classes</a> - character predicates</nobr></li>
+<li><nobr><a href="#unicode">Unicode Strings</a></nobr></li>
+<ul>
+<li><nobr><a href="#utf-8-byte-p">utf-8-byte-p</a> - tests if a XLISP character is a valid UTF-8 byte</nobr></li>
+<li><nobr><a href="#utf-8-bytes">utf-8-bytes</a> - returns the number of bytes of an UTF-8 character</nobr></li>
+<li><nobr><a href="#utf-8-bytes">utf-8-string-to-list</a> - converts an UTF-8 string to a list of 'string-characters'</nobr></li>
+<li><nobr><a href="#utf-8-bytes">utf-8-list-to-string</a> - converts a list of 'string-characters' to an XLISP string</nobr></li>
+</ul>
+</ul>
+
+<a name=""></a>
+
+<hr>
+
+<h2>make-string</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">make-string</font> (length initial-element)
+ (cond ((not (and (integerp length)
+ (plusp length)))
+ (error <font color="#AA0000">"not a positive integer"</font> length))
+ ((not (characterp initial-element))
+ (error <font color="#AA0000">"not a character"</font> initial-element))
+ (t
+ (let ((element (string initial-element))
+ (string <font color="#AA0000">""</font>))
+ (dotimes (x length)
+ (setq string (strcat string element)))
+ string))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="string-star"></a>
+
+<hr>
+
+<h2>string*</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+
+<dt><nobr>(<b>string*</b> [<i>expr1</i> ...])</nobr></dt>
+<dd><i>exprN</i> - arbitrary Lisp expressions<br>
+returns - the expression[s], converted and concatenated into a single string</dd>
+</dl>
+
+<dl>
+
+</div></p>
+
+<p>The 'string*' function tries to make a string out of everything:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">string*</font> (&rest items)
+ (if (null items)
+ <font color="#880000">""</font>
+ (let ((end (length items))
+ (result <font color="#880000">""</font>))
+ (labels ((strcat-element (element)
+ (let ((string (if (or (consp element) (arrayp element))
+ (string* element)
+ (format nil <font color="#880000">"~a"</font> element))))
+ (setq result (strcat result string)))))
+ (dotimes (index end)
+ (if (eq (nth index items) '*unbound*)
+ (strcat-element <font color="#880000">"*UNBOUND*"</font>)
+ (let ((item (nth index items)))
+ (case (type-of item)
+ (cons (let ((end (length item)))
+ (when (not (consp (last item))) (incf end))
+ (dotimes (index end)
+ (if (eq (nth index item) '*unbound*)
+ (strcat-element <font color="#880000">"*UNBOUND*"</font>)
+ (strcat-element (nth index item))))))
+ (array (let ((end (length item)))
+ (dotimes (index end)
+ (if (eq (aref item index) '*unbound*)
+ (strcat-element <font color="#880000">"*UNBOUND*"</font>)
+ (strcat-element (aref item index))))))
+ (t (strcat-element item))))))
+ result))))
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+(string*) => ""
+
+(string* #\A "B" 'c) => "ABC"
+(string* 1 2 3) => "123"
+
+(string* 1 "st") => "1st"
+(string* "2" #\n #\d) => "2nd"
+
+(setq a 3) => 3
+(string* 'a "=" a) => "A=3"
+</pre>
+
+<p>Nested expressions will be flattened:</p>
+
+<pre class="example">
+(string* #(1 (#\2) "3")) => "123"
+</pre>
+
+<p>The result may contain nonsense:</p>
+
+<pre class="example">
+(string* #'car) => "#<Subr-CAR: #8645768>"
+(string* '(lambda (x) (print x))) => "LAMBDAXPRINTX"
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="posix"></a>
+
+<hr>
+
+<h2>POSIX Character Classes</h2>
+
+<hr>
+
+<p>The <nobr>built-in</nobr> XLISP character test functions
+<a href="../reference/upper-case-p.htm">upper-case-p</a>,
+<a href="../reference/lower-case-p.htm">lower-case-p</a>,
+<a href="../reference/both-case-p.htm">both-case-p</a>, return the boolean
+values <a href="../reference/t.htm"> T </a> or
+<a href="../reference/nil.htm">NIL</a> instead of the tested character,
+while <a href="../reference/digit-char-p.htm">digit-char-p</a> returns an
+integer <nobr>or <a href="../reference/nil.htm">NIL</a></nobr>, what is
+handy if you want to convert arbitrary Lisp symbols into numbers without
+producing an error, but all this is impractical for writing a string
+parser.</p>
+
+<p>The following functions implement tests for the standard POSIX character
+classes, where all functions return the tested character if the test
+succeeds, or <a href="../reference/nil.htm">NIL</a></nobr> if the test
+fails. <nobr>The 'internal'</nobr> functions do not check if the argument is
+a character and therefore are faster than the 'user' functions. Also note
+that XLISP is limited to ASCII characters, so there is no way to find out if
+an unicode character is upper- or lowercase if the character code is greater
+than <nobr>ASCII 127</nobr>.</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td colspan="3"><nobr><b>POSIX</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><b>Internal</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><b>User Function</b></nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>alnum</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-alnum-p">char:alnum-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#alnum-character-p">alnum-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>alphanumeric = [a-z], [A-Z], [0-9]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>alpha</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-alpha-p">char:alpha-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#alpha-character-p">alpha-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>alphabetic = [a-z], [A-Z]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>blank</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-blank-p">char:blank-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#blank-character-p">blank-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>space and horizontal-tab</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>cntrl</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-cntrl-p">char:cntrl-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#cntrl-character-p">cntrl-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>code-chars 0-31 and 127</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>digit</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-digit-p">char:digit-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#digit-character-p">digit-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>decimal = [0-9]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>graph</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-graph-p">char:graph-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#graph-character-p">graph-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>graphical = alnum + punct</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>lower</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-lower-p">char:lower-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#lower-character-p">lower-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>lowercase = [a-z]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>print</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-print-p">char:print-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#print-character-p">print-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>printable = alnum + punct + space</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>punct</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-punct-p">char:punct-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#punct-character-p">punct-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>punctuation marks</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>space</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-space-p">char:space-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#space-character-p">space-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>characters producing whitespace</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>upper</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-upper-p">char:upper-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#upper-character-p">upper-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>uppercase = [A-Z]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>xdigit</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-xdigit-p">char:xdigit-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#xdigit-character-p">xdigit-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>hexadecimal = [0-9], [a-f], [A-F]</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p><b>Internal Functions</b> for POSIX character classes:</p>
+
+<a name="char-alnum-p"></a>
+
+<pre class="example">
+<font color="#008844">;; alphanumeric characters = a-z, A-z, 0-9</font>
+
+(defun <font color="#0000CC">char:alnum-p</font> (char)
+ (and (alphanumericp char)
+ char))
+<a name="char-alpha-p"></a>
+<font color="#008844">;; alphabetic characters = a-z, A-Z</font>
+
+(defun <font color="#0000CC">char:alpha-p</font> (char)
+ (and (both-char-p char)
+ char))
+<a name="char-blank-p"></a>
+<font color="#008844">;; blanks = space and horizontal-tab</font>
+
+(defun <font color="#0000CC">char:blank-p</font> (char)
+ (and (or (char= char #\Space)
+ (char= char #\Tab))
+ char))
+<a name="char-cntrl-p"></a>
+<font color="#008844">;; control characters = code-chars 0-31 and 127</font>
+
+(defun <font color="#0000CC">char:cntrl-p</font> (char)
+ (let ((code (char-code char)))
+ (and (or (<= 0 code 31)
+ (= code 127))
+ char)))
+<a name="char-digit-p"></a>
+<font color="#008844">;; decimal digits = 0-9</font>
+
+(defun <font color="#0000CC">char:digit-p</font> (char)
+ (and (digit-char-p char)
+ char))
+<a name="char-graph-p"></a>
+<font color="#008844">;; graphical characters = alnum + punct</font>
+
+(defun <font color="#0000CC">char:graph-p</font> (char)
+ (and (<= 33 (char-code char) 126)
+ char))
+<a name="char-lower-p"></a>
+<font color="#008844">;; lowercase characters = a-z</font>
+
+(defun <font color="#0000CC">char:lower-p</font> (char)
+ (and (lower-case-p char)
+ char))
+<a name="char-print-p"></a>
+<font color="#008844">;; printable characters = alnum + punct + space</font>
+
+(defun <font color="#0000CC">char:print-p</font> (char)
+ (and (<= 32 (char-code char) 126)
+ char))
+<a name="char-punct-p"></a>
+<font color="#008844">;; punctuation marks</font>
+
+(defun <font color="#0000CC">char:punct-p</font> (char)
+ (let ((code (char-code char)))
+ (and (or (<= 33 code 47) <font color="#008844">; ! " # $ % & ' ( ) * + , - . /</font>
+ (<= 58 code 64) <font color="#008844">; : ; < = > ? @</font>
+ (<= 91 code 96) <font color="#008844">; [ \ ] ^ _ `</font>
+ (<= 123 code 126)) <font color="#008844">; { | } ~</font>
+ char)))
+<a name="char-space-p"></a>
+<font color="#008844">;; characters producing whitespace</font>
+<font color="#008844">;;</font>
+<font color="#008844">;; 9 = horizontal tab 10 = line feed 11 = vertical tab</font>
+<font color="#008844">;; 12 = form feed 13 = carriage return 32 = space</font>
+
+(defun <font color="#0000CC">char:space-p</font> (char)
+ (and (member (char-code char) '(9 10 11 12 13 32))
+ char))
+<a name="char-upper-p"></a>
+<font color="#008844">;; uppercase characters = A-Z</font>
+
+(defun <font color="#0000CC">char:upper-p</font> (char)
+ (and (upper-case-p char)
+ char))
+<a name="char-xdigit-p"></a>
+<font color="#008844">;; hexadecimal digits = 0-9, a-f, A-F</font>
+
+(defun <font color="#0000CC">char:xdigit-p</font> (char)
+ (and (or (digit-char-p char)
+ (let ((code (char-code char)))
+ (or (<= 65 code 70) <font color="#008844">; A-Z</font>
+ (<= 97 code 102)))) <font color="#008844">; a-z</font>
+ char))
+</pre>
+
+<p><b>User Functions</b> for POSIX character classes:</p>
+
+<a name="alnum-character-p"></a>
+
+<pre class="example">
+<font color="#008844">;; alphanumeric characters = a-z, A-z, 0-9</font>
+
+(defun <font color="#0000CC">alnum-character-p</font> (char)
+ (and (characterp char)
+ (char:alnum-p char)))
+<a name="alpha-character-p"></a>
+<font color="#008844">;; alphabetic characters = a-z, A-Z</font>
+
+(defun <font color="#0000CC">alpha-character-p</font> (char)
+ (and (characterp char)
+ (char:alpha-p char)))
+<a name="blank-character-p"></a>
+<font color="#008844">;; blanks = space and horizontal-tab</font>
+
+(defun <font color="#0000CC">blank-character-p</font> (char)
+ (and (characterp char)
+ (char:blank-p char)))
+<a name="cntrl-character-p"></a>
+<font color="#008844">;; control characters = code-chars 0-31 and 127</font>
+
+(defun <font color="#0000CC">cntrl-character-p</font> (char)
+ (and (characterp char)
+ (char:cntrl-p char)))
+<a name="digit-character-p"></a>
+<font color="#008844">;; decimal digits = 0-9</font>
+
+(defun <font color="#0000CC">digit-character-p</font> (char)
+ (and (characterp char)
+ (char:digit-p char)))
+<a name="graph-character-p"></a>
+<font color="#008844">;; graphical characters = alnum + punct</font>
+
+(defun <font color="#0000CC">graph-character-p</font> (char)
+ (and (characterp char)
+ (char:graph-p char)))
+<a name="lower-character-p"></a>
+<font color="#008844">;; lowercase characters = a-z</font>
+
+(defun <font color="#0000CC">lower-character-p</font> (char)
+ (and (characterp char)
+ (char:lower-p char)))
+<a name="print-character-p"></a>
+<font color="#008844">;; printable characters = alnum + punct + space</font>
+
+(defun <font color="#0000CC">print-character-p</font> (char)
+ (and (characterp char)
+ (char:print-p char)))
+<a name="punct-character-p"></a>
+<font color="#008844">;; punctuation marks</font>
+
+(defun <font color="#0000CC">punct-character-p</font> (char)
+ (and (characterp char)
+ (char:punct-p char)))
+<a name="space-character-p"></a>
+<font color="#008844">;; characters producing whitespace</font>
+
+(defun <font color="#0000CC">space-character-p</font> (char)
+ (and (characterp char)
+ (char:space-p char)))
+<a name="upper-character-p"></a>
+<font color="#008844">;; uppercase characters = A-Z</font>
+
+(defun <font color="#0000CC">upper-character-p</font> (char)
+ (and (characterp char)
+ (char:upper-p char)))
+<a name="xdigit-character-p"></a>
+<font color="#008844">;; hexadecimal digits = 0-9, a-f, A-F</font>
+
+(defun <font color="#0000CC">xdigit-character-p</font> (char)
+ (and (characterp char)
+ (char:xdigit-p char)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="unicode"></a>
+
+<hr>
+
+<h2>Unicode</h2>
+
+<hr>
+
+<p>The UTF-8 functions may help to write custom <nobr>UTF-8</nobr> string
+access functions like <nobr>UTF-8-SUBSEQ</nobr> or
+<nobr>UTF-8-STRING-SEARCH</nobr> with no need to care about the underlying
+<nobr>low-level</nobr> octal sequences.</p>
+
+
+
+<p>In the list of "string-characters" every ASCII or UTF-8 character
+from 1-byte to 4-byte is represented by its own list element:</p>
+
+<pre class="example">
+(utf-8-string-to-list "hällö") => ("h" "\303\244" "l" "l" "\303\266")
+ h ä l l ö
+</pre>
+
+<p>The list can be manipulated by standard Nyquist list functions and
+then re-converted into a string by UTF-8-LIST-TO-STRING.</p>
+
+Practical examples
+
+<p>In Nyquist code, non-ASCII characters are represented by their
+native bytes sequences, represented by escaped octal numbers:</p>
+
+<pre class="example">
+(print "ä") => "\303\244" <font color="#008844">; on UTF-8 systems</font>
+</pre>
+
+<p>So for example matching the second "ä" from "hällo" in the list
+above, represented by the octal sequence "\303\244":</p>
+
+<pre class="example">
+(let ((string-list (utf-8-string-to-list "hällö")))
+ (string= "ä" (nth 1 string-list))) ; 0 = first, 1 = second element
+=> T ; T = true = identified
+</pre>
+
+<p>Advantage: The number of the element in the list is the same as the
+number of the character in the string, independent from the number of bytes
+in the underlying character encoding.</p>
+
+;; The UTF-8 toolbox is intended to manipulate UTF-8 encoded file-
+;; or directory names, typed in by the user or read from environment
+;; variables, before they are given to SETDIR or OPEN.
+;;
+;; Information from the environment
+;;
+;; Because the encoding of the non-ASCII characters depends on the
+;; underlying operation system [with non-unicode operation systems
+;; there will be no UTF-8 encoding available], it's always better
+;; to refer to strings from environment variables, user input, or
+;; strings returned from the underlying file system, instead of
+;; hand-coded strings in the Nyquist source code, for example:
+;;
+;; GET-ENV - can read strings from environment variables:
+;;
+;; (defun user-home-directory ()
+;; (or (get-env "HOME") ; Unix
+;; (get-env "UserProfile"))) ; Windows
+;;
+;; On Windows, there is no HOME variable defined by Windows itself,
+;; but most programs will respect a HOME variable, if one has been
+;; defined by the user. That's why the HOME variable is read first.
+;;
+;; SETDIR - can test if a directory exists and return its name:
+;;
+;; (defun directory-exists-p (string)
+;; (let ((orig-dir (setdir "."))
+;; (new-dir (setdir string)))
+;; (when (string/= orig-dir new-dir)
+;; (setdir orig-dir)
+;; new-dir)))
+;;
+;; SETDIR always returns abloute direcory names, even if STRING is a
+;; relative direcory name. That's why DIRECTORY-EXISTS-P first stores
+;; the absolute name of the current working directory in the ORIG-DIR
+;; variable and compares it then against the absolute directory name
+;; returned by SETDIR when it tries to change the directory to STRING.
+;;
+;; OPEN - can test if a file exists and return its name:
+;;
+;; (defun file-exists-p (string)
+;; (unless (directory-exists-p string)
+;; (let (file-stream)
+;; (unwind-protect
+;; (setq file-stream (open string))
+;; (when file-stream (close file-stream)))
+;; (when file-stream string))))
+;;
+;; On Unix, a directory is a special kind of file, so the Nyquist/XLISP
+;; OPEN function opens directories, too. That's why FILE-EXISTS-P first
+;; must test and make sure that STRING is not the name of a directory.
+;;
+;;; Known bugs and limitations of the UTF-8 toolbox:
+;;
+;; The UTF-8 toolbox does not provide support for UTF-8 case-detection
+;; or UTF-8 case-conversion. It cannot be detected if a UTF-8 character
+;; is upper- or lowercase, it's also not possible to convert characters
+;; from upper- to lowercase or vice versa.
+;;
+;; The library does not provide functions to compare UTF-8 characters
+;; or to sort UTF-8 characters.
+;;
+;; The XLISP character functions do not work with UTF-8 octal sequences,
+;; so matching must be done via XLISP's STRING= and STRING/= functions.
+;;
+;; The XLISP string comparison functions like STRING<, STRING>, etc.
+;; do not work reliably with multibyte characters.
+;;
+;; The string matching and sorting algorithms of the Unicode Consortium
+;; are too complex to be implemented in XLISP with reasonable speed.
+;;
+;; See: http://www.unicode.org/reports/tr10/ - string comparison
+;;
+;; The library is implemented in interpreted Lisp, so please do not
+;; expect high-speed performance with advanced list manipulations.
+;;
+;; The library still has not been tested with ISO encoded systems.
+;;
+
+<p><b>UTF-8 Encoding</b> - see also http://en.wikipedia.org/wiki/UTF-8</p>
+
+
+<p>In an UTF-8 encoded character the first byte starts with:</p>
+
+<pre class="example">
+;; one-byte 0xxxxxxx -> legal char-codes 0 to 127 [UTF-8/ASCII]
+;; two-byte 110xxxxx -> legal char-codes 194 to 223 [UTF-8]
+;; three-byte 1110xxxx -> legal char-codes 224 to 239 [UTF-8]
+;; four-byte 11110xxx -> legal char-codes 240 to 244 [UTF-8]
+;;
+;; The second, third, and fourth characters start with:
+;;
+;; 10xxxxxx -> legal char-codes 128 to 191 [UTF-8]
+</pre>
+
+
+<p>UTF-8-BYTE-P tests if a XLISP character is a valid UTF-8 byte</p>
+
+<pre class="example">
+(defun utf-8-byte-p (char)
+ (when (characterp char)
+ (let ((code (char-code char)))
+ (when (or (<= 0 code 191)
+ (<= 194 code 244))
+ char))))
+</pre>
+
+<p>UTF-8-BYTES tries to determine from the XLISP character code
+how many bytes the character has in UTF-8 encoding</p>
+
+<pre class="example">
+(defun utf-8-bytes (char)
+ (cond ((not (characterp char))
+ (error "not a character" char))
+ ((not (utf-8-byte-p char))
+ (error "invalid UTF-8 byte" char))
+ (t
+ (let ((code (char-code char)))
+ (cond ((<= 0 code 127) 1) ; one byte [= ASCII]
+ ((<= 194 code 223) 2) ; two bytes
+ ((<= 224 code 239) 3) ; three bytes
+ ((<= 240 code 244) 4) ; four bytes
+ (t (error "utf-8-bytes: not an UTF-8 identifer" char)))))))
+</pre>
+
+<p>UTF-8-STRING-TO-LIST converts a string containing ASCII or UTF-8
+characters from one to four bytes into a list, where:</p>
+
+<ul>
+<li><nobr><b>ASCII</b> - ASCII string</nobr></li>
+<li><nobr><b>UTF-8</b> - string of octal-sequences</nobr></li>
+</ul>
+
+;; Every character (single-byte or multi-byte) is represented
+;; by its own list element:
+;;
+;; (utf-8-string-to-list "hällö") => ("h" "\303\244" "l" "l" "\303\266")
+;; h ä l l ö
+;;
+;; The list can be manipulated by standard XLISP list functions and
+;; then re-converted into a string by UTF-8-LIST-TO-STRING below.
+
+<pre class="example">
+(defun utf-8-string-to-list (string)
+ (cond
+ ((not (stringp string))
+ (error "utf-8-string-to-list: not a string" string))
+ ((string= "" string) nil)
+ (t
+ (let ((end (length string))
+ (list nil))
+ (do ((index 0 (1+ index)))
+ ((>= index end))
+ (let* ((char (char string index))
+ (bytes (1- (utf-8-bytes char)))
+ (utf-8 (string char)))
+ (dotimes (rest-of bytes) ; runs only if bytes > 0
+ (incf index)
+ (if (> index end)
+ (error "utf-8-string-to-list: index out of range" index)
+ (let ((byte (char string index)))
+ (if (not (utf-8-byte-p byte))
+ (error "utf-8-string-to-list: invalid UTF-8 byte" byte)
+ (setq utf-8 (strcat utf-8 (string byte)))))))
+ (push utf-8 list)))
+ (reverse list)))))
+</pre>
+
+;; UTF-8-LIST-TO-STRING re-converts a list containing ASCII and
+;; UTF-8 "string-characters" back to a XLISP string, intended
+;; to be given to SETDIR or OPEN for file or directory operations.
+
+<pre class="example">
+(defun utf-8-list-to-string (list)
+ (cond ((not (listp list))
+ (error "utf-8-list-to-string: not a list" list))
+ ((null list) "")
+ (t
+ (let ((result ""))
+ (dolist (string list)
+ (if (not (stringp string))
+ (error "utf-8-list-to-string: not a string" string)
+ (setq result (strcat result string))))
+ result))))
+</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/xlisp/ash.htm b/docsrc/xlisp/xlisp-doc/examples/xlisp/ash.htm new file mode 100644 index 0000000..2d17d98 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/xlisp/ash.htm @@ -0,0 +1,130 @@ +<html><head>
+
+<title>ash</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>ash</h1>
+
+<hr>
+
+<p>The 'ash' functio performs an '<nobr>arithmetic shift</nobr>' operation:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>ash</b> <i>integer count</i>)</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>count</i> - an integer expression<br>
+returns - the <i>number</i> shifted by <i>count</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">ash</font> (integer count)
+ (or (integerp integer) (error <font color="#880000">"not an integer"</font> integer))
+ (or (integerp count) (error <font color="#880000">"not an integer"</font> count))
+ (let* ((shift (* integer (expt 2.0 count)))
+ (trunc (truncate shift)))
+ <font color="#008844">;; XLISP implementation of (FLOOR SHIFT)</font>
+ (if (or (plusp shift) (= shift trunc))
+ trunc
+ (1- trunc))))
+</pre>
+
+<p>The 'ash' functio performs an arithmetic shift operation on the binary
+representation of the 'integer' argument, which is treated as if it were
+binary. <nobr>The 'integer'</nobr> argument is shifted arithmetically to the
+left by 'count' bit positions if 'count' is positive, or to the right by
+'count' bit positions if 'count' is negative. <nobr>The shifted</nobr> value
+of the same sign as 'integer' is returned.</p>
+
+<p>The 'ash' function performs the computation:</p>
+
+<pre class="example">
+floor (integer * 2^count)
+</pre>
+
+<p>Logically, the 'ash' function moves all of the bits in integer to the
+left, adding <nobr>zero-bits</nobr> at the right, or moves them to the
+right, discarding bits.</p>
+
+<p>The 'ash' function is defined to behave as if integer were represented in
+two's complement form, regardless of how integers are represented
+internally.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(ash 16 1) => 32
+(ash 16 0) => 16
+(ash 16 -1) => 8
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">debug:ash</font> (integer count)
+ (let ((shifted (ash integer count)))
+ (format t <font color="#880000">"integer: ~a~%"</font> (bin-string integer :all))
+ (format t <font color="#880000">"shifted: ~a~%"</font> (bin-string shifted :all))
+ shifted))
+</pre>
+
+<p>See <nobr><a href="../binary.htm">Binary Integer Numbers</a></nobr> for
+the '<nobr>bin-string</nobr>' function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/xlisp/bsh.htm b/docsrc/xlisp/xlisp-doc/examples/xlisp/bsh.htm new file mode 100644 index 0000000..31c8af6 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/xlisp/bsh.htm @@ -0,0 +1,127 @@ +<html><head>
+
+<title>bsh</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>bsh</h1>
+
+<hr>
+
+<p>The 'bsh' functio performs an '<nobr>binary shift</nobr>' operation:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>bsh</b> <i>integer count</i>)</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>count</i> - an integer expression<br>
+returns - the <i>number</i> shifted by <i>count</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">bsh</font> (integer count)
+ (or (integerp integer) (error <font color="#880000">"not an integer"</font> integer))
+ (or (integerp count) (error <font color="#880000">"not an integer"</font> count))
+ (if (zerop count)
+ integer
+ (let ((digits (or (dolist (bits '(16 32 64 128) nil)
+ (let ((fixnum (round (expt 2.0 (1- bits)))))
+ (and (plusp (1- fixnum))
+ (minusp fixnum)
+ (return bits))))
+ (error <font color="#880000">"integer limit not found"</font>)))
+ (list nil)
+ (string "#b"))
+ (dotimes (x digits)
+ (let ((digit (logand (round (expt 2.0 x)) integer)))
+ (push (if (zerop digit) "0" "1") list)))
+ (dotimes (x digits)
+ (let ((digit (if (< -1 count digits) (nth count list) "0")))
+ (setq string (strcat string digit))
+ (incf count)))
+ (eval (read (make-string-input-stream string))))))
+</pre>
+
+<p>The 'bsh' function performs a binary shift operation on the 'integer'
+argument. <nobr>The bits</nobr> of the 'integer' argument is shifted to the
+left by 'count' positions if 'count' is positive, or to the right by 'count'
+positions if 'count' is negative. <nobr>The missing</nobr> bits are filled
+with zeros.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(bsh 16 1) =>
+(bsh 16 0) =>
+(bsh 16 -1) =>
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">debug:bsh</font> (integer count)
+ (let ((shifted (bsh integer count)))
+ (format t <font color="#880000">"integer: ~a~%"</font> (bin-string integer :all))
+ (format t <font color="#880000">"shifted: ~a~%"</font> (bin-string shifted :all))
+ shifted))
+</pre>
+
+<p>See <nobr><a href="../binary.htm">Binary Integer Numbers</a></nobr> for
+the '<nobr>bin-string</nobr>' function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/xlisp/ceiling.htm b/docsrc/xlisp/xlisp-doc/examples/xlisp/ceiling.htm new file mode 100644 index 0000000..a005ff1 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/xlisp/ceiling.htm @@ -0,0 +1,103 @@ +<html><head>
+
+<title>ceiling</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>ceiling</h1>
+
+<hr>
+
+<p>The 'ceiling' function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward positive infinity:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>ceiling</b> <i>number</i>)</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> expression<br>
+returns - the integer result of truncating <i>number</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">ceiling</font> (number)
+ (let ((trunc (truncate number)))
+ (if (or (minusp number) (= number trunc))
+ trunc
+ (1+ trunc))))
+</pre>
+
+<p>The 'ceiling' function computes an integer number that has
+been truncated toward positive infinity. <nobr>That is</nobr>, the result
+represents the smallest mathematical integer that is not smaller than the
+number given as argument.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(ceiling 3) => 3 (ceiling -3) => -3
+(ceiling 3.0) => 3 (ceiling -3.0) => -3
+(ceiling 3.1) => 4 (ceiling -3.1) => -3
+(ceiling 3.5) => 4 (ceiling -3.5) => -3
+(ceiling 3.9) => 4 (ceiling -3.9) => -3
+(ceiling 4.0) => 4 (ceiling -4.0) => -4
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/xlisp/floor.htm b/docsrc/xlisp/xlisp-doc/examples/xlisp/floor.htm new file mode 100644 index 0000000..5851166 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/xlisp/floor.htm @@ -0,0 +1,103 @@ +<html><head>
+
+<title>floor</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>floor</h1>
+
+<hr>
+
+<p>The 'floor' function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward negative infinity:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>floor</b> <i>number</i>)</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> expression<br>
+returns - the integer result of truncating <i>number</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">floor</font> (number)
+ (let ((trunc (truncate number)))
+ (if (or (plusp number) (= number trunc))
+ trunc
+ (1- trunc))))
+</pre>
+
+<p>The 'floor' function computes an integer number that has been truncated
+toward negative infinity. <nobr>That is</nobr>, the result represents the
+largest mathematical integer that is not larger than the number given as
+argument.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(floor 3) => 3 (floor -3) => -3
+(floor 3.0) => 3 (floor -3.0) => -3
+(floor 3.1) => 3 (floor -3.1) => -4
+(floor 3.5) => 3 (floor -3.5) => -4
+(floor 3.9) => 3 (floor -3.9) => -4
+(floor 4.0) => 4 (floor -4.0) => -4
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/internals/c-printf.htm b/docsrc/xlisp/xlisp-doc/internals/c-printf.htm new file mode 100644 index 0000000..d5e552a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/internals/c-printf.htm @@ -0,0 +1,518 @@ +<html><head>
+
+<title>ANSI C 'printf' Format</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>ANSI C 'printf' Format</h1>
+
+<hr>
+
+<p><b>Nyquist/XLISP:</b> The
+<nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr> and
+<nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
+variables define format strings for the underlying 'sprintf' <nobr>C
+function</nobr>. <nobr>In C,</nobr> the same format string specification is
+used for 'fprint' [writes to <nobr>a file]</nobr>, 'printf' [writes to
+standard output] and 'sprintf' [writes to another string]. These three
+functions are meant in the following text with 'the printf functions'.</p>
+
+<p><b>ANSI C:</b> The printf functions write output under control of a
+format string that specifies how subsequent arguments are converted for
+output. If there are insufficient arguments for the format, the behavior is
+undefined. If the format is exhausted while arguments remain, the excess
+arguments are evaluated but are otherwise ignored. The printf functions
+return when the end of the format string is encountered.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="format-string"></a>
+
+<hr>
+
+<h2>Format String</h2>
+
+<hr>
+
+<p>The format string is composed of zero or more directives, which are
+ordinary characters <nobr>[except "%"]</nobr>, which are copied
+unchanged to the output stream, and conversion specifications, each of which
+results in fetching zero or more subsequent arguments. Each conversion
+specification is introduced by the <nobr>character "%"</nobr>:</p>
+
+<pre class="example">
+<font color="#AA0000">%</font>[<font color="#0000CC">flags</font>][<font color="#0000CC">field-with</font>][<font color="#0000CC">precision</font>][<font color="#0000CC">data-type</font>]<font color="#880000">conversion-type</font>
+</pre>
+
+<p>After the "%", the following appear in sequence:</p>
+
+<ul>
+
+<li><p><b>Flags</b> - Zero or more <a href="#flags">flags</a> that modify
+the meaning of the conversion specification.</p></li>
+
+<li><p><b>Field Width</b> - <nobr>An optional</nobr> decimal integer
+specifying a minimum field width. <nobr>If the</nobr> converted value has
+fewer characters than the field width, it will be padded with spaces on the
+left to the field width. <nobr>The field</nobr> is padded on the right if
+the <nobr><a href="#minus-flag"> − </a> flag</nobr> has been
+given, or padded with zeros if the
+<nobr><a href="#zero-flag"> 0 </a> flag</nobr> had been
+given. <nobr>A negative</nobr> integer, given as '<nobr>field width</nobr>'
+argument, is interpreted as a
+<nobr><a href="#minus-flag"> − </a> flag</nobr> followed by
+a positive <nobr>field width</nobr>.</p></li>
+
+<li><p><b>Precision</b> - <nobr>An optional</nobr> decimal integer that
+gives the minimum number of digits to appear for
+<a href="#integer">integer</a> conversions, the number of digits to appear
+after the
+<nobr>decimal-point</nobr> character for <nobr>floating-point</nobr>
+<nobr><a href="#float-e"> e </a></nobr> and
+<nobr><a href="#float-f"> f </a></nobr> conversions, or the
+maximum number of significant digits for the <nobr>floating-point</nobr>
+<nobr><a href="#float-g"> g </a></nobr> conversion.</p>
+
+<p>The precision takes the form of a period character followed by an
+optional decimal integer:</p>
+
+<pre class="example">
+.[<font color="#0000CC">integer</font>]
+</pre>
+
+<p><nobr>If the</nobr> integer is omitted, it is treated as zero, a
+negative precision argument is taken as if it were missing.</p>
+
+<p><b>Note:</b> <nobr>In C</nobr>, the precision also specifies the
+maximum number of characters to be written from a string in <nobr>'s'
+conversion</nobr>, but "%s" should not be used in the XLISP
+<nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr> or
+<nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
+variables, otherwise XLISP will crash.</p></li>
+
+</li>
+
+<li><p><b>Data Type</b> - <nobr>An optional</nobr> character specifying a
+<nobr><a href="#data-type">data type</a></nobr> to be used for the
+conversion.</p>
+
+<p><b>XLISP:</b> Nyquist/XLISP uses <nobr>C 'long'</nobr> signed integers
+and <nobr>C 'double'</nobr> floats only, so with <nobr>floating-point</nobr>
+numbers no special <nobr><a href="#data-type">data type</a></nobr> needs to
+be given, while <a href="#integer">integer</a> conversions should always be
+prefixed by a <nobr>'l' [lowercase L]</nobr>, otherwise the printed
+representation of integer numbers may be differently than the behaviour of
+the Nyquist/XLISP functions.</nobr></p></li>
+
+<li><p><b>Conversion Type</b> - <nobr>A character</nobr> that specifies the
+<nobr><a href="#conversion-type">conversion type</a></nobr> to be
+applied.</p></li>
+
+</ul>
+
+<p><b>Not with Nyquist/XLISP:</b> <nobr>In C</nobr>, a '<nobr>field
+width</nobr>' or 'precision', or both, may be indicated by an asterisk *
+instead of a digit string. In this case, an int argument supplies the field
+width or precision. The arguments specifying field width or precision, or
+both, shall appear [in that order] before the argument [if any] to be
+converted.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="flags"></a>
+
+<hr>
+
+<h2>Flags</h2>
+
+<hr>
+
+<p>The flag characters and their meanings are:</p>
+
+<p><div class="box">
+
+<dl>
+
+<a name="minus-flag"></a>
+
+<dt><p><nobr>− [minus sign character]</nobr></p></dt>
+
+<dd><p>The result of the conversion will be <nobr>left-justified</nobr>
+within the field.</p></dd>
+
+<a name="plus-flag"></a>
+
+<dt><p><nobr>+ [plus sign character]</nobr></p></dt>
+
+<dd><p>The result of a signed conversion will always begin with a plus or
+minus sign.</p></dd>
+
+<a name="space-flag"></a>
+
+<dt><p><nobr><i>space</i> [space character]</nobr></p></dt>
+
+<dd><p>If the first character of a signed conversion is not a sign, or if a
+signed conversion results in no characters, a space will be prepended to the
+result. <nobr>If the</nobr> 'space' and
+<nobr><a href="#plus-flag"> + </a> flags</nobr> both appear, the
+'space' flag will be ignored.</p></dd>
+
+<a name="hash-flag"></a>
+
+<dt><p><nobr># [hash character]</nobr></p></dt>
+
+<dd><p>The result is to be converted to an 'alternate form':</p>
+
+<p>Octal Numbers - For o conversion, it increases the precision to force the
+first digit of the result to be a zero.</p>
+
+<p>Hexadecimal Numbers - For x or X conversion, a nonzero result will have
+0x or 0X prepended to it.</p>
+
+<p>Floating-point Numbers - For e, E, f, g, and G conversions, the result
+will always contain a decimal-point character, even if no digits follow it
+(normally, a decimal-point character appears in the result of these
+conversions only if a digit follows it). For g and G conversions, trailing
+zeros will not be removed from the result. For other conversions, the
+behavior is undefined.</p>
+
+</dd>
+
+<a name="zero-flag"></a>
+
+<dt><p><nobr>0 [number zero character]</nobr></p></dt>
+
+<dd><p>For integer d, i, o, u, x, X, and floating-point e, E, f, g, G
+conversions, leading zeros [following any indication of sign or base] are
+used to pad to the <nobr><a href="#format-string">field width</a></nobr>.
+<nobr>No <a href="#space-flag">space</a></nobr> padding is performed.
+<nobr>If the</nobr> '0' and
+<nobr><a href="#minus-flag"> − </a> flags</nobr> both
+appear, the <nobr>'0' flag</nobr> will be ignored. For integer d, i, o, u,
+x, X conversions, if a <a href="#format-string">precision</a> is specified,
+the <nobr>'0' flag</nobr> will be ignored. <nobr>For other</nobr>
+conversions, the behavior is undefined.</p></dd>
+
+</dl>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="data-type"></a>
+
+<hr>
+
+<h2>Data Type</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+
+<dt><p><nobr><b>h</b> [lowercase H character]</nobr></p></dt>
+
+<dd><p>A following d, i, o, u, x, or X conversion specifier applies to a
+short int or unsigned short int argument [the argument will have been
+promoted according to the integral promotions, and its value shall be
+converted to short int or unsigned short int before printing].</p>
+
+<p>A following n conversion specifier applies to a pointer to a short int
+argument.</p></dd>
+
+<dt><p><nobr><b>l</b> [lowercase L character]</nobr></p></dt>
+
+<dd><p>A following d, i, o, u, x, or X conversion specifier applies to a
+long int or unsigned long int argument.</p>
+
+<p>A following n conversion specifier applies to a pointer to a long int
+argument.</p></dd>
+
+<dt><p><nobr><b>L</b> [uppercase L character]</nobr></p></dt>
+
+<dd><p>A following e, E, f, g, or G conversion specifier applies to a long
+double argument.</p></dd>
+
+</dl>
+
+</div></p>
+
+<p>If an h, l, or L appears with any other conversion specifier, the
+behavior is undefined.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="conversion-type"></a>
+
+<hr>
+
+<h2>Conversion Type</h2>
+
+<hr>
+
+<p><b>Integer</b> conversion:</p>
+
+<p><div class="box">
+
+<dl>
+
+<a name="integer"></a>
+
+<dt><p><nobr><b>d</b>, <b>i</b>, <b>o</b>, <b>u</b>, <b>x</b>,
+<b>X</b></nobr></p></dt>
+
+<dd><p>The integer argument is converted to:
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="center"><nobr>d</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td><nobr>signed decimal</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="center"><nobr>i</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td><nobr>signed decimal</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="center"><nobr>o</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td><nobr>unsigned octal</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="center"><nobr>u</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td><nobr>unsigned decimal</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="center"><nobr>x</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td><nobr>unsigned hexadecimal, using 'abcdef'</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="center"><nobr>X</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td><nobr>unsigned hexadecimal, using 'ABCDEF'</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>The <a href="#format-string">precision</a> specifies the minimum number
+of digits to appear. <nobr>If the</nobr> value being converted can be
+represented in fewer digits, it will be expanded with leading zeros. The
+default precision <nobr>is 1</nobr>. The result of converting a zero value
+with an explicit precision of zero results in no characters.</p>
+
+<b>XLISP:</b> Nyquist/XLISP uses <nobr>C 'long'</nobr> signed integers, so
+the integer conversions should always be prefixed by a <nobr>'l' [lowercase
+L]</nobr> indicating a '<nobr>long int</nobr>' <nobr>C
+<a href="#data-type">data type</a></nobr>, otherwise the printed
+representation of integer numbers may be differently than the behaviour of
+the Nyquist/XLISP functions.</p></dd>
+
+</dl>
+
+</div></p>
+
+<p><b>Floating-point</b> conversion:</p>
+
+<p><div class="box">
+
+<dl>
+
+<a name="float-f"></a>
+
+<dt><p><b>f</b></p></dt>
+
+<dd><p>The <nobr>floating-point</nobr> argument of <nobr>C data</nobr> type
+'double' is converted to decimal notation in the style:</p>
+
+<pre class="example">
+[-]<font color="#0000CC">ddd</font>.<font color="#0000CC">ddd</font>
+</pre>
+
+<p>where the number of digits after the <nobr>decimal-point</nobr> character
+is equal to the <a href="#format-string">precision</a> specification.
+<nobr>If the</nobr> <a href="#format-string">precision</a> is missing, it is
+taken <nobr>as 6</nobr>. <nobr>If the</nobr>
+<a href="#format-string">precision</a> is explicitly zero, no
+<nobr>decimal-point</nobr> character appears. <nobr>If a</nobr>
+<nobr>decimal-point</nobr> character appears, at least one digit appears
+<nobr>before it</nobr>. <nobr>The value</nobr> is rounded to the appropriate
+number of digits.</p></dd>
+
+<a name="float-e"></a>
+
+<dt><p><b>e</b>, <b>E</b></p></dt>
+
+<dd><p>The <nobr>floating-point</nobr> argument of <nobr>C data</nobr> type
+'double' is converted in the style:</p>
+
+<pre class="example">
+[-]<font color="#0000CC">d</font>.<font color="#0000CC">ddd</font><font color="#AA0000">e</font>+-<font color="#0000CC">dd</font>
+</pre>
+
+<p>where there is one digit before the <nobr>decimal-point</nobr> character
+[which is nonzero if the argument is nonzero] and the number of digits after
+it is equal to the <a href="#format-string">precision</a>. <nobr>If
+the</nobr> <a href="#format-string">precision</a> is missing, it is taken
+<nobr>as 6</nobr>. <nobr>If the</nobr>
+<a href="#format-string">precision</a> is zero, no
+<nobr>decimal-point</nobr> character appears. <nobr>The value</nobr> is
+rounded to the appropriate number of digits. <nobr>The exponent</nobr>
+always contains at least two digits. <nobr>If the</nobr> value is zero, the
+exponent is zero. <nobr>The "E"</nobr> conversion specifier will
+produce a number with 'E' instead of 'e' introducing the exponent.</p> </dd>
+
+<a name="float-g"></a>
+
+<dt><p><b>g</b>, <b>G</b></p></dt>
+
+<dd><p>The <nobr>floating-point</nobr> argument of <nobr>C data</nobr> type
+'double' is converted in style <a href="#float-f"> f </a> or
+<a href="#float-e"> e </a> or in style
+<a href="#float-e"> E </a> in the case of a "G"
+conversion specifier, with the <a href="#format-string">precision</a>
+specifying the number of significant digits. <nobr>If an</nobr> explicit
+<a href="#format-string">precision</a> is zero, it is taken <nobr>as
+1</nobr>. <nobr>The style</nobr> used depends on the value converted.
+<nobr>Style <a href="#float-"> e </a></nobr> will be used only if
+the exponent resulting from such a conversion is less <nobr>than -4</nobr>
+or greater than or equal to the <a href="#format-string">precision</a>.
+Trailing zeros are removed from the fractional portion of the result.
+<nobr>A decimal-point</nobr> character appears only if it is followed by
+<nobr>a digit</nobr>.</p></dd>
+
+</dl>
+
+</div></p>
+
+<p>Other conversion types defined <nobr>in ANSI C</nobr>, but <b>not</b> to
+be used with the XLISP
+<nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr> and
+<nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
+variables, because XLISP will produce nonsense or just simply will crash:</p>
+
+<p><div class="box">
+
+<dl>
+
+<dt><p><b>c</b></p></dt>
+
+<dd><p>The integer argument is converted to an '<nobr>unsigned char</nobr>',
+and the resulting character is written.</p>
+
+<p><b>XLISP:</b> If the
+<nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr> or
+<nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
+variable is set to "%c", then with integers or
+<nobr>floating-point</nobr> numbers, the lowest <nobr>8 bit</nobr> of the
+internal binary representation will be interpreted as an
+<a href="">ASCII</a> character.</p></dd>
+
+<dt><p><b>s</b></p></dt>
+
+<dd><p>The argument shall be a pointer to an array of character type.
+Characters from the array are written up to [but not including] a
+terminating null character. <nobr>If the</nobr>
+<a href="#format-string">precision</a> is specified, no more than that many
+characters are written. <nobr>If the</nobr>
+<a href="#format-string">precision</a> is not specified or is greater than
+the size of the array, the array shall contain a null character.</p>
+
+XLISP: If </dd>
+
+<dt><p><b>p</b></p></dt>
+
+<dd><p>The argument shall be a pointer to 'void'. The value of the pointer
+is converted to a sequence of printable characters, in an
+<nobr>implementation-defined</nobr> manner.</p></dd>
+
+<dt><p><b>n</b></p></dt>
+
+<dd><p>The argument shall be a pointer to an integer into which is written
+the number of characters written to the output stream so far by this call to
+the <nobr>C 'fprintf'</nobr> function.<nobr> No argument</nobr> is
+converted.</p></dd>
+
+<dt><p><b>%</b></p></dt>
+
+<dd><p><nobr>A "%"</nobr> is written. <nobr>No argument</nobr> is
+converted. <nobr>The complete</nobr> conversion specification <nobr>shall be
+"%%"</nobr>.</p></dd>
+
+</dl>
+
+</div></p>
+
+<p>If a conversion specification is invalid, the behavior is undefined.
+<nobr>In no</nobr> case does a nonexistent or small
+<nobr><a href="#format-string">field width</a></nobr> cause truncation of a
+field. <nobr>If the</nobr> result of a conversion is wider than the
+<nobr><a href="#format-string">field width</a></nobr>, the field is expanded
+to contain the conversion result.</p>
+
+<p>The minimum value for the maximum number of characters produced by
+any single conversion shall be 509.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/internals/xlisp-internals.html b/docsrc/xlisp/xlisp-doc/internals/xlisp-internals.html new file mode 100644 index 0000000..2a7ffc0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/internals/xlisp-internals.html @@ -0,0 +1,1206 @@ +<html><head><title>XLISP Internals</title>
+
+<style type="text/css">
+ pre.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 8px;
+ padding-right: 8px;
+ padding-bottom: 8px;
+ padding-left: 8px;
+ border: #808080;
+ border-style: solid;
+ border-top-width: 1px;
+ border-right-width: 1px;
+ border-bottom-width: 1px;
+ border-left-width: 1px;
+ width:auto;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>XLISP Internals</h1>
+
+<hr>
+
+<p>92Jan14 jsp@glia.biostr.washington.edu [Jeff Prothero]. Public Domain.</p>
+
+<pre>
+ +---------------------+
+ | xlisp 2.1 internals |
+ +---------------------+
+
+ "Trust the Source, Luke, trust the Source!"
+</pre>
+
+<hr>
+
+<h2> Contents</h2>
+
+<hr>
+
+<ol>
+<li><nobr><a href="xlisp-internals.html#SEC01">Who should read this?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC02">What is an LVAL?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC03">What is the obarray?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC04">The Interpreter Stacks</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC05">What is a context?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC06">What is an environment?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC07">How are XLISP entities stored and identified?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC08">How are vectors implemented?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC09">How are strings implemented?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC10">How are symbols implemented?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC11">How are closures implemented?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC12">How are objects implemented?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC13">How are classes implemented?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC14">How is the class hierarchy laid out?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC15">How do we look up the value of a variable?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC16">How are function calls implemented?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC17">How are message-sends implemented?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC18">How is garbage collection implemented?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC19">How are the source files laid out?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC20">How do I add a new primitive fn to xlisp?</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC21">Minor Observations.</a></nobr></li>
+<li><nobr><a href="xlisp-internals.html#SEC22">Acknowledgements. </a></nobr></li>
+</ol>
+
+<a name="SEC01"></a>
+
+<hr>
+
+<h2>Who should read this ?</h2>
+
+<hr>
+
+<p>Anyone poking through the C implementation of XLISP for the first time.
+This is intended to provide a rough roadmap of the global XLISP structures
+and algorithms. If you just want to write lisp code in XLISP, you don't need
+to read this file. Go read the
+<nobr><a href="../manual/xlisp-man-index.htm">XLISP 2.0 Manual</a>,</nobr>
+the <nobr><a href="../tutorials/xlisp-objects.htm">XLisp Objects Primer</a>,</nobr>
+and the <nobr><a href="../reference/reference-index.htm">XLisp Language Reference</a>,</nobr>
+in about that order. If you want to tinker with the XLISP implementation
+code, you should *still* read those three before reading this. The following
+isn't intended to be exhaustively precise, that's what the source code is
+for. It is intended only to allow you a fighting change of understanding the
+code the first time through [instead of the third time].</p>
+
+<p>At the bottom of the file you'll find an example of how to add new
+primitive functions to XLISP.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="SEC02"></a>
+
+<hr>
+
+<h2>What is an LVAL ?</h2>
+
+<hr>
+
+<p>An LVAL is the C type for a generic pointer to an XLISP
+garbage-collectable something. [Cons cell, object, string, closure, symbol,
+vector, whatever.] Virtually every variable in the interpreter is an LVAL.
+Cons cells contain two LVAL slots, symbols contains four LVAL slots,
+etc.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="SEC03"></a>
+
+<hr>
+
+<h2>What is the obarray ?</h2>
+
+<hr>
+
+<p>The obarray is the XLISP symbol table. More precisely, it is a hashtable
+mapping ASCII strings [symbol names] to symbols. [The name 'obarray' is
+traditional but a bit of a misnomer, since it contains only XLISP symbols,
+and in particular contains no XLISP objects.] It is used when converting
+Lisp expressions from text to internal form. Since it is a root for the
+garbage collector, it also serves to distinguish permanent global-variable
+symbols from other symbols. You can permanently protect a symbol from the
+garbage collector by entering it into the obarray. This is called
+'interning' the symbol. The obarray is called 'obarray' in C and
+<a href="../reference/global-obarray.htm">*obarray*</a>
+in XLISP. It is physically implemented as a vector-valued symbol.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="SEC04"></a>
+
+<hr>
+
+<h2>The Interpreter Stacks</h2>
+
+<hr>
+
+<p>XLISP uses two stacks, an 'evaluation stack' and an 'argument stack'.
+Both are roots for the garbage collector. The evaluation stack is largely
+private to the interpreter and protects internal values from garbage
+collection, while the argument stack holds the conventional user-visible
+stackframes.</p>
+
+<p>The evaluation stack is an 'edepth'-long array of LVAL allocated by
+'xldmem.c:xlminit()'. It grows zeroward.</p>
+
+<p>'xlstkbase' points to the zero-near end of the evaluation stack.</p>
+
+<p>'xlstktop' points to the zero-far end of the evaluation stack, the
+occupied part of the stack lies between 'xlstack' and 'xlstktop'. Note that
+'xlstktop' is *NOT* the top of the stack in the conventional sense of
+indicating the most recent entry on the stack. 'xlstktop' is a static bounds
+pointer which never changes once the stack is allocated.</p>
+
+<p>'xlstack' starts at the zero-far end of the evaluation stack. '*xlstack'
+is the most recent LVAL on the stack. The garbage collector marks everything
+reachable from the evaluation stack [among other things], so we frequently
+push things on this stack while C code is manipulating them. [Via
+'xlsave()', 'xlprotect()', 'xlsave1()', 'xlprot1()'.]</p>
+
+<p>The argument stack is an 'adepth'-long array of LVAL. It also grows
+zeroward. The evaluator pushes arguments on the argument stack at the start
+of a function call [form evaluation]. Built-in functions usually eat them
+directly off the stack. For user-lisp functions 'xleval.c:evfun()' pops them
+off the stack and binds them to the appropriate symbols before beginning
+execution of the function body proper.</p>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td colspan="3"><nobr><b>xlargstkbase</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">is the zero-near end of argument stack.</td>
+</tr>
+<tr>
+ <td><nobr><font size="-2"> </font></nobr></td>
+</tr>
+<tr valign="top">
+ <td colspan="3"><nobr><b>xlargstktop</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">is the zero-far end of argument stack. Like 'xlstktop',
+ 'xlargstktop' is a static bounds pointer which never changes after the
+ stack is allocated.</td>
+</tr>
+<tr>
+ <td><nobr><font size="-2"> </font></nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>*xlsp</b></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[stack pointer]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">is the most recent item on the argument stack.</td>
+</tr>
+<tr>
+ <td><nobr><font size="-2"> </font></nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>*xlfp</b></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[frame pointer]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">is the base of the current stackframe.</td>
+</tr>
+</tbody></table></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="SEC05"></a>
+
+<hr>
+
+<h2>What is a context ?</h2>
+
+<hr>
+
+<p>A XLISP context is something like a checkpoint, recording a particular
+point buried in the execution history so that we can abort or return back to
+it. Contexts are used to implement call and return, catch and throw,
+signals, gotos, and breaks. 'xlcontext' points to the chain of active
+contexts, the top one being the second-newest active context. [The newest,
+that is, the current, active context is implemented by the variables
+'xlstack', 'xlenv', 'xlfenv', 'xldenv', 'xlcontext', 'xlargv', 'xlargc',
+'xlfp', and 'xlsp'.] Context records are written by 'xljump.c:xlbegin()' and
+read by 'xljump.c:xljump()'. Context records are C structures on the C
+program stack. They are not in the dynamic memory pool or on the Lisp
+execution or argument stacks.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="SEC06"></a>
+
+<hr>
+
+<h2>What is an environment ?</h2>
+
+<hr>
+
+<p>An environment is basically a store of symbol-value pairs, used to
+resolve variable references by the Lisp program. XLISP maintains three
+environments, in the global variables 'xlenv', 'xlfenv' and 'xldenv'.</p>
+
+<p>Lisp supports two sorts of binding, 'lexical binding' and 'dynamic
+binding'. Lexically bound variables are visible only in code textually
+within their binding form. Dynamically bound variables are visible in any
+code *called* from the binding form. [Either kind of binding may be shadowed
+by other declarations, of course.] Historically, Lisp has been moving from
+dynamic binding [which is easy for interpreters to handle], to lexical
+binding [which is easy for humans and compilers to handle]. Almost all XLISP
+binding forms are lexically scoped. The most important exception is
+<a href="../reference/progv.htm">progv</a>.</p>
+
+<p>'xlenv' and 'xlfenv' track lexical bindings. 'xlenv' and 'xlfenf' are
+conceptually a single environment, although they are implemented separately.
+They are linked-list stacks which are pushed when we enter a function and
+popped when we exit it. We also switch 'xlenv+xlfenf' environments entirely
+when we begin executing a new closure [user-function written in Lisp].</p>
+
+<p>The 'xlenv' environment is the most heavily used environment. It is used
+to resolve everyday data references to local variables. It consists of a
+list of frames [and objects]. Each frame is a list of symbol-value pairs. In
+the case of an object, we check all the instance and class variables of the
+object, then do the same for its superclass, until we run out of
+superclasses.</p>
+
+<p>The 'xlfenv' environment is maintained strictly parallel to 'xlenv', but
+is used to find function values instead of variable values. The separation
+may be partly for lookup speed and partly for historical reasons. Merging
+these two lists into a single list [while distinguishing function bindings
+from variable bindings, of course] would slightly decrease fn enter/exit
+overhead while increasing the overhead of looking up each variable or
+function binding.</p>
+
+<p>When we send a message, we set 'xlenv' to the value it had when the
+message closure was built, then push on (obj msg-class), where 'msg-class'
+is the [super]class defining the method. [We also set 'xlfenv' to the value
+'xlfenv' had when the method was built.] This makes the object instance
+variables part of the environment, and saves the information needed to
+correctly resolve references to class variables, and to implement
+<a href="../reference/send-super.htm">send-super</a>.</p>
+
+<p>The 'xldenv' environment tracks dynamic bindings. It is a simple list of
+symbol-value pairs, treated as a stack.
+<a href="../reference/progv.htm">progv</a> uses it to save the old
+values of symbols it binds, and it is also used to save old values of
+'s_evalhook' and 's_applyhook'
+[<a href="../reference/global-evalhook.htm">*evalhook*</a> and
+<a href="../reference/global-applyhook.htm">*applyhook*</a>]. These latter
+mostly support the debug facilities.</p>
+
+<p>These environments are manipulated in C via the 'xlisp.h' macros
+'xlframe(e)', 'xlbind(s,v)', 'xlfbind(s,v)', 'xlpbind(s,v,e)',
+'xldbind(s,v)', 'xlunbind(e)'.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="SEC07"></a>
+
+<hr>
+
+<h2>How are XLISP entities stored and identified ?</h2>
+
+<hr>
+
+<p>Conceptually, XLISP manages memory as a single array of fixed-size
+objects. Keeping all objects the same size simplifies memory management
+enormously, since any object can be allocated anywhere, and complex
+compacting schemes aren't needed. Every LVAL pointer points somewhere in
+this array. Every XLISP object has the basic format <nobr>'xldmem.h:typdef
+struct node':</nobr></p>
+
+<pre class="example">
+struct node {
+ char n_type;
+ char n_flags;
+ LVAL car;
+ LVAL cdr;
+}
+</pre>
+
+<p>where 'n_type' is one of:</p>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr><b>FREE</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">a node on the freelist.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>SUBR</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">a function implemented in C. [Needs evaluated arguments.]</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>FSUBR</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">a 'special form' implemented in C. [Needs unevaluated arguments.]</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>CONS</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">a regular lisp cons cell.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>SYMBOL</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">a symbol.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>FIXNUM</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">an integer.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>FLONUM</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">a floating-point number.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>STRING</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">a string.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>OBJECT</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">any object, including
+ <a href="../reference/class.htm">class</a> objects.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>STREAM</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">an input or output file.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>VECTOR</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">a variable-size array of LVALs.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>CLOSURE</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">result of <a href="../reference/defun.htm">defun</a>
+ or <a href="../reference/lambda.htm">lambda</a>, a function
+ written in Lisp.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>CHAR</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">an ASCII character.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>USTREAM</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">an internal stream.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>STRUCT</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">a structure.</td>
+</tr>
+</tbody></table></p>
+
+<p>Messages may be sent only to nodes with a 'n_type' of OBJECT.</p>
+
+<p>Obviously, several of the above types won't fit in a fixed-size two-slot
+node. The escape is to have them 'malloc()' some memory and have one of the
+slots point to it. VECTOR is the archetype. For example, see
+'xldmem.c:newvector()'. To some extent, this 'malloc()' hack simply exports
+the memory fragmentation problem to the C 'malloc()/free()' routines.
+However, it helps keep XLISP simple, and it has the happy side-effect of
+unpinning the body of the vector, so that vectors can easily be expanded and
+contracted.</p>
+
+<p>The garbage collector has special-case code for each of the above node
+types, so it can find all LVAL slots and recycle any 'malloc()'-ed ram when
+a node is garbage-collected.</p>
+
+<p>XLISP pre-allocates nodes for all ASCII characters, and for small
+integers. These nodes are never garbage-collected.</p>
+
+<p>As a practical matter, allocating all nodes in a single array is not very
+sensible. Instead, nodes are allocated as needed, in segments of one or two
+thousand nodes, and the segments linked by a pointer chain rooted at
+'xldmem.c:segs'.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="SEC08"></a>
+
+<hr>
+
+<h2>How are vectors implemented ?</h2>
+
+<hr>
+
+<p>An XLISP vector is a generic array of LVAL slots. Vectors are also the
+canonical illustration of XLISP's escape mechanism for node types which need
+more than two LVAL slots [the maximum possible in the fixed-size nodes in
+the dynamic memory pool]. The node CAR/CDR slots for a vector hold a size
+field plus a pointer to a 'malloc()'-ed ram chunk, which is automatically
+'free()'-ed when the vector is garbage-collected.</p>
+
+<p>'xldmem.h' defines macros for reading and writing vector fields and
+slots, 'getsize()', 'getelement()' and 'setelement()'. It also defines
+macros for accessing each of the other types of XLISP nodes.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="SEC09"></a>
+
+<hr>
+
+<h2>How are strings implemented ?</h2>
+
+<hr>
+
+<p>Strings work much like vectors. The node has a pointer to a 'malloc()'-ed
+ram chunk which is automatically 'free()'-ed when the string gets
+garbage-collected.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="SEC10"></a>
+
+<hr>
+
+<h2>How are symbols implemented ?</h2>
+
+<hr>
+
+<p>A symbol is a generic user-visible Lisp variable, with separate slots for
+print name, value, function, and property list. Any or all of these slots
+[including name] may be NIL.</p>
+
+<p>You create an XLISP symbol from C by calling 'xlmakesym(name)' or
+'xlenter(name)' [to make a symbol and enter it in the obarray].</p>
+
+<p>You may create symbols from XLISP by explicitly calling
+<a href="../reference/gensym.htm">gensym</a>,
+<a href="reference/make-symbol.htm">make-symbol</a> [uninterned symbols],
+or <a href="../reference/intern.htm">intern</a> [interned symbol].
+However, the Lisp reader will create symbols on sight, so most Lisp symbols
+are created as side-effects of expressions like:</p>
+
+<pre class="example">
+'name
+</pre>
+
+<p>A symbol is <a href="../reference/intern.htm">intern</a>ed if it
+is listed in the <a href="../reference/global-obarray.htm">*obarray*</a>.
+Various parts of the system, like the Lisp reader, treat the
+<a href="../reference/global-obarray.htm">*obarray*</a>
+essentially as the list of all known symbols. It is unusual but occasionally
+useful to create uninterned symbols. You can make
+<a href="../reference/read.htm">read</a> create an uninterned
+symbol by preceding it with '#:'. In XLISP, a newly created symbol has no
+value unless its name begins with a ':', in which case it has itself for its
+value. Handy for keywords and message selectors.]</p>
+
+<p>Most of the symbol-specific code in the interpreter is in 'xlsym.c'.</p>
+
+<p>Physically, a symbol is implemented like a four-slot vector [print name,
+value, function, and property list].</p>
+
+<p>Random musing: Abstractly, the Lisp symbols plus cons cells [etc.]
+constitute a single directed graph, and the symbols mark spots where normal
+recursive evaluation should stop. Normal Lisp programming practice is to
+have a symbol in every cycle in the graph, so that recursive traversal can
+be done without mark bits.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="SEC11"></a>
+
+<hr>
+
+<h2>How are closures implemented ?</h2>
+
+<hr>
+
+<p>A closure, the return value from a
+<a href="../reference/lambda.htm">lambda</a>, is a regular
+coded-in-lisp function. Physically, it is implemented like an eleven-slot
+vector, with the node 'n_type' field hacked to contain CLOSURE instead of
+VECTOR. The vector slots contain:</p>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr><b>name</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">a symbol, the first argument of
+ <a href="../reference/defun.htm">defun</a>.
+ <a href="../reference/nil.htm">nil</a> for
+ <a href="../reference/lambda.htm">lambda</a> closures.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>type</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">'s_lambda' or 's_macro'. Must be 's_lambda' to be
+ executable.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>args</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">list of required formal arguments [as symbols].</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>oargs</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">list of
+ <a href="../reference/lambda-keyword-optional.htm">&optional</a> arguments,
+ each like <nobr>(name (default specified-p)).</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>rest</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">name of '&rest' formal arguments, else
+ <a href="../reference/nil.htm">nil</a>.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>kargs</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><a href="../reference/lambda-keyword-key.htm">&key</a>-word
+ arguments, each like <nobr>((':foo 'bar default specified-p))</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>aargs</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><a href="../reference/lambda-keyword-aux.htm">&aux</a>
+ variables, each like <nobr>(('arg default)).</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>body</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">actual code [as a Lisp list] for the function.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>env</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">value of 'xlenv' when the closure was built.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>fenv</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">value of 'xlfend' when the closure was built.</td>
+</tr>
+<tr valign="top">
+ <td><nobr><b>lambda</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">the original formal args list in the
+ <a href="../reference/defun.htm">defun</a> or
+ <a href="../reference/lambda.htm">lambda</a>.</td>
+</tr>
+</tbody></table></p>
+
+<p>The lambda field is for printout purposes. The remaining fields store a
+predigested version of the formal arguments list. This is a limited form of
+compilation. By processing the arguments list at closure-creation time, we
+reduce the work needed during calls to the closure.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="SEC12"></a>
+
+<hr>
+
+<h2>How are objects implemented ?</h2>
+
+<hr>
+
+<p>An object is implemented like a vector, with the size determined by the
+number of instance variables. The first slot in the vector points to the
+class of the object, the remaining slots hold the instance variables for the
+object. An object needs enough slots to hold all the instance variables
+defined by its class, *plus* all the instance variables defined by all of
+its superclasses.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="SEC13"></a>
+
+<hr>
+
+<h2>How are classes implemented ?</h2>
+
+<hr>
+
+<p>A class is a specific kind of object, hence has a class pointer plus
+instance variables. All classes have the following instance variables:</p>
+
+<pre>
+ MESSAGES a list of <nobr>(interned-symbol method-closure)</nobr> pairs.
+ IVARS instance variable names, a list of interned symbols.
+ CVARS class variable names, a list of interned symbols.
+ CVALS class variable values, a vector of values.
+ SUPERCLASS a pointer to the superclass.
+ IVARCNT the number of class instance variables, a fixnum.
+ IVARTOTAL the total number of instance variables, a fixnum.
+</pre>
+
+<p>IVARCNT is the count of the number of instance variables defined by our
+class. IVARTOTAL is the total number of instance variables in an object of this
+class -- IVARCNT for this class plus the IVARCNTs from all of our
+superclasses.</p>
+
+<table cellpadding="0"><tbody><tr><td> </td><td bgcolor="eeeeee">
+ <a href="xlisp-internals.html#SEC00">Back to Top</a></nobr></li>
+</tr></tbody></table>
+
+<h3><a name="SEC14">How is the class hierarchy laid out ?</a></h3>
+
+<p>The fundamental objects are the OBJECT and CLASS class objects. (Both are
+instances of class CLASS, and since CLASSes are a particular kind of OBJECT,
+both are also objects, with n_type==OBJECT. Bear with me!)</p>
+
+<p>OBJECT is the root of the class hierarchy: everything you can send a message
+to has OBJECT as its class or super*class. (Vectors, chars, integers and so
+forth stand outside the object hierarchy -- you can't send messages to them. I'm
+not sure why Dave did it this way.) OBJECT defines the messages:</p>
+
+<pre>
+ :isnew -- Does nothing but return the object.
+ :class -- Returns contents of class-pointer slot.
+ :show -- Prints names of obj, obj->class and instance vars.
+</pre>
+
+<p>Since a CLASS is a specialized type of OBJECT (with instance variables like
+MESSAGES which generic OBJECTs lack), class CLASS has class OBJECT as its
+superclass. The CLASS object defines the messages:</p>
+
+<pre>
+ :new -- Create new object with self.IVARTOTAL LVAR slots, plus
+ one for the class pointer. Point class slot to self.
+ Set new.n_type char to OBJECT.
+ :isnew -- Fill in IVARS, CVARS, CVALS, SUPERCLASS, IVARCNT and
+ IVARTOTAL, using parameters from :new call. (The
+ :isnew msg inherits the :new msg parameters because
+ the :isnew msg is generated automatically after
+ each :new msg, courtesy of a special hack in
+ xlobj.c:sendmsg().)
+ :answer -- Add a (msg closure) pair to self.MESSAGES.
+</pre>
+
+<p>Here's a figure to summarize the above, with a generic object thrown in for
+good measure. Note that all instances of CLASS will have a SUPERCLASS pointer,
+but no normal object will. Note also that the messages known to an object are
+those which can be reached by following exactly one Class Ptr and then zero or
+more Superclass Ptrs. For example, the generic object can respond to :ISNEW,
+:CLASS and :SHOW, but not to :NEW or :ANSWER. (The functions implementing the
+given messages are shown in parentheses.)</p>
+
+<pre>
+ NIL
+ ^
+ |
+ |Superclass Ptr
+ |
+ Msg+--------+
+ :isnew (xlobj.c:obisnew) <----| class |Class Ptr
+ :class (xlobj.c:obclass) <----| OBJECT |------------------------------>+
+ :show (xlobj.c:objshow) <----| | |
+ +--------+ |
+ ^ ^ ^ |
+ +---------+ | | | |
+ | generic |Class Ptr | | +<---------------+ |
+ | object |-------------->+ |Superclass Ptr ^Superclass Ptr |
+ +---------+ | | |
+ Msg+--------+ +---------+ |
+ :isnew (xlobj.c:clnew) <----| class |Class Ptr | generic |Class Ptr |
+ :new (xlobj.c:clisnew) <----| CLASS |------->+ | CLASS |------->+ |
+ :answer(xlobj.c:clanswer)<----| | | | | | |
+ +--------+ | +---------+ | |
+ ^ ^ | | |
+ | | v v |
+ | +-----------+ <------------------+ v
+ +<------------------------------------+
+</pre>
+
+<p>Thus, class CLASS inherits the :CLASS and :SHOW messages from class OBJECT,
+overrides the default :ISNEW message, and provides new messages :NEW and
+:ANSWER.</p>
+
+<p>New classes are created by (send CLASS :NEW ...) messages. Their Class Ptr
+will point to CLASS. By default, they will have OBJECT as their superclass, but
+this can be overridden by the second optional argument to :NEW.</p>
+
+<p>The above basic structure is set up by xlobj.c:xloinit().</p>
+
+<table cellpadding="0"><tbody><tr><td> </td><td bgcolor="eeeeee">
+ <a href="xlisp-internals.html#SEC00">Back to Top</a></nobr></li>
+</tr></tbody></table>
+
+<h3><a name="SEC15">How do we look up the value of a variable ?</a></h3>
+
+<p>When we're cruising along evaluating an expression and encounter a symbol,
+the symbol might refer to a global variable, an instance variable, or a class
+variable in any of our superclasses. Figuring out which means digging through
+the environment. The canonical place this happens is in xleval.c:xleval(), which
+simply passes the buck to xlsym.c:xlgetvalue(), which in turn passes the buck to
+xlxsym.c:xlxgetvalue(), where the fun of scanning down xlenv begins. The xlenv
+environment looks something like</p>
+
+<pre>
+ Backbone Environment frame contents
+ -------- --------------------------
+ xlenv --> frame ((sym val) (sym val) (sym val) ... )
+ frame ...
+ object (obj msg-class)
+ frame ...
+ object ...
+ frame ...
+ ...
+</pre>
+
+<p>The "frame" lines are due to everyday nested constructs like LET expressions,
+while the "object" lines represent an object environment entered via a message
+send. xlxgetvalue scans the enviroment left to right, and then top to bottom. It
+scans down the regular environment frames itself, and calls
+xlobj.c:xlobjgetvalue() to search the object environment frames.</p>
+
+<p>xlobjgetvalue() first searches for the symbol in the msg-class, then in all
+the successive superclasses of msg-class. In each class, it first checks the
+list of instance-variable names in the IVARS slot, then the list of
+class-variables name in the CVARS slot.</p>
+
+<table cellpadding="0"><tbody><tr><td> </td><td bgcolor="eeeeee">
+ <a href="xlisp-internals.html#SEC00">Back to Top</a></nobr></li>
+</tr></tbody></table>
+
+<h3><a name="SEC16">How are function calls implemented ?</a></h3>
+
+<p>xleval.c contains the central expression-evaluation code. xleval.c:xleval()
+is the standard top-level entrypoint. The two central functions are
+xleval.c:xlevform() and xleval.c:evfun(). xlevform() can evaluate four kinds of
+expression nodes:</p>
+
+<p><b>SUBR:</b> A normal primitive fn coded in C. We call evpushargs() to
+evaluate and push the arguments, then call the primitive.</p>
+
+<p><b>FSUBR:</b> A special primitive fn coded in C, which (like IF) wants its
+arguments unevaluated. We call pushargs() (instead of evpushargs()) and then the
+C fn.</p>
+
+<p><b>CLOSURE:</b> A preprocessed written-in-lisp fn from a DEFUN or LAMBDA. We
+call evpushargs() and then evfun().</p>
+
+<p><b>CONS:</b> We issue an error if CONS.car isn't a LAMBDA, otherwise we call
+xleval.c:xlclose() to build a CLOSURE from the LAMBDA, and fall into the CLOSURE
+code.</p>
+
+<p>The common thread in all the above cases is that we call evpushargs() or
+pushargs() to push all the arguments on the evaluation stack, leaving the number
+and location of the arguments in the global variables xlargc and xlargv. The
+primitive C functions consume their arguments directly from the argument
+stack.</p>
+
+<p>xleval.c:evfun() evaluates a CLOSURE by:</p>
+
+<p>(1) Switching xlenv and xlfenv to the values they had when the CLOSURE was
+built. (These values are recorded in the CLOSURE.)</p>
+
+<p>(2) Binding the arguments to the environment. This involves scanning through
+the section of the argument stack indicated by xlargc/xlargv, using information
+from the CLOSURE to resolve keyword arguments correctly and assign appropriate
+default values to optional arguments, among other things.</p>
+
+<p>(3) Evaluating the body of the function via xleval.c:xleval().</p>
+
+<p>(4) Cleaning up and restoring the original environment.</p>
+
+<table cellpadding="0"><tbody><tr><td> </td><td bgcolor="eeeeee">
+ <a href="xlisp-internals.html#SEC00">Back to Top</a></nobr></li>
+</tr></tbody></table>
+
+<h3><a name="SEC17">How are message-sends implemented ?</a></h3>
+
+<p>We scan the MESSAGES list in the CLASS object of the recipient, looking for a
+(message-symbol method) pair that matches our message symbol. If necessary, we
+scan the MESSAGES lists of the recipient's superclasses too.
+(xlobj.c:sendmsg().) Once we find it, we basically do a normal function
+evaluation. (xlobjl.c:evmethod().)</p>
+
+<p>Two differences between message-send and normal function invocation:</p>
+
+<p>1) We need to replace the message-symbol by the recipient on the argument
+stack to make "self" available in the method closure.</p>
+
+<p>2) We need to push an 'object' stack entry on the xlenv environment to record
+which class is handling the message (so that, for example, SEND-SUPER can find
+our superclass).</p>
+
+<table cellpadding="0"><tbody><tr><td> </td><td bgcolor="eeeeee">
+ <a href="xlisp-internals.html#SEC00">Back to Top</a></nobr></li>
+</tr></tbody></table>
+
+<h3><a name="SEC18">How is garbage collection implemented ?</a></h3>
+
+<p>The dynamic memory pool managed by xlisp consists of a chain of memory
+segments (xldmem.h:struct segment) rooted at global C variable "segs". Each
+segment contains an array of "struct node"s plus a pointer to the next segment.
+Each node contains a n_type field and a MARK bit, which is zero except during
+garbage collection.</p>
+
+<p>Xlisp uses a simple, classical mark-and-sweep garbage collector. When it runs
+out of memory (fnodes==NIL), it does a recursive traversal setting the MARK flag
+on all nodes reachable from the obarray, the three environments
+xlenv/xlfenv/xldenv, and the evaluation and argument stacks. (A "switch" on the
+n_type field tells us how to find all the LVAL slots in the node (plus
+associated storage), and a pointer-reversal trick lets us avoid using too much
+stack space during the traversal.) sweep() then adds all un-MARKed LVALs to
+fnodes, and clears the MARK bit on the remaining nodes. If this fails to produce
+enough free nodes, a new segment is malloc()ed.</p>
+
+<p>The code to do this stuff is mostly in xldmem.c.</p>
+
+<table cellpadding="0"><tbody><tr><td> </td><td bgcolor="eeeeee">
+ <a href="xlisp-internals.html#SEC00">Back to Top</a></nobr></li>
+</tr></tbody></table>
+
+<h3><a name="SEC19">How are the source files laid out ?</a></h3>
+
+<p>To really understand the source, of course, you simply have to sit down and
+read it. There's no royal road to hacking! So this is a map of the source, not a
+picture of it.</p>
+
+<p>The core portable xlisp files have the prefix 'xl' (for 'xlisp').</p>
+
+<p>The best place to start reading the code is in the two main header files,
+xlisp.h and xldmem.h.</p>
+
+<p>The xldmem.h file ('dmem' for 'dynamic memory') defines the actual structure
+in memory of all the primitive xlisp data types. This is the file you will most
+likely refer to most often.</p>
+
+<p>The xlisp.h file defines essentially all global constants and macros which
+don't need to know about the structures in xldmem.h, mainly manifest constants
+sizing various arrays for different machines, and macros to test for the type of
+a list object and to help parse xlisp argument lists.</p>
+
+<p>The central code files to understand are xlmain.c, xleval.c, xlbfun.c, and
+xlsym.c.</p>
+
+<p><b>xlmain.c</b> contains both main() and the central read-eval-print loop, so
+it is the place from which to begin tracing flow of control.</p>
+
+<p><b>xleval.c</b> (with some support from xlbfun.) contains the heart of xlisp,
+the code to evaluate functions and macros.</p>
+
+<p><b>xlsym.c</b> contains the code to find the value of a symbol.</p>
+
+<p>Once you understand the above three, you know where xlisp decides to evaluate
+an s-expression, how it evaluates it, and how it finds the values needed by the
+expression.</p>
+
+<p>A good file to tackle next is xlobj.c, which handles much of the
+object-oriented support, and has much of the flavor of xleval.c.</p>
+
+<p>Most of the other files are just libraries of functions to handle particular
+types of processing, and are easily understood once the central code is
+grokked.</p>
+
+<p>One of the charms of xlisp *is* that it is small enough to easily read and
+comprehend. I hope it stays that way!</p>
+
+<p>Here's a very brief file-by-file overview of the source. Your files will
+probably be laid out just a little differently. In particular, if you're not
+running on unix, instead of 'unixstuff.c' you'll have something like
+'dosstuff.c'.</p>
+
+<pre>
+ Size Name Contains
+ ----- -------- --------
+ 2054 osdefs.h System specific declarations. Empty file in my case.
+ 2050 osptrs.h System specific pointers. Empty file in my case.
+ 14172 unixstuff.c Isolates I/O fns, which tend to be OS-specific. Unix version.
+ 19049 xlbfun.c 'Basic FUNctions': highlevel eval stuff + random support.
+ 30229 xlcont.c 'CONTrol': case, do, while, dotimes, other special forms.
+ 6380 xldbug.c 'DeBUG': break, abort, error, baktrace...
+ 18006 xldmem.c 'Dynamic MEMory': ram allocation, garbage collector.
+ 9431 xldmem.h Declaration of LVAL, scads of useful macros.
+ 21220 xleval.c 'EVALuation': eval, apply, macroexpand and support for them.
+ 11935 xlfio.c 'File I/O': OPEN, READ-CHAR, WRITE-CHAR ...
+ 18481 xlftab.c 'Function TABle': Array of all xlisp primitives.
+ 4866 xlglob.c 'GLOBal variables': Boring list of declarations.
+ 11048 xlimage.c 'memory IMAGE': Code to save/restore contents of xlisp.
+ 10579 xlinit.c 'INITialization': Start-of-the-world setup code.
+ 6016 xlio.c 'Input/Output': misc I/O stuff, some called by xlfio.c.
+ 12664 xlisp.h consp() ..., xlgetarg() ..., misc types.
+ 5853 xljump.c catch, throw, return ...
+ 20723 xllist.c car, cdr, append, map ... basic list manipulation.
+ 11975 xlmath.c Arithmetic functions -- addition, multiplication ...
+ 16425 xlobj.c Object support -- create objects & classes, send msgs...
+ 4134 xlpp.c A little prettyprinter.
+ 9487 xlprin.c Print an arbitrary lisp value in ascii.
+ 19535 xlread.c Read in an arbitrary ascii lisp expression.
+ 15062 xlstr.c Manipulation of characters and strings.
+ 12889 xlstruct.c Lisp structures -- defstruct and kin.
+ 5957 xlsubr.c eq, equal, some internal utility fns.
+ 7019 xlsym.c Symbols and obarrays ... maksym, getvalue, getprop...
+ 5566 xlsys.c Misc stuff -- read file, print backtrace, peek/poke...
+ 3926 xmain.c main(), with top read-eval-print loop.
+</pre>
+
+<table cellpadding="0"><tbody><tr><td> </td><td bgcolor="eeeeee">
+ <a href="xlisp-internals.html#SEC00">Back to Top</a></nobr></li>
+</tr></tbody></table>
+
+<h3><a name="SEC20">How do I add a new primitive fn to xlisp ?</a></h3>
+
+<p>A preliminary comment: You should have a copy of Guy L Steele's "Common Lisp:
+The Language" (2nd Edition), and make your new primitives compatible with the
+standard whenever practical.</p>
+
+<p>Add a line to the end of xlftab.c:funtab[]. This table contains a list of
+triples:</p>
+
+<p>The first element of each triple is the function name as it will appear to
+the programmer. Make it all upper case.</p>
+
+<p>The second element is S (for SUBR) if (like most fns) your function wants its
+arguments pre-evaluated, else F (for FSUBR).</p>
+
+<p>The third element is the name of the C function to call.</p>
+
+<p>Remember that your arguments arrive on the xlisp argument stack rather than
+via the usual C parameter mechanism.</p>
+
+<p>CAUTION: Try to keep your files separate from generic xlisp files, and to
+minimize the number of changes you make in the generic xlisp files. This way,
+you'll have an easier time re-installing your changes when new versions of xlisp
+come out. For example, if you are going to add many primitive functions to your
+xlisp, use an #include file rather than putting them all in xlftab.c. It's a
+good idea to put a marker (like a comment with your initials) on each line you
+change or insert in the generic xlisp fileset.</p>
+
+<p>CAUTION: Remember that you usually need to protect the LVAL variables in your
+function from the garbage-collector. It never hurts to do this, and often
+produces obscure bugs if you do not. You protect uninitialized local variables
+with xlsave1() and initialized local variables with xlprot1().</p>
+
+<p>BE CAREFUL NOT TO PROTECT UNINITIALIZED LOCAL VARIABLES WITH XLPROT1() OR
+XLPROTECT()! This will appear to work fine until garbage collection happens at
+an inconvenient moment, at which point the garbage collector will wind up
+following your uninitialized pointer off to never-never land.</p>
+
+<p>Note: If you have several pointers to protect, you can save a little runtime
+and codespace by using xlstkcheck(number-of-variables-to-protect) followed by
+xlsave()s and xlprotect()s instead of the more expensive xlsave1()s and
+xlprot1()s.</p>
+
+<p>Generic code for a new primitive fn:</p>
+
+<pre>
+ /* xlsamplefun - do useless stuff. */
+ /* Called like (samplefun '(a c b) 1 2.0) */
+ LVAL xlsamplefun()
+ {
+ /* Variables to hold the arguments: */
+ LVAL list_arg, integer_arg, float_arg;
+
+ /* Get the arguments, with appropriate errors */
+ /* if any are of the wrong type. Look in */
+ /* xlisp.h for macros to read other types of */
+ /* arguments. Look in xlmath.c for examples */
+ /* of functions which can handle an argument */
+ /* which may be either int or float: */
+ list_arg = xlgalist() ; /* "XLisp Get A LIST" */
+ integer_arg = xlgafixnum(); /* "XLisp Get A FIXNUM" */
+ float_arg = xlgaflonum(); /* "XLisp Get A FLONUM" */
+
+ /* Issue an error message if there are any extra arguments: */
+ xllastarg();
+
+ /* Call a separate C function to do the actual */
+ /* work. This way, the main function can */
+ /* be called from both xlisp code and C code. */
+ /* By convention, the name of the xlisp wrapper */
+ /* starts with "xl", and the native C function */
+ /* has the same name minus the "xl" prefix: */
+ return samplefun( list_arg, integer_arg, float_arg );
+ }
+ LVAL samplefun( list_arg, integer_arg, float_arg )
+ LVAL list_arg, integer_arg, float_arg;
+ {
+ FIXTYPE val_of_integer_arg;
+ FLOTYPE val_of_float_arg;
+
+ /* Variables which will point to LISP objects: */
+ LVAL result;
+ LVAL list_ptr;
+ LVAL float_ptr;
+ LVAL int_ptr;
+
+ /* Protect our internal pointers by */
+ /* pushing them on the evaluation */
+ /* stack so the garbage collector */
+ /* can't recycle them in the middle */
+ /* of the routine: */
+ xlstkcheck(4); /* Make sure following xlsave */
+ /* calls won't overrun stack. */
+ xlsave(list_ptr); /* Use xlsave1() if you don't */
+ xlsave(float_ptr);/* do an xlstkcheck(). */
+ xlsave(int_ptr);
+ xlsave(result);
+
+ /* Semantic check, illustrating use of xlfail(): */
+ if (list_ptr == NIL) {
+ xlfail("null list");
+ /* Won't return. */
+ }
+
+ /* Create an internal list structure, protected */
+ /* against garbage collection until we exit fn: */
+ list_ptr = cons(list_arg,list_arg);
+
+ /* Get the actual values of our fixnum and flonum: */
+ val_of_integer_arg = getfixnum( integer_arg );
+ val_of_float_arg = getflonum( float_arg );
+
+ /* Semantic check, illustrating use of xlerror(): */
+ if (val_of_integer_arg < -2) {
+ xlerror("bad integer",cvfixnum(val_of_integer_arg));
+ /* Won't return. */
+ }
+
+ /*******************************************/
+ /* You can have any amount of intermediate */
+ /* computations at this point in the fn... */
+ /*******************************************/
+
+ /* Make new numeric values to return: */
+ integer_ptr = cvfixnum( val_of_integer_arg * 3 );
+ float_ptr = cvflonum( val_of_float_arg * 3.0 );
+
+ /* Cons it all together to produce a return value: */
+ result = cons( float_ptr, NIL );
+ result = cons( integer_ptr, result );
+ result = cons( list_ptr, result );
+
+ /* Restore the stack, canceling the xlsave()s: */
+ xlpopn(4); /* Use xlpop() for a single argument.*/
+
+ return result;
+ }
+</pre>
+
+<p><b>Example of what NOT to do:</b></p>
+
+<p>Here's a function I wrote which does *NOT* correctly prevent the garbage
+collector from stealing its dynamically allocated cells:</p>
+
+<pre>
+ LVAL incorrect_Point_To_List( p )/*DON'T USE THIS CODE! */
+ geo_point* p;
+ /*-
+ Convert point to (x y z) list.
+ -*/
+ {
+ LVAL result;
+ xlsave1(result);
+ result = cons( /* THIS CODE IS BROKEN! */
+ cvflonum( p->x), /* THIS CODE IS BROKEN! */
+ cons( /* THIS CODE IS BROKEN! */
+ cvflonum( p->y), /* THIS CODE IS BROKEN! */
+ cons( /* THIS CODE IS BROKEN! */
+ cvflonum(p->z), /* THIS CODE IS BROKEN! */
+ NIL /* THIS CODE IS BROKEN! */
+ ) /* THIS CODE IS BROKEN! */
+ ) /* THIS CODE IS BROKEN! */
+ ); /* THIS CODE IS BROKEN! */
+ xlpop();
+ return result;
+ }
+</pre>
+
+<p>The problem with the above function is that the "z" cell will be allocated
+first, and is not protected during the allocation of the "y" flonum (or vice
+versa, depending on the order the compiler chooses to evaluate these arguments).
+Similarly, the "y" cell is not protected during allocation of the "x" flonum.
+Here is a correct version, in which "result" always protects the
+list-to-date:</p>
+
+<pre>
+ LVAL correct_Point_To_List( p )
+ geo_point* p;
+ /*-
+ Convert point to (x y z) list.
+ -*/
+ {
+ LVAL result;
+ xlsave1(result);
+ result = cons( cvflonum(p->z), NIL );
+ result = cons( cvflonum(p->y), result );
+ result = cons( cvflonum(p->x), result );
+ xlpop();
+ return result;
+ }
+</pre>
+
+<table cellpadding="0"><tbody><tr><td> </td><td bgcolor="eeeeee">
+ <a href="xlisp-internals.html#SEC00">Back to Top</a></nobr></li>
+</tr></tbody></table>
+
+<h3><a name="SEC21">Minor Observations:</a></h3>
+
+<p>xlapply, xlevform and sendmsg will issue an error if they encounter a s_macro
+CLOSURE. You are not allowed to use APPLY or FUNCALL with macros in Common Lisp.
+There is no way provided to declare macro methods, nor do they make much
+sense...</p>
+
+<p>Neither xlapply nor sendmsg will handle FSUBRs. Common Lisp does not allow
+APPLYing a special form (FSUBR), and since SEND is a SUBR, all of its arguments
+are already evaluated, so it is not possible to have FSUBR methods.</p>
+
+<p>Since xlisp tracks the three most recent input expressions (in variables +,
+++ and +++) and three most recent results (in variables *, ** and ***), things
+may occasionally not get garbage-collected as soon as you expect!</p>
+
+<p>Both xlobj.c:xloinit() and xlobj.c:obsymvols() initialize the "object" and
+"class" variables. This is neither redundant nor a bug:</p>
+
+<p>xloinit creates the classes class and object, as well as the symbols, but
+sets the C variables class and object to point to the class and object.</p>
+
+<p>obsymbols just sets the C variables by looking up the symbols. It is needed
+because when you restore a workspace you don't create new objects but still need
+to know where the existing objects are (they might be in a different location in
+the saved workspace). Notice that obsymbols is called by xlsymbols which is
+called both when initializing a new workspace and when restoring an old
+workspace.</p>
+
+<table cellpadding="0"><tbody><tr><td> </td><td bgcolor="eeeeee">
+ <a href="xlisp-internals.html#SEC00">Back to Top</a></nobr></li>
+</tr></tbody></table>
+
+<h3><a name="SEC22">Acknowledgements</a></h3>
+
+<p>This document is considerably improved thanks to careful reading and
+thoughtful suggestions from Ken Whedbee (kcw@beach.cis.ufl.edu) and (especially)
+Tom Almy (toma@sail.labs.tek.com).</p> </pre>
+
+<table cellpadding="0"><tbody><tr><td> </td><td bgcolor="eeeeee">
+ <a href="xlisp-internals.html#SEC00">Back to Top</a></nobr></li>
+</tr></tbody></table>
+
+<br><hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/manual/contents.htm b/docsrc/xlisp/xlisp-doc/manual/contents.htm new file mode 100644 index 0000000..d959433 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/manual/contents.htm @@ -0,0 +1,858 @@ +<html><head><title>Table of Contents</title></head> + +<body> + +<a href="../start.htm">Nyquist / XLISP 2.0</a> - +Contents | +<a href="../tutorials/tutorials.htm">Tutorials</a> | +<a href="../examples/examples.htm">Examples</a> | +<a href="../reference/reference-index.htm">Reference</a> + +<hr> + +<h1>Table of Contents</h1> + +<hr> + +<ol> +<li><nobr>Manuals</nobr></li> +<ul> +<li><nobr><a href="#xlisp-2-0-manual">XLISP 2.0 Manual</a> - by David Betz</nobr></li> +<li><nobr><a href="#xlisp-opbject-system">XLISP Object System</a> - by David Betz</nobr></li> +<li><nobr><a href="../reference/profile.htm">XLISP Profiling</a> - by Roger B. Dannenberg</nobr></li> +</ul> +<li><nobr>Reference</nobr></li> +<ul> +<li><nobr><a href="#symbols">Symbols</a></nobr></li> +<li><nobr>Functions</nobr></li> +<ul> +<li><nobr><a href="#evaluation-functions">Evaluation</a></nobr></li> +<li><nobr><a href="#symbol-functions">Symbol Functions</a></nobr></li> +<li><nobr><a href="#array-functions">Arrays</a></nobr></li> +<li><nobr><a href="#list-functions">Lists</a></nobr></li> +<li><nobr><a href="#predicate-functions">Predicates</a></nobr></li> +<li><nobr><a href="#control-constructs">Control Constructs</a></nobr></li> +<li><nobr><a href="#debugging-and-error-handling">Debugging and Error Handling</a></nobr></li> +<li><nobr><a href="#arithmetic-functions">Numbers</a></nobr></li> +<li><nobr><a href="#string-functions">Strings</a></nobr></li> +<li><nobr><a href="#character-functions">Characters</a></nobr></li> +<li><nobr><a href="#input-output-functions">Input/Output</a></nobr></li> +<li><nobr><a href="#file-io-functions">File I/O</a></nobr></li> +<li><nobr><a href="#string-stream-functions">String Streams</a></nobr></li> +<li><nobr><a href="#system-functions">System</a></nobr></li> +</ul> +</ul> +</ol> + +<a name="xlisp-2-0-manual"></a> + +<hr> + +<h2>XLISP 2.0 Manual</h2> + +<hr> + +<ul> +<li><nobr><a href="xlisp.htm">XLISP 2.0 Manual</a></nobr></li> +<ol> +<li><nobr><a name="1" href="xlisp.htm#introduction">Introduction</a></nobr></li> +<li><nobr><a name="2" href="xlisp.htm#a-note-from-the-author">A Note From The Author</a></nobr></li> +<li><nobr><a name="3" href="xlisp.htm#command-loop">Command Loop</a></nobr></li> +<li><nobr><a name="4" href="xlisp.htm#break-loop">Break Loop</a></nobr></li> +<li><nobr><a name="5" href="xlisp.htm#data-types">Data Types</a></nobr></li> +<li><nobr><a name="6" href="xlisp.htm#the-evaluator">The Evaluator</a></nobr></li> +<li><nobr><a name="7" href="xlisp.htm#lexical-conventions">Lexical Conventions</a></nobr></li> +<li><nobr><a name="8" href="xlisp.htm#the-readtable">Readtable</a></nobr></li> +<ul> +<li><nobr>Read Table Entries</nobr></li> +<ul> +<li><nobr><a href="xlisp.htm#constituent">:constituent</a> - indicating a symbol constituent</nobr></li> +<li><nobr><a href="xlisp.htm#white-space">:white-space</a> - indicating a whitespace character</nobr></li> +<li><nobr><a href="xlisp.htm#tmacro">:tmacro</a> - terminating readmacro</nobr></li> +<li><nobr><a href="xlisp.htm#nmacro">:nmacro</a> - terminating non-readmacro</nobr></li> +<li><nobr><a href="xlisp.htm#sescape">:sescape</a> - single escape character '\'</nobr></li> +<li><nobr><a href="xlisp.htm#mescape">:mescape</a> - multiple escape character '|'</nobr></li> +</ul> +<li><nobr>Read Macros</nobr></li> +<ul> +<li><nobr><a href="xlisp.htm#quote"> ' </a> - read macro for <a href="../reference/quote.htm">quote</a></nobr></li> +<li><nobr><a href="xlisp.htm#function"> #' </a> - read macro for <a href="../reference/function.htm">function</a></nobr></li> +<li><nobr><a href="xlisp.htm#array"> #() </a> - read macro for arrays</nobr></li> +<li><nobr><a href="xlisp.htm#hexadecimal"> #x </a> - read macro for hexadecimal numbers</nobr></li> +<li><nobr><a href="xlisp.htm#octal"> #o </a> - read macro for octal numbers</nobr></li> +<li><nobr><a href="xlisp.htm#binary"> #b </a> - read macro for binary numbers</nobr></li> +<li><nobr><a href="xlisp.htm#character"> #\ </a> - read macro for character values</nobr></li> +<li><nobr><a href="xlisp.htm#comment">#|...|#</a> - read macro for comments</nobr></li> +<li><nobr><a href="xlisp.htm#uninterned"> #: </a> - read macro for uninterned symbols</nobr></li> +<li><nobr><a href="xlisp.htm#backquote"> ` </a> - read macro for <a href="../reference/backquote.htm">backquote</a></nobr></li> +<li><nobr><a href="xlisp.htm#comma"> , </a> - read macro for <a href="../reference/backquote.htm">comma</a></nobr></li> +<li><nobr><a href="xlisp.htm#comma-at"> ,@ </a> - read macro for <a href="../reference/backquote.htm">comma-at</a></nobr></li> +</ul> +<li><nobr>Characters Names</nobr></li> +<ul> +<li><nobr><a href="xlisp.htm#tmacro">#\Tab</a> - a 'horizontal tab' character</nobr></li> +<li><nobr><a href="xlisp.htm#tmacro">#\Newline</a> - a 'newline' character</nobr></li> +<li><nobr><a href="xlisp.htm#tmacro">#\Space</a> - a 'space' character</nobr></li> +</ul> +</ul> +<li><nobr><a name="9" href="xlisp.htm#lambda-lists">Lambda Lists</a></nobr></li> +<ul> +<li><nobr><a href="xlisp.htm#arguments">Arguments</a></nobr></li> +<ul> +<li><nobr><a href="xlisp.htm#required-arguments">Required Arguments</a></nobr></li> +<li><nobr><a href="xlisp.htm#optional-arguments">Optional Arguments</a></nobr></li> +<li><nobr><a href="xlisp.htm#rest-argument">Rest Arguments</a></nobr></li> +<li><nobr><a href="xlisp.htm#keyword-arguments">Keyword Arguments</a></nobr></li> +<li><nobr><a href="xlisp.htm#auxiliary-variables">Auxiliary Variables</a></nobr></li> +</ul> +<li><nobr><a href="xlisp.htm#lambda-list-syntax">Lambda List Syntax</a></nobr></li> +</ul> +</ol> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="xlisp-opbject-system"></a> + +<hr> + +<h2>XLISP Object System</h2> + +<hr> + +<ul> +<li><nobr><a name="10" href="objects.htm">XLISP Object System</a></nobr></li> +<ul> +<li><nobr><a href="objects.htm#1">Definitions</a></nobr></li> +<ul> +<li><nobr><a href="objects.htm#selector-def">selector</a> - a symbol used to select an appropriate method</nobr></li> +<li><nobr><a href="objects.htm#message-def">message</a> - a selector and a list of actual arguments</nobr></li> +<li><nobr><a href="objects.htm#method-def">method</a> - the code that implements a message</nobr></li> +<li><nobr><a href="objects.htm#object-def">object</a> - the top of the class hierarchy</nobr></li> +<li><nobr><a href="objects.htm#class-def">class</a> - the class of all object classes</nobr></li> +</ul> +<li><nobr><a href="objects.htm#2">The 'send' Function</a></nobr></li> +<li><nobr><a href="objects.htm#3">The 'self' Symbol</a></nobr></li> +<li><nobr><a href="objects.htm#4">The 'send-super' Function</a></nobr></li> +<li><nobr><a href="objects.htm#5">The 'Object' Class</a></nobr></li> +<ul> +<li><nobr><a href="objects.htm#object">object</a> - the top of the class hierarchy</nobr></li> +<ul> +<li><nobr><a href="objects.htm#object-show">:show</a> - show an object's instance variables</nobr></li> +<li><nobr><a href="objects.htm#object-class">:class</a> - return the class of an object</nobr></li> +<li><nobr><a href="objects.htm#object-isnew">:isnew</a> - the default object initialization routine</nobr></li> +<li><nobr><a href="objects.htm#send-super">send-super</a> - send superclass a message</nobr></li> +</ul> +</ul> +<li><nobr><a href="objects.htm#6">The 'Class' Class</a></nobr></li> +<ul> +<li><nobr><a href="objects.htm#class">class</a> - class of all object classes</nobr></li> +<ul> +<li><nobr><a href="objects.htm#class-new">:new</a> - create a new instance of a class</nobr></li> +<li><nobr><a href="objects.htm#class-isnew">:isnew</a> - initialize a new class</nobr></li> +<li><nobr><a href="objects.htm#class-answer">:answer</a> - add a message to a class</nobr></li> +</ul> +</ul> +</ul> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="symbols"></a> + +<hr> + +<h2>Symbols</h2> + +<hr> + +<ul> +<li><nobr><a href="../reference/self.htm">self</a> - the current object within a method context</nobr></li> +<li><nobr><a href="../reference/global-obarray.htm">*obarray*</a> - the object hash table</nobr></li> +<li><nobr><a href="../reference/global-standard-input.htm">*standard-input*</a> - the standard input stream</nobr></li> +<li><nobr><a href="../reference/global-standard-output.htm">*standard-output*</a> - the standard output stream</nobr></li> +<li><nobr><a href="../reference/global-error-output.htm">*error-output*</a> - the error output stream</nobr></li> +<li><nobr><a href="../reference/global-trace-output.htm">*trace-output*</a> - the trace output stream</nobr></li> +<li><nobr><a href="../reference/global-debug-io.htm">*debug-io*</a> - the debug i/o stream</nobr></li> +<li><nobr><a href="../reference/global-breakenable.htm">*breakenable*</a> - flag controlling entering break loop on errors</nobr></li> +<li><nobr><a href="../reference/global-tracelist.htm">*tracelist*</a> - list of names of functions to trace</nobr></li> +<li><nobr><a href="../reference/global-tracenable.htm">*tracenable*</a> - enable trace back printout on errors</nobr></li> +<li><nobr><a href="../reference/global-tracelimit.htm">*tracelimit*</a> - number of levels of trace back information</nobr></li> +<li><nobr><a href="../reference/global-evalhook.htm">*evalhook*</a> - user substitute for the evaluator function</nobr></li> +<li><nobr><a href="../reference/global-applyhook.htm">*applyhook*</a> - [not yet implemented]</nobr></li> +<li><nobr><a href="../reference/global-readtable.htm">*readtable*</a> - the current readtable</nobr></li> +<li><nobr><a href="../reference/global-unbound.htm">*unbound*</a> - indicator for unbound symbols</nobr></li> +<li><nobr><a href="../reference/global-gc-flag.htm">*gc-flag*</a> - controls the printing of 'gc' messages</nobr></li> +<li><nobr><a href="../reference/global-gc-hook.htm">*gc-hook*</a> - function to call after garbage collection</nobr></li> +<li><nobr><a href="../reference/global-integer-format.htm">*integer-format*</a> - format for printing integers</nobr></li> +<li><nobr><a href="../reference/global-float-format.htm">*float-format*</a> - format for printing floats</nobr></li> +<li><nobr><a href="../reference/global-print-case.htm">*print-case*</a> - symbol output case</nobr></li> +<li><nobr><a href="../reference/global-file-separator.htm">*file-separator*</a> - the operating system's file sparator character</nobr></li> +</ul> + +<ul> +<li><nobr><a href="../manual/xlisp.htm#command-loop"> + </a> - the most recent input expression</nobr></li> +<li><nobr><a href="../manual/xlisp.htm#command-loop"> ++ </a> - the next to the last input expression</nobr></li> +<li><nobr><a href="../manual/xlisp.htm#command-loop"> +++ </a> - the second to the last input expression</nobr></li> +<li><nobr><a href="../manual/xlisp.htm#command-loop"> * </a> - the result of the previously evaluated expression</nobr></li> +<li><nobr><a href="../manual/xlisp.htm#command-loop"> ** </a> - the result of the next to the last evaluated expression</nobr></li> +<li><nobr><a href="../manual/xlisp.htm#command-loop"> *** </a> - the result of the second to the last evaluated expression</nobr></li> +<li><nobr><a href="../manual/xlisp.htm#command-loop"> - </a> - the expression currently being evaluated</nobr></li> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="evaluation-functions"></a> + +<hr> + +<h2>Evaluation Functions</h2> + +<hr> + +<ul> +<li><nobr><a href="../reference/eval.htm">eval</a> - evaluate an XLISP expression</nobr></li> +<li><nobr><a href="../reference/apply.htm">apply</a> - apply a function to a list of arguments</nobr></li> +<li><nobr><a href="../reference/funcall.htm">funcall</a> - call a function with arguments</nobr></li> +<li><nobr><a href="../reference/quote.htm">quote</a> - return an expression unevaluated</nobr></li> +<li><nobr><a href="../reference/function.htm">function</a> - get the functional interpretation</nobr></li> +<li><nobr><a href="../reference/backquote.htm">backquote</a> - fill in a template</nobr></li> +<li><nobr><a href="../reference/lambda.htm">lambda</a> - make a function closure</nobr></li> +<li><nobr><a href="../reference/get-lambda-expression.htm">get-lambda-expression</a> - get the lambda expression</nobr></li> +<li><nobr><a href="../reference/macroexpand.htm">macroexpand</a> - recursively expand macro calls</nobr></li> +<li><nobr><a href="../reference/macroexpand-1.htm">macroexpand-1</a> - expand a macro call</nobr></li> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="symbol-functions"></a> + +<hr> + +<h2>Symbol Functions</h2> + +<hr> + +<ul> +<li><nobr>Constructors</nobr></li> +<ul> +<li><nobr><a href="../reference/defun.htm">defun</a> - define a function</nobr></li> +<li><nobr><a href="../reference/defmacro.htm">defmacro</a> - define a macro</nobr></li> +<li><nobr><a href="../reference/gensym.htm">gensym</a> - generate a symbol</nobr></li> +<li><nobr><a href="../reference/intern.htm">intern</a> - make an interned symbol</nobr></li> +<li><nobr><a href="../reference/make-symbol.htm">make-symbol</a> - make an uninterned symbol</nobr></li> +</ul> +<li><nobr>Accessors</nobr></li> +<ul> +<li><nobr><a href="../reference/symbol-name.htm">symbol-name</a> - get the print name of a symbol</nobr></li> +<li><nobr><a href="../reference/symbol-value.htm">symbol-value</a> - get the value of a symbol</nobr></li> +<li><nobr><a href="../reference/symbol-function.htm">symbol-function</a> - get the functional value of a symbol</nobr></li> +<li><nobr><a href="../reference/symbol-plist.htm">symbol-plist</a> - get the property list of a symbol</nobr></li> +</ul> +<li><nobr>Assignment</nobr></li> +<ul> +<li><nobr><a href="../reference/set.htm">set</a> - set the value of a symbol</nobr></li> +<li><nobr><a href="../reference/setq.htm">setq</a> - set the [quoted] value of a symbol</nobr></li> +<li><nobr><a href="../reference/psetq.htm">psetq</a> - parallel version of setq</nobr></li> +<li><nobr><a href="../reference/setf.htm">setf</a> - set the value of a field</nobr></li> +</ul> +<li><nobr>Utilities</nobr></li> +<ul> +<li><nobr><a href="../reference/incf.htm">incf</a> - increment a variable</nobr></li> +<li><nobr><a href="../reference/decf.htm">decf</a> - decrement a variable</nobr></li> +</ul> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="array-functions"></a> + +<hr> + +<h2>Array Functions</h2> + +<hr> + +<ul> +<li><nobr>Constructors</nobr></li> +<ul> +<li><nobr><a href="../reference/make-array.htm">make-array</a> - make a new array</nobr></li> +<li><nobr><a href="../reference/vector.htm">vector</a> - make an initialized vector</nobr></li> +</ul> +<li><nobr>Acessors</nobr></li> +<ul> +<li><nobr><a href="../reference/aref.htm">aref</a> - get the nth element of an array</nobr></li> +</ul> +<li><nobr>Predicate</nobr></li> +<ul> +<li><nobr><a href="../reference/arrayp.htm">arrayp</a> - is this an array?</nobr></li> +</ul> +<li><nobr>Utilities</nobr></li> +<ul> +<li><nobr><a href="../reference/length.htm">length</a> - find the length of a list, vector or string</nobr></li> +<li><nobr><a href="../reference/hash.htm">hash</a> - compute the hash index for a symbol</nobr></li> +</ul> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="list-functions"></a> + +<hr> + +<h2>List Functions</h2> + +<hr> + +<ul> +<li><nobr>Constructors</nobr></li> +<ul> +<li><nobr><a href="../reference/cons.htm">cons</a> - construct a new list node</nobr></li> +<li><nobr><a href="../reference/list.htm">list</a> - create a list of values</nobr></li> +</ul> +<li><nobr>Accessors</nobr></li> +<ul> +<li><nobr><a href="../reference/car.htm">car</a> - return the car of a list node</nobr></li> +<li><nobr><a href="../reference/caar.htm">caar, cadr</a> - </nobr></li> +<li><nobr><a href="../reference/caaar.htm">caaar...caddr</a> - </nobr></li> +<li><nobr><a href="../reference/caaaar.htm">caaaar...cadddr</a> - </nobr></li> +<li><nobr><a href="../reference/cdr.htm">cdr</a> - return the cdr of a list node</nobr></li> +<li><nobr><a href="../reference/cddr.htm">cdar, cddr</a> - </nobr></li> +<li><nobr><a href="../reference/cdddr.htm">cdaar...cdddr</a> - </nobr></li> +<li><nobr><a href="../reference/cddddr.htm">cdaaar...cddddr</a> - </nobr></li> +<li><nobr><a href="../reference/first.htm">first</a> - get the first element of a list</nobr></li> +<li><nobr><a href="../reference/second.htm">second</a> - get the second element of a list</nobr></li> +<li><nobr><a href="../reference/third.htm">third</a> - get the third element of a list</nobr></li> +<li><nobr><a href="../reference/fourth.htm">fourth</a> - get the fourth element of a list</nobr></li> +<li><nobr><a href="../reference/rest.htm">rest</a> - get the rest of the list except the first element</nobr></li> +<li><nobr><a href="../reference/last.htm">last</a> - return the last list node of a list</nobr></li> +<li><nobr><a href="../reference/nth.htm">nth</a> - return the nth element of a list</nobr></li> +<li><nobr><a href="../reference/nthcdr.htm">nthcdr</a> - return the nth cdr of a list</nobr></li> +</ul> +<li><nobr>Predicates</nobr></li> +<ul> +<li><nobr><a href="../reference/consp.htm">consp</a> - is this a non-empty list?</nobr></li> +<li><nobr><a href="../reference/listp.htm">listp</a> - is this an empty or non-empty list?</nobr></li> +<li><nobr><a href="../reference/null.htm">null</a> - is this an empty list?</nobr></li> +</ul> +<li><nobr>List Functions</nobr></li> +<ul> +<li><nobr><a href="../reference/append.htm">append</a> - append lists</nobr></li> +<li><nobr><a href="../reference/reverse.htm">reverse</a> - reverse a list</nobr></li> +<li><nobr><a href="../reference/member.htm">member</a> - find an expression in a list</nobr></li> +<li><nobr><a href="../reference/length.htm">length</a> - find the length of a list, vector or string</nobr></li> +<li><nobr><a href="../reference/subst.htm">subst</a> - substitute expressions</nobr></li> +</ul> +<li><nobr>Association Lists</nobr></li> +<ul> +<li><nobr><a href="../reference/assoc.htm">assoc</a> - find an expression in an a-list</nobr></li> +<li><nobr><a href="../reference/sublis.htm">sublis</a> - substitute with an a-list</nobr></li> +</ul> +<li><nobr>Property Lists</nobr></li> +<ul> +<li><nobr><a href="../reference/get.htm">get</a> - get the value of a property</nobr></li> +<li><nobr><a href="../reference/putprop.htm">putprop</a> - put a property onto a property list</nobr></li> +<li><nobr><a href="../reference/remprop.htm">remprop</a> - remove a property from a property list</nobr></li> +</ul> +<li><nobr>Mapping</nobr></li> +<ul> +<li><nobr><a href="../reference/mapc.htm">mapc</a> - apply function to successive cars</nobr></li> +<li><nobr><a href="../reference/mapcar.htm">mapcar</a> - apply function to successive cars</nobr></li> +<li><nobr><a href="../reference/mapl.htm">mapl</a> - apply function to successive cdrs</nobr></li> +<li><nobr><a href="../reference/maplist.htm">maplist</a> - apply function to successive cdrs</nobr></li> +</ul> +<li><nobr>Lists as Stack</nobr></li> +<ul> +<li><nobr><a href="../reference/push.htm">push</a> - push a value to the front of a list</nobr></li> +<li><nobr><a href="../reference/pop.htm">pop</a> - pop a value from the front of a list</nobr></li> +</ul> +<li><nobr>Lists as Sets</nobr></li> +<ul> +<li><nobr><a href="../reference/union.htm">union</a> - compute the union of two lists</nobr></li> +<li><nobr><a href="../reference/intersection.htm">intersection</a> - compute the intersection of two lists</nobr></li> +<li><nobr><a href="../reference/set-difference.htm">set-difference</a> - compute the set-difference of two lists</nobr></li> +<li><nobr><a href="../reference/subsetp.htm">subsetp</a> - test if a list is a subset of another list</nobr></li> +</ul> +<li><nobr>Non-destructive List Functions</nobr></li> +<ul> +<li><nobr><a href="../reference/remove.htm">remove</a> - remove elements from a list</nobr></li> +<li><nobr><a href="../reference/remove-if.htm">remove-if</a> - remove elements that pass test</nobr></li> +<li><nobr><a href="../reference/remove-if-not.htm">remove-if-not</a> - remove elements that fail test</nobr></li> +</ul> +<li><nobr>Destructive List Functions</nobr></li> +<ul> +<li><nobr><a href="../reference/rplaca.htm">rplaca</a> - replace the car of a list node</nobr></li> +<li><nobr><a href="../reference/rplacd.htm">rplacd</a> - replace the cdr of a list node</nobr></li> +<li><nobr><a href="../reference/nconc.htm">nconc</a> - destructively concatenate lists</nobr></li> +<li><nobr><a href="../reference/delete.htm">delete</a> - delete elements from a list</nobr></li> +<li><nobr><a href="../reference/delete-if.htm">delete-if</a> - delete elements that pass test</nobr></li> +<li><nobr><a href="../reference/delete-if-not.htm">delete-if-not</a> - delete elements that fail test</nobr></li> +<li><nobr><a href="../reference/sort.htm">sort</a> - sort a list</nobr></li> +</ul> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="predicate-functions"></a> + +<hr> + +<h2>Predicate Functions</h2> + +<hr> + +<ul> +<li><nobr>Predicates</nobr></li> +<ul> +<li><nobr><a href="../reference/atom.htm">atom</a> - is this an atom?</nobr></li> +<li><nobr><a href="../reference/symbolp.htm">symbolp</a> - is this a symbol?</nobr></li> +<ul> +<li><nobr><a href="../reference/boundp.htm">boundp</a> - is a variable value bound to this symbol?</nobr></li> +<li><nobr><a href="../reference/fboundp.htm">fboundp</a> - is a function value bound to this symbol?</nobr></li> +</ul> +<li><nobr><a href="../reference/keywordp.htm">keywordp</a> - is this a keyword?</nobr></li> +<li><nobr><a href="../reference/numberp.htm">numberp</a> - is this a number?</nobr></li> +<ul> +<li><nobr><a href="../reference/plusp.htm">plusp</a> - is this number positive?</nobr></li> +<li><nobr><a href="../reference/minusp.htm">minusp</a> - is this number negative?</nobr></li> +<li><nobr><a href="../reference/zerop.htm">zerop</a> - is this number zero?</nobr></li> +<li><nobr><a href="../reference/integerp.htm">integerp</a> - is this number an integer?</nobr></li> +<ul> +<li><nobr><a href="../reference/evenp.htm">evenp</a> - is this integer even?</nobr></li> +<li><nobr><a href="../reference/oddp.htm">oddp</a> - is this integer odd?</nobr></li> +</ul> +<li><nobr><a href="../reference/floatp.htm">floatp</a> - is this number a float?</nobr></li> +</ul> +<li><nobr><a href="../reference/null.htm">null</a> - is this an empty list?</nobr></li> +<li><nobr><a href="../reference/consp.htm">consp</a> - is this a non-empty list?</nobr></li> +<li><nobr><a href="../reference/listp.htm">listp</a> - is this a list?</nobr></li> +<ul> +<li><nobr><a href="../reference/endp.htm">endp</a> - is this the end of a list?</nobr></li> +</ul> +<li><nobr><a href="../reference/stringp.htm">stringp</a> - is this a string?</nobr></li> +<li><nobr><a href="../reference/characterp.htm">characterp</a> - is this a character?</nobr></li> +<ul> +<li><nobr><a href="../reference/upper-case-p.htm">upper-case-p</a> - is this an upper case character?</nobr></li> +<li><nobr><a href="../reference/lower-case-p.htm">lower-case-p</a> - is this a lower case character?</nobr></li> +<li><nobr><a href="../reference/both-case-p.htm">both-case-p</a> - is this an alphabetic [either case] character?</nobr></li> +<li><nobr><a href="../reference/digit-char-p.htm">digit-char-p</a> - is this a digit character?</nobr></li> +<li><nobr><a href="../reference/alphanumericp.htm">alphanumericp</a> - is this an alphabetic or a digit character?</nobr></li> +</ul> +<li><nobr><a href="../reference/arrayp.htm">arrayp</a> - is this an array?</nobr></li> +<li><nobr><a href="../reference/streamp.htm">streamp</a> - is this a stream?</nobr></li> +<li><nobr><a href="../reference/filep.htm">filep</a> - is this a file?</nobr></li> +<li><nobr><a href="../reference/objectp.htm">objectp</a> - is this an object?</nobr></li> +<li><nobr><a href="../reference/soundp.htm">soundp</a> - is this a Nyquist sound?</nobr></li> +<li><nobr><a href="../reference/bigendianp.htm">bigendianp</a> - is this a bigendian machine?</nobr></li> +</ul> +<li><nobr>Comparison</nobr></li> +<ul> +<li><nobr><a href="../reference/eq.htm">eq</a> - are the expressions identical?</nobr></li> +<li><nobr><a href="../reference/eql.htm">eql</a> - are the expressions identical?</nobr></li> +<li><nobr><a href="../reference/equal.htm">equal</a> - are the expressions equal?</nobr></li> +</ul> +<li><nobr>Boolean</nobr></li> +<ul> +<li><nobr><a href="../reference/not.htm">not</a> - is this false?</nobr></li> +</ul> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="control-constructs"></a> + +<hr> + +<h2>Control Constructs</h2> + +<hr> + +<ul> +<li><nobr>Logical</nobr></li> +<ul> +<li><nobr><a href="../reference/and.htm">and</a> - the logical AND of a list of expressions</nobr></li> +<li><nobr><a href="../reference/or.htm">or</a> - the logical OR of a list of expressions</nobr></li> +</ul> +<li><nobr>Conditional</nobr></li> +<ul> +<li><nobr><a href="../reference/if.htm">if</a> - evaluate expressions conditionally</nobr></li> +<li><nobr><a href="../reference/when.htm">when</a> - evaluate only when a condition is true</nobr></li> +<li><nobr><a href="../reference/unless.htm">unless</a> - evaluate only when a condition is false</nobr></li> +<li><nobr><a href="../reference/cond.htm">cond</a> - evaluate conditionally</nobr></li> +<li><nobr><a href="../reference/case.htm">case</a> - select by case</nobr></li> +</ul> +<li><nobr>Binding</nobr></li> +<ul> +<li><nobr><a href="../reference/let.htm">let</a> - create local bindings</nobr></li> +<li><nobr><a href="../reference/let-star.htm">let*</a> - let with sequential binding</nobr></li> +<li><nobr><a href="../reference/flet.htm">flet</a> - create local functions</nobr></li> +<li><nobr><a href="../reference/labels.htm">labels</a> - flet with recursive functions</nobr></li> +<li><nobr><a href="../reference/macrolet.htm">macrolet</a> - create local macros</nobr></li> +</ul> +<li><nobr>Non-local Exits</nobr></li> +<ul> +<li><nobr><a href="../reference/catch.htm">catch, throw</a> - evaluate expressions and catch throws</nobr></li> +<li><nobr><a href="../reference/unwind-protect.htm">unwind-protect</a> - protect evaluation of an expression</nobr></li> +</ul> +<li><nobr>Looping Constructs</nobr></li> +<ul> +<li><nobr><a href="../reference/loop.htm">loop</a> - basic looping form</nobr></li> +<li><nobr><a href="../reference/do.htm">do</a> - loop while the termination test is NIL</nobr></li> +<li><nobr><a href="../reference/do-star.htm">do*</a> - 'do' loop with sequential binding</nobr></li> +<li><nobr><a href="../reference/dolist.htm">dolist</a> - loop through a list</nobr></li> +<li><nobr><a href="../reference/dotimes.htm">dotimes</a> - loop from zero to n-1</nobr></li> +<li><nobr><a href="../reference/while.htm">while</a> - standard 'while' loop</nobr></li> +</ul> +<li><nobr>The Program Feature</nobr></li> +<ul> +<li><nobr><a href="../reference/prog.htm">prog</a> - the program feature</nobr></li> +<li><nobr><a href="../reference/prog-star.htm">prog*</a> - 'prog' with sequential binding</nobr></li> +<li><nobr><a href="../reference/block.htm">block</a> - named block</nobr></li> +<li><nobr><a href="../reference/return.htm">return</a> - cause a prog construct to return a value</nobr></li> +<li><nobr><a href="../reference/return-from.htm">return-from</a> - return from a named block</nobr></li> +<li><nobr><a href="../reference/tagbody.htm">tagbody</a> - block with labels</nobr></li> +<li><nobr><a href="../reference/go.htm">go</a> - go to a tag within a tagbody or prog</nobr></li> +<li><nobr><a href="../reference/progv.htm">progv</a> - dynamically bind symbols</nobr></li> +<li><nobr><a href="../reference/prog1.htm">prog1</a> - return the value of the first expression</nobr></li> +<li><nobr><a href="../reference/prog2.htm">prog2</a> - return the value of the second expression</nobr></li> +<li><nobr><a href="../reference/progn.htm">progn</a> - return the value of the last expression</nobr></li> +</ul> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="debugging-and-error-handling"></a> + +<hr> + +<h2>Debugging and Error Handling</h2> + +<hr> + +<ul> +<li><nobr><a href="../reference/trace.htm">trace</a> - add a function to the trace list</nobr></li> +<li><nobr><a href="../reference/untrace.htm">untrace</a> - remove a function from the trace list</nobr></li> +<li><nobr><a href="../reference/error.htm">error</a> - signal a non-correctable error</nobr></li> +<li><nobr><a href="../reference/cerror.htm">cerror</a> - signal a correctable error</nobr></li> +<li><nobr><a href="../reference/break.htm">break</a> - enter a break loop</nobr></li> +<li><nobr><a href="../reference/clean-up.htm">clean-up</a> - clean-up after an error</nobr></li> +<li><nobr><a href="../reference/top-level.htm">top-level</a> - clean-up after an error and return to the top level</nobr></li> +<li><nobr><a href="../reference/continue.htm">continue</a> - continue from a correctable error</nobr></li> +<li><nobr><a href="../reference/errset.htm">errset</a> - trap errors</nobr></li> +<li><nobr><a href="../reference/baktrace.htm">baktrace</a> - print n levels of trace back information</nobr></li> +<li><nobr><a href="../reference/evalhook.htm">evalhook</a> - evaluate with hooks</nobr></li> +<li><nobr><a href="../reference/profile.htm">profile</a> - turn profiling on or off</nobr></li> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="arithmetic-functions"></a> + +<hr> + +<h2>Arithmetic Functions</h2> + +<hr> + +<ul> +<li><nobr>Integer and Floating Point - error if not a number</nobr></li> +<ul> +<li><nobr><a href="../reference/truncate.htm">truncate</a> - truncates a floating point number to an integer</nobr></li> +<li><nobr><a href="../reference/float.htm">float</a> - converts an integer to a floating point number</nobr></li> +<li><nobr><a href="../reference/addition.htm"> + </a> - add one or several numbers</nobr></li> +<li><nobr><a href="../reference/subtraction.htm"> − </a> - negate a single number or subtract one or several numbers</nobr></li> +<li><nobr><a href="../reference/multiplication.htm"> * </a> - multiply one or several numbers</nobr></li> +<li><nobr><a href="../reference/division.htm"> / </a> - get the reciprocal of a single number or divide several numbers</nobr></li> +<li><nobr><a href="../reference/increment.htm">1+</a> - increment a number by one</nobr></li> +<li><nobr><a href="../reference/decrement.htm">1−</a> - decrement a number by one</nobr></li> +<li><nobr><a href="../reference/min.htm">min</a> - the smallest of one or several numbers</nobr></li> +<li><nobr><a href="../reference/max.htm">max</a> - the largest of one or several numbers</nobr></li> +<li><nobr><a href="../reference/abs.htm">abs</a> - the absolute value of a number</nobr></li> +<li><nobr><a href="../reference/asin.htm">asin</a> - compute the arcsine of a number</nobr></li> +<li><nobr><a href="../reference/acos.htm">acos</a> - compute the arccosine of a number</nobr></li> +<li><nobr><a href="../reference/atan.htm">atan</a> - compute the arctangent of a number</nobr></li> +<li><nobr><a href="../reference/power.htm">power</a> - compute 'x' to the 'y' power</nobr></li> +<li><nobr><a href="../reference/interpolate.htm">interpolate</a> - compute the 'y' coordinate corresponding to 'x'</nobr></li> +</ul> +<li>Comparison - error if not a number</li> +<ul> +<li><nobr><a href="../reference/number-lessp.htm"> < </a> - test for less than</nobr></li> +<li><nobr><a href="../reference/number-not-greaterp.htm"> <= </a> - test for less than or equal to</nobr></li> +<li><nobr><a href="../reference/number-equal.htm"> = </a> - test for equal to</nobr></li> +<li><nobr><a href="../reference/number-not-equal.htm"> /= </a> - test for not equal to</nobr></li> +<li><nobr><a href="../reference/number-not-lessp.htm"> >= </a> - test for greater than or equal to</nobr></li> +<li><nobr><a href="../reference/number-greaterp.htm"> > </a> - test for greater than</nobr></li> +</ul> +<li><nobr>Floating Point - error if not a floating point number</nobr></li> +<ul> +<li><nobr><a href="../reference/sin.htm">sin</a> - compute the sine of a floating-point number</nobr></li> +<li><nobr><a href="../reference/cos.htm">cos</a> - compute the cosine of a floating-point number</nobr></li> +<li><nobr><a href="../reference/tan.htm">tan</a> - compute the tangent of a floating-point number</nobr></li> +<li><nobr><a href="../reference/expt.htm">expt</a> - compute x to the y power</nobr></li> +<li><nobr><a href="../reference/exp.htm">exp</a> - compute e to the x power</nobr></li> +<li><nobr><a href="../reference/log.htm">exp</a> - compute the natural logarithm of a floating-point number</nobr></li> +<li><nobr><a href="../reference/sqrt.htm">sqrt</a> - compute the square root of a floating-point number</nobr></li> +</ul> +<li><nobr>Integer - error if not an integer number</nobr></li> +<ul> +<li><nobr><a href="../reference/gcd.htm">gcd</a> - compute the greatest common divisor</nobr></li> +<li><nobr><a href="../reference/logand.htm">logand</a> - compute the bitwise 'and' of one or several numbers</nobr></li> +<li><nobr><a href="../reference/logior.htm">logior</a> - compute the bitwise 'inclusive or' of one or several numbers</nobr></li> +<li><nobr><a href="../reference/logxor.htm">logxor</a> - compute the bitwise 'exclusive or' of one or several numbers</nobr></li> +<li><nobr><a href="../reference/lognot.htm">lognot</a> - compute the bitwise 'not' of an number</nobr></li> +<li><nobr><a href="../reference/rem.htm">rem</a> - remainder of one or several integer numbers</nobr></li> +</ul> +<li><nobr>Random Numbers</nobr></li> +<ul> +<li><nobr><a href="../reference/random.htm">random</a> - compute an integer random number between 0 and n-1 inclusive</nobr></li> +<li><nobr><a href="../reference/rrandom.htm">rrandom</a> - compute a floating point random number between 0 and 1 inclusive</nobr></li> +<li><nobr><a href="../reference/real-random.htm">real-random</a> - compute a floating point random number in an arbitrary range</nobr></li> +</ul> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="string-functions"></a> + +<hr> + +<h2>String Functions</h2> + +<hr> + +<ul> +<li><nobr>String Functions</nobr></li> +<ul> +<li><nobr><a href="../reference/string.htm">string</a> - make a string from a character or an integer ASCII value</nobr></li> +<li><nobr><a href="../reference/strcat.htm">strcat</a> - concatenate strings</nobr></li> +<li><nobr><a href="../reference/subseq.htm">subseq</a> - extract a substring</nobr></li> +<li><nobr><a href="../reference/length.htm">length</a> - find the length of a list, vector or string</nobr></li> +<li><nobr><a href="../reference/string-search.htm">string-search</a> - search for a pattern in a string</nobr></li> +</ul> +<li><nobr>Trimming</nobr></li> +<ul> +<li><nobr><a href="../reference/string-trim.htm">string-trim</a> - trim both ends of a string</nobr></li> +<li><nobr><a href="../reference/string-left-trim.htm">string-left-trim</a> - trim the left end of a string</nobr></li> +<li><nobr><a href="../reference/string-right-trim.htm">string-right-trim</a> - trim the right end of a string</nobr></li> +</ul> +<li><nobr>Case Conversion</nobr></li> +<ul> +<li><nobr><a href="../reference/string-upcase.htm">string-upcase</a> - convert a string to uppercase</nobr></li> +<li><nobr><a href="../reference/string-downcase.htm">string-downcase</a> - convert a string to lowercase</nobr></li> +<li><nobr><a href="../reference/nstring-upcase.htm">nstring-upcase</a> - convert a part of a string to uppercase</nobr></li> +<li><nobr><a href="../reference/nstring-downcase.htm">nstring-downcase</a> - convert a part of a string to lowercase</nobr></li> +</ul> +<li><nobr>Case-sensitive Comparison</nobr></li> +<ul> +<li><nobr><a href="../reference/string-lessp-s.htm">string<</a> - test for less than in ASCII ordering</nobr></li> +<li><nobr><a href="../reference/string-not-greaterp-s.htm">string<=</a> - test for less than or equal to in ASCII ordering</nobr></li> +<li><nobr><a href="../reference/string-equal-s.htm">string=</a> - test for equal to in ASCII ordering</nobr></li> +<li><nobr><a href="../reference/string-not-equal-s.htm">string/=</a> - test for not equal to in ASCII ordering</nobr></li> +<li><nobr><a href="../reference/string-not-lessp-s.htm">string>=</a> - test for greater than or equal to in ASCII ordering</nobr></li> +<li><nobr><a href="../reference/string-greaterp-s.htm">string></a> - test for greater than in ASCII ordering</nobr></li> +</ul> +<li><nobr>Case-insensitive Comparison</nobr></li> +<ul> +<li><nobr><a href="../reference/string-lessp-i.htm">string-lessp</a> - is this less than in ASCII ordering?</nobr></li> +<li><nobr><a href="../reference/string-not-greaterp-i.htm">string-not-greaterp</a> - is this not greater than in ASCII ordering?</nobr></li> +<li><nobr><a href="../reference/string-equal-i.htm">string-equal</a> - is this equal in ASCII ordering?</nobr></li> +<li><nobr><a href="../reference/string-not-equal-i.htm">string-not-equal</a> - is this not equal in ASCII ordering?</nobr></li> +<li><nobr><a href="../reference/string-not-lessp-i.htm">string-not-lessp</a> - is this not less than in ASCII ordering?</nobr></li> +<li><nobr><a href="../reference/string-greaterp-i.htm">string-greaterp</a> - is this greater than in ASCII ordering?</nobr></li> +</ul> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="character-functions"></a> + +<hr> + +<h2>Character Functions</h2> + +<hr> + +<ul> +<li><nobr>Character Functions</nobr></li> +<ul> +<li><nobr><a href="../reference/char.htm">char</a> - extract a character from a string</nobr></li> +<li><nobr><a href="../reference/char-code.htm">char-code</a> - get the ASCII code of a character</nobr></li> +<li><nobr><a href="../reference/code-char.htm">code-char</a> - get the character with a specified ASCII code</nobr></li> +<li><nobr><a href="../reference/digit-char.htm">digit-char</a> - convert a digit weight to a digit</nobr></li> +<li><nobr><a href="../reference/char-int.htm">char-int</a> - convert a character to an integer</nobr></li> +<li><nobr><a href="../reference/int-char.htm">int-char</a> - convert an integer to a character</nobr></li> +</ul> +<li><nobr>General Predicate - all data types</nobr></li> +<ul> +<li><nobr><a href="../reference/characterp.htm">characterp</a> - is this a character?</nobr></li> +</ul> +<li><nobr>Character Predicates - error if not a character</nobr></li> +<ul> +<li><nobr><a href="../reference/upper-case-p.htm">upper-case-p</a> - is this an upper case character?</nobr></li> +<li><nobr><a href="../reference/lower-case-p.htm">lower-case-p</a> - is this a lower case character?</nobr></li> +<li><nobr><a href="../reference/both-case-p.htm">both-case-p</a> - is this an alphabetic [either case] character?</nobr></li> +<li><nobr><a href="../reference/digit-char-p.htm">digit-char-p</a> - is this a digit character?</nobr></li> +<li><nobr><a href="../reference/alphanumericp.htm">alphanumericp</a> - is this an alphabetic or a digit character?</nobr></li> +</ul> +<li><nobr>Case Conversion</nobr></li> +<ul> +<li><nobr><a href="../reference/char-upcase.htm">char-upcase</a> - convert a character to upper case</nobr></li> +<li><nobr><a href="../reference/char-downcase.htm">char-downcase</a> - convert a character to lower case</nobr></li> +</ul> +<li><nobr>Case-sensitive Comparison</nobr></li> +<ul> +<li><nobr><a href="../reference/char-lessp-s.htm">char<</a> - test for less than in ASCII ordering</nobr></li> +<li><nobr><a href="../reference/char-not-greaterp-s.htm">char<=</a> - test for less than or equal to in ASCII ordering</nobr></li> +<li><nobr><a href="../reference/char-equal-s.htm">char=</a> - test for equal to in ASCII ordering</nobr></li> +<li><nobr><a href="../reference/char-not-equal-s.htm">char/=</a> - test for not equal to in ASCII ordering</nobr></li> +<li><nobr><a href="../reference/char-not-lessp-s.htm">char>=</a> - test for greater than or equal to in ASCII ordering</nobr></li> +<li><nobr><a href="../reference/char-greaterp-s.htm">char></a> - test for greater than in ASCII ordering</nobr></li> +</ul> +<li><nobr>Case-insensitive Comparison</nobr></li> +<ul> +<li><nobr><a href="../reference/char-lessp-i.htm">char-lessp</a> - is this less than in ASCII ordering?</nobr></li> +<li><nobr><a href="../reference/char-not-greaterp-i.htm">char-not-greaterp</a> - is this not greater than in ASCII ordering?</nobr></li> +<li><nobr><a href="../reference/char-equal-i.htm">char-equal</a> - is this equal in ASCII ordering?</nobr></li> +<li><nobr><a href="../reference/char-not-equal-i.htm">char-not-equal</a> - is this not equal in ASCII ordering?</nobr></li> +<li><nobr><a href="../reference/char-not-lessp-i.htm">char-not-lessp</a> - is this not less than in ASCII ordering?</nobr></li> +<li><nobr><a href="../reference/char-greaterp-i.htm">char-greaterp</a> - is this greater than in ASCII ordering?</nobr></li> +</ul> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="input-output-functions"></a> + +<hr> + +<h2>Input/Output Functions</h2> + +<hr> + +<ul> +<li><nobr><a href="../reference/get-key.htm">get-key</a> - get a single key stroke from the keyboard</nobr></li> +<li><nobr><a href="../reference/read.htm">read</a> - read an expression</nobr></li> +<li><nobr><a href="../reference/print.htm">print</a> - print an expression on a new line</nobr></li> +<li><nobr><a href="../reference/prin1.htm">prin1</a> - print an expression</nobr></li> +<li><nobr><a href="../reference/princ.htm">princ</a> - print an expression without quoting</nobr></li> +<li><nobr><a href="../reference/pprint.htm">pprint</a> - pretty print an expression</nobr></li> +<li><nobr><a href="../reference/terpri.htm">terpri</a> - terminate the current print line</nobr></li> +<li><nobr><a href="../reference/flatsize.htm">flatsize</a> - length of printed representation using prin1</nobr></li> +<li><nobr><a href="../reference/flatc.htm">flatc</a> - length of printed representation using princ</nobr></li> +<li><nobr><a href="../reference/format.htm">format</a> - do formated output</nobr></li> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="file-io-functions"></a> + +<hr> + +<h2>File I/O Functions</h2> + +<hr> + +<ul> +<li><nobr>Character I/O</nobr></li> +<ul> +<li><nobr><a href="../reference/open.htm">open</a> - open a character file stream</nobr></li> +<li><nobr><a href="../reference/peek-char.htm">peek-char</a> - peek at the next character</nobr></li> +<li><nobr><a href="../reference/read-char.htm">read-char</a> - read a character from a stream</nobr></li> +<li><nobr><a href="../reference/read-line.htm">read-line</a> - read a line from a stream</nobr></li> +<li><nobr><a href="../reference/write-char.htm">write-char</a> - write a character to a stream</nobr></li> +</ul> +<li><nobr>Binary I/O</nobr></li> +<ul> +<li><nobr><a href="../reference/bigendianp.htm">bigendianp</a> - is this a bigendian machine?</nobr></li> +<li><nobr><a href="../reference/open-binary.htm">open-binary</a> - open a binary file stream</nobr></li> +<li><nobr>Bytes</nobr></li> +<ul> +<li><nobr><a href="../reference/read-byte.htm">read-byte</a> - read a byte from a stream</nobr></li> +<li><nobr><a href="../reference/write-byte.htm">write-byte</a> - write a byte to a stream</nobr></li> +</ul> +<li><nobr>Integer Numbers</nobr></li> +<ul> +<li><nobr><a href="../reference/read-int.htm">read-int</a> - read a binary integer number from a stream</nobr></li> +<li><nobr><a href="../reference/write-int.htm">write-int</a> - write a binary integer number to a stream</nobr></li> +</ul> +<li><nobr>Floating Point Numbers</nobr></li> +<ul> +<li><nobr><a href="../reference/read-float.htm">read-float</a> - read a binary floating point number from a stream</nobr></li> +<li><nobr><a href="../reference/write-float.htm">write-float</a> - write a binary floating point number to a stream</nobr></li> +</ul> +</ul> +<li><nobr>Character and Bibary I/O</nobr></li> +<ul> +<li><nobr><a href="../reference/close.htm">close</a> - close a file stream</nobr></li> +</ul> +<li><nobr>Operating System</nobr></li> +<ul> +<li><nobr><a href="../reference/setdir.htm">setdir</a> - set the current directory</nobr></li> +<li><nobr><a href="../reference/listdir.htm">listdir</a> - get a directory listing </nobr></li> +<li><nobr><a href="../reference/get-temp-path.htm">get-temp-path</a> - get a path where a temporary file can be created</nobr></li> +<li><nobr><a href="../reference/get-user.htm">get-user</a> - get the current user name</nobr></li> +<li><nobr><a href="../reference/find-in-xlisp-path.htm">find-in-xlisp-path</a> - search the XLISP path for a filename</nobr></li> +</ul> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="string-stream-functions"></a> + +<hr> + +<h2>String Stream Functions</h2> + +<hr> + +<ul> +<li><nobr><a href="../reference/make-string-input-stream.htm">make-string-input-stream</a> - create an unnamed stream from a string expression</nobr></li> +<li><nobr><a href="../reference/make-string-output-stream.htm">make-string-output-stream</a> - create and return an unnamed output stream</nobr></li> +<li><nobr><a href="../reference/get-output-stream-string.htm">get-output-stream-string</a> - empty a stream and return the data as a string</nobr></li> +<li><nobr><a href="../reference/get-output-stream-list.htm">get-output-stream-list</a> - empty a stream and return the data as a list</nobr></li> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="system-functions"></a> + +<hr> + +<h2>System Functions</h2> + +<hr> + +<ul> +<li><nobr><a href="../reference/load.htm">load</a> - load a source file</nobr></li> +<li><nobr><a href="../reference/save.htm">save</a> - save workspace to a file</nobr></li> +<li><nobr><a href="../reference/restore.htm">restore</a> - restore workspace from a file</nobr></li> +<li><nobr><a href="../reference/dribble.htm">dribble</a> - create a file with a transcript of a session</nobr></li> +<li><nobr><a href="../reference/gc.htm">gc</a> - force garbage collection</nobr></li> +<li><nobr><a href="../reference/expand.htm">expand</a> - expand memory by adding segments</nobr></li> +<li><nobr><a href="../reference/alloc.htm">alloc</a> - change number of nodes to allocate in each segment</nobr></li> +<li><nobr><a href="../reference/info.htm">info</a> - show information about memory usage</nobr></li> +<li><nobr><a href="../reference/room.htm">room</a> - show memory allocation statistics</nobr></li> +<li><nobr><a href="../reference/type-of.htm">type-of</a> - returns the type of the expression</nobr></li> +<li><nobr><a href="../reference/peek.htm">peek</a> - peek at a location in memory</nobr></li> +<li><nobr><a href="../reference/poke.htm">poke</a> - poke a value into memory</nobr></li> +<li><nobr><a href="../reference/bigendianp.htm">bigendianp</a> - is this a big-endian machine?</nobr></li> +<li><nobr><a href="../reference/address-of.htm">address-of</a> - get the address of an xlisp node</nobr></li> +<li><nobr><a href="../reference/get-env.htm">get-env</a> - get the value of an environment variable</nobr></li> +<li><nobr><a href="../reference/system.htm">system</a> - execute a command of the operating system</nobr></li> +<li><nobr><a href="../reference/quit.htm">quit</a> - exit XLISP</nobr></li> +<li><nobr><a href="../reference/exit.htm">exit</a> - exit XLISP</nobr></li> +<li><nobr><a href="../reference/setup-console.htm">setup-console</a> - set default console attributes</nobr></li> +<li><nobr><a href="../reference/echoenabled.htm">echoenabled</a> - turn console input echo on or off</nobr></li> +</ul> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<hr> + +<a href="../start.htm">Nyquist / XLISP 2.0</a> - +Contents | +<a href="../tutorials/tutorials.htm">Tutorials</a> | +<a href="../examples/examples.htm">Examples</a> | +<a href="../reference/reference-index.htm">Reference</a> + +</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/manual/links.htm b/docsrc/xlisp/xlisp-doc/manual/links.htm new file mode 100644 index 0000000..eff06d6 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/manual/links.htm @@ -0,0 +1,3 @@ +
+
+<a href="../reference/object.htm">object</a>
diff --git a/docsrc/xlisp/xlisp-doc/manual/manual.css b/docsrc/xlisp/xlisp-doc/manual/manual.css new file mode 100644 index 0000000..964dca2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/manual/manual.css @@ -0,0 +1,34 @@ +.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+
diff --git a/docsrc/xlisp/xlisp-doc/manual/objects.htm b/docsrc/xlisp/xlisp-doc/manual/objects.htm new file mode 100644 index 0000000..31c4fea --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/manual/objects.htm @@ -0,0 +1,358 @@ +<html><head><title>XLISP: An Object-oriented Lisp</title></head> + +<link rel="stylesheet" type="text/css" href="manual.css"> + +<body> + +<a href="../start.htm">Nyquist / XLISP 2.0</a> - +<a href="contents.htm">Contents</a> | +<a href="../tutorials/tutorials.htm">Tutorials</a> | +<a href="../examples/examples.htm">Examples</a> | +<a href="../reference/reference-index.htm">Reference</a> + +<hr> + +<h1>XLISP Object System</h1> + +<hr> + +<ol> +<li><nobr><a href="#1">Definitions</a></nobr></li> +<ul> +<li><nobr><a href="#define-selector">selector</a> - a symbol used to select an appropriate method</nobr></li> +<li><nobr><a href="#define-message">message</a> - a selector and a list of actual arguments</nobr></li> +<li><nobr><a href="#define-method">method</a> - the code that implements a message</nobr></li> +<li><nobr><a href="#define-object">object</a> - the top of the class hierarchy</nobr></li> +<li><nobr><a href="#define-class">class</a> - the class of all object classes</nobr></li> +</ul> +<li><nobr><a href="#2">The 'send' Function</a></nobr></li> +<li><nobr><a href="#3">The 'self' Symbol</a></nobr></li> +<li><nobr><a href="#4">The 'send-super' Function</a></nobr></li> +<li><nobr><a href="#5">The 'object' Class</a></nobr></li> +<ul> +<li><nobr><a href="#object">object</a> - the top of the class hierarchy</nobr></li> +<ul> +<li><nobr><a href="#object-show">:show</a> - show an object's instance variables</nobr></li> +<li><nobr><a href="#object-class">:class</a> - return the class of an object</nobr></li> +<li><nobr><a href="#object-isnew">:isnew</a> - the default object initialization routine</nobr></li> +<li><nobr><a href="#send-super">send-super</a> - send superclass a message</nobr></li> +</ul> +</ul> +<li><nobr><a href="#6">The 'class' Class</a></nobr></li> +<ul> +<li><nobr><a href="#class">class</a> - class of all object classes</nobr></li> +<ul> +<li><nobr><a href="#class-new">:new</a> - create a new instance of a class</nobr></li> +<li><nobr><a href="#class-isnew">:isnew</a> - initialize a new class</nobr></li> +<li><nobr><a href="#class-answer">:answer</a> - add a message to a class</nobr></li> +</ul> +</ul> +</ol> + +<a name="1"></a> +<a name="define-selector"></a> +<a name="define-message"></a> +<a name="define-method"></a> +<a name="define-object"></a> +<a name="define-class"></a> + +<hr> + +<h2>1 Definitions</h2> + +<hr> + +<p><div class="box"> + +<p><table cellpadding="0" cellspacing="0"><tbody> +<tr> + <td align="right"><nobr>selector</nobr></td> + <td valign="top"><nobr> — </nobr></td> + <td width="100%"><nobr>a symbol used to select an appropriate method, usually a keyword</nobr></td> +</tr> +<tr> + <td align="right"><nobr>message</nobr></td> + <td valign="top"><nobr> — </nobr></td> + <td width="100%"><nobr>a selector symbol and a list of actual arguments</nobr></td> +</tr> +<tr> + <td align="right"><nobr>method</nobr></td> + <td valign="top"><nobr> — </nobr></td> + <td width="100%"><nobr>the Lisp code that implements a message</nobr></td> +</tr> +<tr> + <td align="right"><nobr><a href="../reference/object.htm">object</a></nobr></td> + <td valign="top"><nobr> — </nobr></td> + <td width="100%"><nobr>the top of the class hierarchy</nobr></td> +</tr> +<tr> + <td align="right"><nobr><a href="../reference/class.htm">class</a></nobr></td> + <td valign="top"><nobr> — </nobr></td> + <td width="100%"><nobr>the class of all object classes [including itself]</nobr></td> +</tr> +</tbody></table></p> + +</div></p> + +<p>Since XLISP was created to provide a simple basis for experimenting with +<nobr>object-oriented</nobr> programming, one of the primitive data types +included is <a href="../reference/object.htm">object</a>. <nobr>In +XLISP</nobr>, an object consists of a data structure containing a pointer to +the object's <a href="../reference/class.htm">class</a> as well as an array +containing the values of the object's instance variables.</p> + +<p>Officially, there is no way to see inside an object [look at the values +of its instance variables]. The only way to communicate with an object is by +sending it a message.</p> + +<p><nobr> <a href="#top">Back to Top</a></nobr></p> + +<a name="2"></a> + +<hr> + +<h2>2 The 'send' Function</h2> + +<hr> + +<p>You can send a message to an object using the +<a href="../reference/send.htm">send</a> function:</p> + +<p><div class="box"> + +<dl> +<dt>(<b>send</b> <i>object selector</i> [<i>args</i>])</dt> +<dd><i>object</i> - an <a href="object.htm">object</a><br> +<i>selector</i> - message selector for <i>object</i><br> +<i>arg</i> - parameter sent to <i>object</i> method<br> +returns - the <i>object</i></dd> +</dl> + +</div></p> + +<p>The <a href="../reference/send.htm">send</a> function takes the object as +its first argument, the message selector as its second argument [which must +be a symbol] and the message arguments as its remaining arguments. <nobr>It +determines</nobr> the class of the receiving object and attempts to find a +method corresponding to the message selector in the set of messages defined +for that class. <nobr>If the</nobr> message is not found in the object's +class and the class has a <nobr>super-class</nobr>, the search continues by +looking at the messages defined for the <nobr>super-class</nobr>. This +process continues from one <nobr>super-class</nobr> to the next until a +method for the message is found. <nobr>If no</nobr> method is found, an +error occurs.</p> + +<p><nobr> <a href="#top">Back to Top</a></nobr></p> + +<a name="3"></a> + +<hr> + +<h2>3 The 'self' Symbol</h2> + +<hr> + +<p>When a method is found, the evaluator binds the receiving object to the +symbol <a href="../reference/self.htm">self</a> and evaluates the method +using the remaining elements of the original list as arguments to the +method. These arguments are always evaluated prior to being bound to their +corresponding formal arguments. The result of evaluating the method becomes +the result of the expression.</p> + +<p>Within the body of a method, a message can be sent to the current object +by calling:</p> + +<pre class="example"> +(send self ... ) +</pre> + +<p>The method lookup starts with the object's class regardless of the class +containing the current method.</p> + +<p><nobr> <a href="#top">Back to Top</a></nobr></p> + +<a name="4"></a> + +<hr> + +<h2>4 The 'send-super' Function</h2> + +<hr> + +<p>Sometimes it is desirable to invoke a general method in a superclass even +when it is overridden by a more specific method in a subclass. This can be +accomplished by calling <a +href="../reference/send-super.htm">send-super</a>, which begins the +method lookup in the superclass of the class defining the current method +rather than in the class of the current object:</p> + +<p><div class="box"> + +<dl> +<dt>(<b>send-super</b> <i>selector</i> [<i>args</i>])</dt> +<dd><i>selector</i> - the message selector<br> +<i>args</i> - the optional message arguments<br> +returns - the result of sending the message</dd> +</dl> + +</div></p> + +<p>The <a href="../reference/send-super.htm">send-super</a> function +takes a selector as its first argument [which must be a symbol] and the +message arguments as its remaining arguments. Notice that <a +href="../reference/send-super.htm">send-super</a> can only be sent from +within a method, and the target of the message is always the current object +<a href="../reference/self.htm">self</a>.</p> + +<pre class="example"> +(send-super ... ) +</pre> + +<p>is similar to:</p> + +<pre class="example"> +(send self ... ) +</pre> + +<p>except that method lookup begins in the superclass of the class +containing the current method rather than the class of the current +object.</p> + +<p><nobr> <a href="#top">Back to Top</a></nobr></p> + +<a name="5"></a> +<a name="object"></a> +<a name="object-show"></a> +<a name="object-class"></a> +<a name="object-isnew"></a> +<a name="send-super"></a> + +<hr> + +<h2>5 The 'object' Class</h2> + +<hr> + +<p><div class="box"> + +<p><a href="../reference/object.htm">object</a> - the top of the class hierarchy.</p> + +</div></p> + +<p>Messages:</p> + +<p><div class="box"> + +<dl> + +<dt>(<a href="../reference/send.htm">send</a> <i>object</i> <a href="../reference/keyword-show.htm">:show</a>) +- show an object's instance variables.</dt> +<dd>returns - the object</dd> + +<br> + +<dt>(<a href="../reference/send.htm">send</a> <i>object</i> <a href="../reference/keyword-class.htm">:class</a>) +- return the class of an object</dt> +<dd>returns - the class of the object</dd> + +<br> + +<dt>(<a href="../reference/send.htm">send</a> <i>object</i> <a href="../reference/keyword-isnew.htm">:isnew</a> <i>args</i>) +- run the default object initialization routine</dt> +<dd>returns - the object</dd> + +<br> + +<dt>(<a href="../reference/send.htm">send</a> <i>object</i> <a href="../reference/keyword-isa.htm">:isa</a> <i>class</i>) +- test if <i>object</i> inherits from <i>class</i></dt> +<dd>returns - <a href="../reference/t.htm"> T </a> if object +is an instance of class or a subclass of class, otherwise +<a href="../reference/nil.htm">NIL</a></dd> + +</dl> + +</div></p> + +<p><nobr> <a href="#top">Back to Top</a></nobr></p> + +<a name="6"></a> +<a name="class"></a> +<a name="class-new"></a> +<a name="class-isnew"></a> +<a name="class-answer"></a> + +<hr> + +<h2>6 The 'class' Class</h2> + +<hr> + +<p><div class="box"> + +<p><a href="../reference/class.htm">class</a> + - class of all object classes (including itself)</p> + +</div></p> + +<p>Messages:</p> + +<p><div class="box"> + +<dl> + +<dt>(<a href="../reference/send.htm">send</a> <i>class</i> <a href="../reference/keyword-new.htm">:new</a> <i>ivars</i> [<i>cvars</i> [<i>super</i>]]) + - create a new instance of a class</dt> +<dd>returns - the new class object</dd> + +<br> + +<dt>(<a href="../reference/send.htm">send</a> <i>class</i> <a href="../reference/keyword-isnew.htm">:isnew</a> <i>ivars</i> [<i>cvars</i> [<i>super</i>]]) + - initialize a new class</dt> +<dd><i>ivars</i> - list of instance variable symbols<br> +<i>cvars</i> - list of class variable symbols<br> +<i>super</i> - the superclass, default is <a href="../reference/object.htm">object</a><br> +returns - the new class object</dd> + +<br> + +<dt>(<a href="../reference/send.htm">send</a> <i>class</i> <a href="../reference/keyword-answer.htm">:answer</a> <i>selector</i> <i>fargs</i> <i>body</i>) + - add a message to a class</dt> +<dd><i>selector</i> - a message selector symbol<br> +<i>fargs</i> - the formal argument list, a lambda list<br> +<i>body</i> - a list of executable expressions<br> +returns - the object</dd> + +</dl> + +</div></p> + +<p>When a new instance of a +<a href="../reference/class.htm">class</a> is created by sending +the message <a href="../reference/keyword-new.htm">:new</a> +to an existing <a href="../reference/class.htm">class</a>, the +message <a href="../reference/keyword-isnew.htm">:isnew</a> followed by +whatever parameters were passed to the +<a href="../reference/keyword-new.htm">:new</a> message is sent to the +newly created <a href="../reference/object.htm">object</a>.</p> + +<p>When a new <a href="../reference/class.htm">class</a> is created +by sending the <a href="../reference/keyword-new.htm">:new</a> message to +the object <a href="../reference/class.htm">class</a>, an optional +parameter may be specified indicating the superclass of the new +<a href="../reference/class.htm">class</a>. If this parameter is +omitted, the new <a href="../reference/class.htm">class</a> will be +a subclass of <a href="../reference/object.htm">object</a>. A +<a href="../reference/class.htm">class</a> inherits all instance +variables, class variables, and methods from its superclass.</p> + +<p><nobr> <a href="#top">Back to Top</a></nobr></p> + +<hr> + +<a href="../start.htm">Nyquist / XLISP 2.0</a> - +<a href="contents.htm">Contents</a> | +<a href="../tutorials/tutorials.htm">Tutorials</a> | +<a href="../examples/examples.htm">Examples</a> | +<a href="../reference/reference-index.htm">Reference</a> + +</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/manual/part15.html b/docsrc/xlisp/xlisp-doc/manual/part15.html new file mode 100755 index 0000000..23a808d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/manual/part15.html @@ -0,0 +1,2131 @@ +<html><head><title>Appendix 3: XLISP: An Object-oriented Lisp</title></head>
+<a name = "100"><h2>Appendix 3: XLISP: An Object-oriented Lisp</h2></a>
+
+<blockquote><b>Version 2.0</b>
+<p>
+February 6, 1988
+<p>
+by<br>
+
+<b>David Michael Betz</b><br>
+
+127 Taylor Road<br>
+
+Peterborough, NH 03458
+<p>
+(603) 924-6936 (home)
+<p>
+Copyright (c) 1988, by David Michael Betz<br>
+
+All Rights Reserved<br>
+
+Permission is granted for unrestricted non-commercial use<br>
+
+</blockquote>
+
+
+<a name = "101"><h3>Introduction</h3></a>
+<p>
+ XLISP is an experimental programming language combining some of
+ the features of Common Lisp with an object-oriented extension
+ capability. It was implemented to allow experimentation with
+ object-oriented programming on small computers.
+<p>
+ There are currently implementations of XLISP running on the IBM-
+ PC and clones under MS-DOS, on the Macintosh, the Atari-ST and
+ the Amiga. It is completely written in the programming language
+ C and is easily extended with user written built-in functions
+ and classes. It is available in source form to non-commercial
+ users.
+<p>
+ Many Common Lisp functions are built into XLISP. In addition,
+ XLISP defines the objects Object and Class as primitives.
+ Object is the only class that has no superclass and hence is
+ the root of the class hierarchy tree. Class is the class of
+ which all classes are instances (it is the only object that is
+ an instance of itself).
+<p>
+ This document is a brief description of XLISP. It assumes some
+ knowledge of LISP and some understanding of the concepts of
+ object-oriented programming.
+<p>
+ I recommend the book <i>Lisp</i> by Winston and Horn and published by
+ Addison Wesley for learning Lisp. The first edition of this
+ book is based on MacLisp and the second edition is based on
+ Common Lisp. XLISP will continue to migrate towards
+ compatibility with Common Lisp.
+<p>
+ You will probably also need a copy of <i>Common Lisp: The
+ Language</i> by Guy L. Steele, Jr., published by Digital Press to
+ use as a reference for some of the Common Lisp functions that
+ are described only briefly in this document.
+<p>
+ <a name = "102"><h3>A Note From The Author</h3></a> If you have any problems with XLISP, feel free to contact me [me being David Betz - RBD] for
+ help or advice. Please remember that since XLISP is available
+ in source form in a high level language, many users [e.g. that Dannenberg fellow - RBD] have been
+ making versions available on a variety of machines. If you call
+ to report a problem with a specific version, I may not be able
+ to help you if that version runs on a machine to which I don't
+ have access. Please have the version number of the version that
+ you are running readily accessible before calling me.
+<p>
+ If you find a bug in XLISP, first try to fix the bug yourself
+ using the source code provided. If you are successful in fixing
+ the bug, send the bug report along with the fix to me. If you
+ don't have access to a C compiler or are unable to fix a bug,
+ please send the bug report to me and I'll try to fix it.
+<p>
+ Any suggestions for improvements will be welcomed. Feel free to
+ extend the language in whatever way suits your needs. However,
+ PLEASE DO NOT RELEASE ENHANCED VERSIONS WITHOUT CHECKING WITH ME
+ FIRST!! I would like to be the clearing house for new features
+ added to XLISP. If you want to add features for your own
+ personal use, go ahead. But, if you want to distribute your
+ enhanced version, contact me first. Please remember that the
+ goal of XLISP is to provide a language to learn and experiment
+ with LISP and object-oriented programming on small computers. I
+ don't want it to get so big that it requires megabytes of memory
+ to run.
+<p>
+ <a name = "103"><h3>XLISP Command Loop</h3></a><a name="index664"><a name="index665"> When XLISP is started, it first tries to load the workspace
+ <code>xlisp.wks</code> from the current directory. If that file doesn't
+ exist, XLISP builds an initial workspace, empty except for the
+ built-in functions and symbols.
+<p>
+ Then XLISP attempts to load <code>init.lsp</code> from the current
+ directory. It then loads any files named as parameters on the
+ command line (after appending <code>.lsp</code> to their names).
+<p>
+ XLISP then issues the following prompt:
+<pre>
+ >
+</pre>
+
+ This indicates that XLISP is waiting for an expression to be
+ typed.
+<p>
+ When a complete expression has been entered, XLISP attempts to
+ evaluate that expression. If the expression evaluates
+ successfully, XLISP prints the result and then returns to the
+ initial prompt waiting for another expression to be typed.
+<p>
+ <a name = "104"><h3>Break Command Loop</h3></a><a name="index666"> When XLISP encounters an error while evaluating an expression,
+ it attempts to handle the error in the following way:
+<p>
+ If the symbol <code>*breakenable*<a name="index667"></code> is true, the message corresponding
+ to the error is printed. If the error is correctable, the
+ correction message is printed.
+<p>
+ If the symbol <code>*tracenable*<a name="index668"></code> is true, a trace back is printed.
+ The number of entries printed depends on the value of the symbol
+ <code>*tracelimit*<a name="index669"></code>. If this symbol is set to something other than a
+ number, the entire trace back stack is printed.
+<p>
+ XLISP then enters a read/eval/print loop to allow the user to
+ examine the state of the interpreter in the context of the
+ error. This loop differs from the normal top-level
+ read/eval/print loop in that if the user invokes the function
+ <code>continue</code>, XLISP will continue from a correctable error. If
+ the user invokes the function <code>clean-up</code>, XLISP will abort the
+ break loop and return to the top level or the next lower
+ numbered break loop. When in a break loop, XLISP prefixes the
+ break level to the normal prompt.
+<p>
+ If the symbol <code>*breakenable*<a name="index670"></code> is <code>nil</code>, XLISP looks for a
+ surrounding errset function. If one is found, XLISP examines
+ the value of the print flag. If this flag is true, the error
+ message is printed. In any case, XLISP causes the errset
+ function call to return <code>nil</code>.
+<p>
+ If there is no surrounding errset function, XLISP prints the
+ error message and returns to the top level.
+<p>
+ <a name = "105"><h3>Data Types</h3></a><a name="index671"><a name="index672"> There are several different data types available to XLISP
+ programmers.
+<p>
+<ul>
+<li>
+lists
+<li>symbols
+<li>strings
+<li>integers
+<li>characters
+<li>floats
+<li>objects
+<li>arrays
+<li>streams
+<li>subrs (built-in functions)
+<li>fsubrs (special forms)
+<li>closures (user defined functions)
+</ul>
+<p>
+<a name = "106"><h3>The Evaluator</h3></a><a name="index673"><a name="index674"> The process of evaluation in XLISP:
+<ul>
+<li>
+ Strings, integers, characters, floats, objects, arrays, streams,
+ subrs, fsubrs and closures evaluate to themselves.
+<li> Symbols act as variables and are evaluated by retrieving the
+ value associated with their current binding.
+<li> Lists are evaluated by examining the first element of the list
+ and then taking one of the following actions:
+<ul>
+<li>
+ If it is a symbol, the functional binding of the symbol is
+ retrieved.
+<li> If it is a lambda expression, a closure is constructed for
+ the function described by the lambda expression.
+<li> If it is a subr, fsubr or closure, it stands for itself.
+<li> Any other value is an error.
+</ul>
+ Then, the value produced by the previous step is examined:
+<ul>
+<li>
+ If it is a subr or closure, the remaining list elements are
+ evaluated and the subr or closure is called with these
+ evaluated expressions as arguments.
+<li> If it is an fsubr, the fsubr is called using the remaining
+ list elements as arguments (unevaluated).
+<li> If it is a macro, the macro is expanded using the remaining
+ list elements as arguments (unevaluated). The macro
+ expansion is then evaluated in place of the original macro
+ call.
+</ul>
+</ul>
+<p>
+<a name = "107"><h3>Lexical Conventions</h3></a><a name="index675"><a name="index676"> The following conventions must be followed when entering XLISP
+ programs:
+<p>
+ Comments in XLISP code begin with a semi-colon character and
+ continue to the end of the line.
+<p>
+ Symbol names in XLISP can consist of any sequence of non-blank
+ printable characters except the following:
+<pre>
+ ( ) ' ` , " ;
+</pre>
+
+ Uppercase and lowercase characters are not distinguished within
+ symbol names. All lowercase characters are mapped to uppercase
+ on input.
+<p>
+ Integer literals consist of a sequence of digits optionally
+ beginning with a <code>+</code> or <code>-</code>. The range of values an integer can
+ represent is limited by the size of a C <code>long</code> on the machine on
+ which XLISP is running.
+<p>
+ Floating point literals consist of a sequence of digits
+ optionally beginning with a <code>+</code> or <code>-</code> and including an embedded
+ decimal point. The range of values a floating point number can
+ represent is limited by the size of a C <code>float</code> (<code>double</code> on
+ machines with 32 bit addresses) on the machine on which XLISP is
+ running.
+<p>
+ Literal strings are sequences of characters surrounded by double
+ quotes. Within quoted strings the ``<code>\</code>'' character is used to
+ allow non-printable characters to be included. The codes
+ recognized are:
+<ul>
+<li>
+<code>\\</code> means the character ``<code>\</code>''
+<li><code>\n</code> means newline
+<li><code>\t</code> means tab
+<li><code>\r</code> means return
+<li><code>\f</code> means form feed
+<li><code>\nnn</code> means the character whose octal code is nnn
+</ul>
+<p>
+<a name = "108"><h3>Readtables</h3></a><a name="index677"> The behavior of the reader is controlled by a data structure
+ called a <i>readtable</i>. The reader uses the symbol <code>*readtable*<a name="index678"></code> to
+ locate the current readtable. This table controls the
+ interpretation of input characters. It is an array with 128
+ entries, one for each of the ASCII character codes. Each entry
+ contains one of the following things:
+<ul>
+<li>
+ <code>NIL</code> - Indicating an invalid character
+<li> <code>:CONSTITUENT</code> - Indicating a symbol constituent
+<li> <code>:WHITE-SPACE</code> - Indicating a whitespace character
+<li> <code>(:TMACRO . <i>fun</i>)</code> - Terminating readmacro
+<li> <code>(:NMACRO . <i>fun</i>)</code> - Non-terminating readmacro
+<li> <code>:SESCAPE</code> - Single escape character ('\')
+<li> <code>:MESCAPE</code> - Multiple escape character ('|')
+</ul>
+<p>
+ In the case of <code>:TMACRO</code> and <code>:NMACRO</code>, the <i>fun</i> component is a
+ function. This can either be a built-in readmacro function or a
+ lambda expression. The function should take two parameters.
+ The first is the input stream and the second is the character
+ that caused the invocation of the readmacro. The readmacro
+ function should return <code>NIL</code> to indicate that the character should
+ be treated as white space or a value consed with <code>NIL</code> to indicate
+ that the readmacro should be treated as an occurence of the
+ specified value. Of course, the readmacro code is free to read
+ additional characters from the input stream.
+<p>
+ XLISP defines several useful read macros:
+<ul>
+<li>
+ '<i><expr></i> == (quote <i><expr></i>)
+<li> #'<i><expr></i> == (function <i><expr></i>)
+<li> #(<i><expr></i>...) == an array of the specified expressions
+<li> #x<i><hdigits></i> == a hexadecimal number (0-9,A-F)
+<li> #o<i><odigits></i> == an octal number (0-7)
+<li> #b<i><bdigits></i> == a binary number (0-1)
+<li> #\<i><char></i> == the ASCII code of the character
+<li> #| ... |# == a comment
+<li> #:<i><symbol></i> == an uninterned symbol
+<li> `<i><expr></i> == (backquote <i><expr></i>)
+<li> ,<i><expr></i> == (comma <i><expr></i>)
+<li> ,@<i><expr></i> == (comma-at <i><expr></i>)
+<li></ul>
+<a name = "109"><h3>Lambda Lists</h3></a><a name="index679"> There are several forms in XLISP that require that a ``lambda
+ list'' be specified. A lambda list is a definition of the
+ arguments accepted by a function. There are four different
+ types of arguments.
+<p>
+ The lambda list starts with required arguments. Required
+ arguments must be specified in every call to the function.
+<p>
+ The required arguments are followed by the &optional arguments.
+ Optional arguments may be provided or omitted in a call. An
+ initialization expression may be specified to provide a default
+ value for an &optional argument if it is omitted from a call.
+ If no initialization expression is specified, an omitted
+ argument is initialized to <code>NIL</code>. It is also possible to provide
+ the name of a <code>supplied-p</code> variable that can be used to
+ determine if a call provided a value for the argument or if the
+ initialization expression was used. If specified, the supplied-
+ p variable will be bound to T if a value was specified in the
+ call and <code>NIL</code> if the default value was used.
+<p>
+ The &optional arguments are followed by the &rest argument. The
+ &rest argument gets bound to the remainder of the argument list
+ after the required and &optional arguments have been removed.
+<p>
+ The &rest argument is followed by the &key arguments. When a
+ keyword argument is passed to a function, a pair of values
+ appears in the argument list. The first expression in the pair
+ should evaluate to a keyword symbol (a symbol that begins with a
+ ``<code>:</code>''). The value of the second expression is the value of the
+ keyword argument. Like &optional arguments, &key arguments can
+ have initialization expressions and supplied-p variables. In
+ addition, it is possible to specify the keyword to be used in a
+ function call. If no keyword is specified, the keyword obtained
+ by adding a ``<code>:</code>'' to the beginning of the keyword argument symbol
+ is used. In other words, if the keyword argument symbol is
+ <code>foo</code>, the keyword will be <code>':foo</code>.
+<p>
+ The &key arguments are followed by the &aux variables. These
+ are local variables that are bound during the evaluation of the
+ function body. It is possible to have initialization
+ expressions for the &aux variables.
+<p>
+ Here is the complete syntax for lambda lists:
+<blockquote>
+ (<i>rarg</i>...<br>
+
+ [&optional [<i>oarg</i> | (<i>oarg</i> [<i>init</i> [<i>svar</i>]])]...]<br>
+
+ [&rest <i>rarg</i>]<br>
+
+ [&key<br>
+
+ [<i>karg</i> | ([<i>karg</i> | (<i>key</i> <i>karg</i>)] [<i>init</i> [<i>svar</i>]])]...<br>
+
+ &allow-other-keys]<br>
+
+ [&aux<br>
+
+ [<i>aux</i> | (<i>aux</i> [<i>init</i>])]...])
+<p>
+ where:
+<p>
+ <i>rarg</i> is a required argument symbol<br>
+
+ <i>oarg</i> is an &optional argument symbol<br>
+
+ <i>rarg</i> is the &rest argument symbol<br>
+
+ <i>karg</i> is a &key argument symbol<br>
+
+ <i>key</i> is a keyword symbol<br>
+
+ <i>aux</i> is an auxiliary variable symbol<br>
+
+ <i>init</i> is an initialization expression<br>
+
+ <i>svar</i> is a supplied-p variable symbol<br>
+
+</blockquote>
+<p>
+<a name = "110"><h3>Objects</h3></a><a name="index680"> Definitions:
+<ul>
+<li>
+selector - a symbol used to select an appropriate method
+<li>message - a selector and a list of actual arguments
+<li>method - the code that implements a message
+</ul>
+ Since XLISP was created to provide a simple basis for
+ experimenting with object-oriented programming, one of the
+ primitive data types included is <i>object</i>. In XLISP, an object
+ consists of a data structure containing a pointer to the
+ object's class as well as an array containing the values of the
+ object's instance variables.
+<p>
+ Officially, there is no way to see inside an object (look at the
+ values of its instance variables). The only way to communicate
+ with an object is by sending it a message.
+<p>
+ You can send a message to an object using the <code>send</code> function.
+ This function takes the object as its first argument, the
+ message selector as its second argument (which must be a symbol)
+ and the message arguments as its remaining arguments.
+<p>
+ The <code>send</code> function determines the class of the receiving object
+ and attempts to find a method corresponding to the message
+ selector in the set of messages defined for that class. If the
+ message is not found in the object's class and the class has a
+ super-class, the search continues by looking at the messages
+ defined for the super-class. This process continues from one
+ super-class to the next until a method for the message is found.
+ If no method is found, an error occurs.
+<p>
+ A message can also be sent from the body of a method by using
+ the current object, but the method lookup starts with the
+ object's superclass rather than its class. This allows a
+ subclass to invoke a standard method in its parent class even
+ though it overrides that method with its own specialized
+ version.
+<p>
+ When a method is found, the evaluator binds the receiving object
+ to the symbol <code>self</code> and evaluates the method using the
+ remaining elements of the original list as arguments to the
+ method. These arguments are always evaluated prior to being
+ bound to their corresponding formal arguments. The result of
+ evaluating the method becomes the result of the expression.
+<p>
+<a name = "111"><h3>The ``Object'' Class</h3></a><a name="index681"><code>Object</code><a name="index682"> - the top of the class hierarchy.
+<p>
+Messages:
+<dl>
+<dt>
+<code>:show<a name="index683"></code> - show an object's instance variables.
+<dd>
+returns - the object
+
+<br>
+<br><dt><code>:class<a name="index684"></code> - return the class of an object
+<dd>
+returns - the class of the object
+
+<br>
+<br><dt><code>:isnew<a name="index685"></code> - the default object initialization routine
+<dd>
+returns - the object
+<br><dt>
+<code>:sendsuper<a name="index686"></code> <i>sel</i> <i>args</i>... - send superclass a message
+<dd>
+<i>sel</i> - the message selector<br>
+<i>args</i> - the message arguments<br>
+returns - the result of sending the message
+
+<br>
+<br><dt>
+</dl>
+<p>
+<a name = "112"><h3>The ``Class'' Class</h3></a><a name="index687"><code>Class<a name="index688"></code> - class of all object classes (including itself)
+<p>
+ Messages:
+<p>
+<dl>
+<dt>
+ :new<a name="index689"> - create a new instance of a class
+<dd>
+ returns - the new class object
+
+<br>
+<br><dt> :isnew<a name="index690"> <i>ivars</i> [<i>cvars</i> [<i>super</i>]] - initialize a new class
+<dd>
+ <i>ivars</i> - the list of instance variable symbols<br>
+ <i>cvars</i> - the list of class variable symbols<br>
+ <i>super</i> - the superclass (default is object)<br>
+ returns - the new class object
+
+<br>
+<br><dt> :answer<a name="index691"> <i>msg</i> <i>fargs</i> <i>code</i> - add a message to a class
+<dd>
+ <i>msg</i> - the message symbol<br>
+ <i>fargs</i> - the formal argument list (lambda list)<br>
+ <i>code</i> - a list of executable expressions<br>
+ returns - the object
+
+<br>
+<br><dt>
+</dl>
+<p>
+ When a new instance of a class is created by sending the message
+ <code>:new</code> to an existing class, the message <code>:isnew</code> followed by
+ whatever parameters were passed to the <code>:new</code> message is sent to
+ the newly created object.
+<p>
+ When a new class is created by sending the <code>:new</code> message to the
+ object <code>Class</code>, an optional parameter may be specified
+ indicating the superclass of the new class. If this parameter
+ is omitted, the new class will be a subclass of <code>Object</code>. A
+ class inherits all instance variables, class variables, and
+ methods from its super-class.
+<p>
+<a name = "113"><h3>Profiling</h3></a><a name="index692">
+The Xlisp 2.0 release has been extended with a profiling facility, which counts how many times and where <code>eval</code> is executed. A separate count is maintained for each named function, closure, or macro, and a count indicates an <code>eval</code> in the immediately (lexically) enclosing named function, closure, or macro. Thus, the count gives an indication of the amount of time spent in a function, not counting nested function calls. The list of all functions executed is maintained on the global <code>*profile*</code> variable. These functions in turn have <code>*profile*</code> properties, which maintain the counts. The profile system merely increments counters and puts symbols on the <code>*profile*</code> list. It is up to the user to initialize data and gather results. Profiling is turned on or off with the <code>profile</code> function. Unfortunately, methods cannot be profiled with this facility.
+<p>
+<a name = "114"><h3>SYMBOLS</h3></a><a name="index693">
+<ul>
+<li>
+<code>self</code> - the current object (within a method context)
+<li><code>*obarray*<a name="index694"></code> - the object hash table
+<li><code>*standard-input*<a name="index695"></code> - the standard input stream
+<li><code>*standard-output*<a name="index696"></code> - the standard output stream
+<li><code>*error-output*<a name="index697"></code> - the error output stream
+<li><code>*trace-output*<a name="index698"></code> - the trace output stream
+<li><code>*debug-io*<a name="index699"></code> - the debug i/o stream
+<li><code>*breakenable*<a name="index700"></code> - flag controlling entering break loop on errors
+<li><code>*tracelist*<a name="index701"></code> - list of names of functions to trace
+<li><code>*tracenable*<a name="index702"></code> - enable trace back printout on errors
+<li><code>*tracelimit*<a name="index703"></code> - number of levels of trace back information
+<li><code>*evalhook*<a name="index704"></code> - user substitute for the evaluator function
+<li><code>*applyhook*<a name="index705"></code> - (not yet implemented)
+<li><code>*readtable*<a name="index706"></code> - the current readtable
+<li><code>*unbound*<a name="index707"></code> - indicator for unbound symbols
+<li><code>*gc-flag*<a name="index708"></code> - controls the printing of gc messages
+<li><code>*gc-hook*<a name="index709"></code> - function to call after garbage collection
+<li><code>*integer-format*<a name="index710"></code> - format for printing integers (``%d'' or ``%ld'')
+<li><code>*float-format*<a name="index711"></code> - format for printing floats (``%g'')
+<li><code>*print-case*<a name="index712"></code> - symbol output case (:upcase or :downcase)
+</ul>
+<p>
+ There are several symbols maintained by the read/eval/print
+ loop. The symbols <code>+</code>, <code>++</code>, and <code>+++</code> are bound to the most
+ recent three input expressions. The symbols <code>*</code>, <code>**</code> and <code>***</code>
+ are bound to the most recent three results. The symbol <code>-</code> is
+ bound to the expression currently being evaluated. It becomes
+ the value of <code>+</code> at the end of the evaluation.
+<a name = "115"><h3>Evaluation Functions</h3></a><a name="index713">
+<dl>
+<dt>
+ (eval<a name="index714"> <i>expr</i>) - evaluate an xlisp expression
+<dd>
+ <i>expr</i> - the expression to be evaluated<br>
+ returns - the result of evaluating the expression
+
+<br>
+<br><dt> (apply<a name="index715"> <i>fun</i> <i>args</i>) - apply a function to a list of arguments
+<dd>
+ <i>fun</i> - the function to apply (or function symbol)<br>
+ <i>args</i> - the argument list<br>
+ returns - the result of applying the function to the arguments
+
+<br>
+<br><dt> (funcall<a name="index716"> <i>fun</i> <i>arg</i>...) - call a function with arguments
+<dd>
+ <i>fun</i> - the function to call (or function symbol)<br>
+ <i>arg</i> - arguments to pass to the function<br>
+ returns - the result of calling the function with the arguments
+
+<br>
+<br><dt> (quote<a name="index717"> <i>expr</i>) - return an expression unevaluated
+<dd>
+ <i>expr</i> - the expression to be quoted (quoted)<br>
+ returns - <i>expr</i> unevaluated
+
+<br>
+<br><dt> (function<a name="index718"> <i>expr</i>) - get the functional interpretation<dd>
+ <i>expr</i> - the symbol or lambda expression (quoted)<br>
+ returns - the functional interpretation<br>
+
+<br><dt> (backquote<a name="index719"> <i>expr</i>) - fill in a template<dd>
+ <i>expr</i> - the template<br>
+ returns - a copy of the template with comma and comma-at<br>
+ expressions expanded
+
+<br>
+<br><dt> (lambda<a name="index720"> <i>args</i> <i>expr</i>...) - make a function closure<dd>
+ <i>args</i> - formal argument list (lambda list) (quoted)<br>
+ <i>expr</i> - expressions of the function body<br>
+ returns - the function closure<br>
+
+<br><dt> (get-lambda-expression<a name="index721"> <i>closure</i>) - get the lambda expression<dd>
+ <i>closure</i> - the closure<br>
+ returns - the original lambda expression<br>
+
+<br><dt> (macroexpand<a name="index722"> <i>form</i>) - recursively expand macro calls<dd>
+ <i>form</i> - the form to expand<br>
+ returns - the macro expansion<br>
+
+<br><dt> (macroexpand-1<a name="index723"> <i>form</i>) - expand a macro call<dd>
+ <i>form</i> - the macro call form<br>
+ returns - the macro expansion<br>
+
+<br><dt>
+</dl><a name = "116"><h3>Symbol Functions</h3></a><a name="index724">
+<dl>
+<dt>
+ (set<a name="index725"> <i>sym</i> <i>expr</i>) - set the value of a symbol
+<dd>
+ <i>sym</i> - the symbol being set<br>
+ <i>expr</i> - the new value<br>
+ returns - the new value<br>
+
+<br><dt> (setq<a name="index726"> [<i>sym</i> <i>expr</i>]...) - set the value of a symbol
+<dd>
+ <i>sym</i> - the symbol being set (quoted)<br>
+ <i>expr</i> - the new value<br>
+ returns - the new value<br>
+
+<br><dt> (psetq<a name="index727"> [<i>sym</i> <i>expr</i>]...) - parallel version of setq
+<dd>
+ <i>sym</i> - the symbol being set (quoted)<br>
+ <i>expr</i> - the new value<br>
+ returns - the new value<br>
+
+<br><dt> (setf<a name="index728"> [<i>place</i> <i>expr</i>]...) - set the value of a field
+<dd>
+ <i>place</i> - the field specifier (quoted):<br>
+<dl><dd>
+ <i>sym</i> - set value of a symbol<br>
+ (car <i>expr</i>) - set car of a cons node<br>
+ (cdr <i>expr</i>) - set cdr of a cons node<br>
+ (nth <i>n</i> <i>expr</i>) - set nth car of a list<br>
+ (aref <i>expr</i> <i>n</i>) - set nth element of an array<br>
+ (get <i>sym</i> <i>prop</i>) - set value of a property<br>
+ (symbol-value <i>sym</i>) - set value of a symbol<br>
+ (symbol-function <i>sym</i>) - set functional value of a symbol<br>
+ (symbol-plist <i>sym</i>) - set property list of a symbol<br>
+</dl>
+ <i>expr</i> - the new value<br>
+ returns - the new value<br>
+
+<br><dt>
+
+ (defun<a name="index729"> <i>sym</i> <i>fargs</i> <i>expr</i>...) - define a function<br>
+ (defmacro<a name="index730"> <i>sym</i> <i>fargs</i> <i>expr</i>...) - define a macro
+
+<dd>
+ <i>sym</i> - symbol being defined (quoted)<br>
+ <i>fargs</i> - formal argument list (lambda list) (quoted)<br>
+ <i>expr</i> - expressions constituting the body of the<br>
+ function (quoted)
+ returns - the function symbol<br>
+
+<br><dt> (gensym<a name="index731"> [<i>tag</i>]) - generate a symbol
+<dd>
+ <i>tag</i> - string or number<br>
+ returns - the new symbol<br>
+
+<br><dt>(intern<a name="index732"> <i>pname</i>) - make an interned symbol
+<dd>
+ <i>pname</i> - the symbol's print name string<br>
+ returns - the new symbol<br>
+
+<br><dt> (make-symbol<a name="index733"> <i>pname</i>) - make an uninterned symbol
+<dd>
+ <i>pname</i> - the symbol's print name string<br>
+ returns - the new symbol<br>
+
+<br><dt> (symbol-name<a name="index734"> <i>sym</i>) - get the print name of a symbol
+<dd>
+ <i>sym</i> - the symbol<br>
+ returns - the symbol's print name<br>
+
+<br><dt> (symbol-value<a name="index735"> <i>sym</i>) - get the value of a symbol
+<dd>
+ <i>sym</i> - the symbol<br>
+ returns - the symbol's value<br>
+
+<br><dt> (symbol-function<a name="index736"> <i>sym</i>) - get the functional value of a symbol
+<dd>
+ <i>sym</i> - the symbol<br>
+ returns - the symbol's functional value<br>
+
+<br><dt> (symbol-plist<a name="index737"> <i>sym</i>) - get the property list of a symbol
+<dd>
+ <i>sym</i> - the symbol<br>
+ returns - the symbol's property list<br>
+
+<br><dt> (hash<a name="index738"> <i>sym</i> <i>n</i>) - compute the hash index for a symbol
+<dd>
+ <i>sym</i> - the symbol or string<br>
+ <i>n</i> - the table size (integer)<br>
+ returns - the hash index (integer)<br>
+
+<br><dt>
+</dl><a name = "117"><h3>Property List Functions</h3></a><a name="index739">
+<dl>
+<dt>
+ (get<a name="index740"> <i>sym</i> <i>prop</i>) - get the value of a property
+<dd>
+ <i>sym</i> - the symbol<br>
+ <i>prop</i> - the property symbol<br>
+ returns - the property value or <code>nil</code><br>
+
+<br><dt> (putprop<a name="index741"> <i>sym</i> <i>val</i> <i>prop</i>) - put a property onto a property list
+<dd>
+ <i>sym</i> - the symbol<br>
+ <i>val</i> - the property value<br>
+ <i>prop</i> - the property symbol<br>
+ returns - the property value<br>
+
+<br><dt> (remprop<a name="index742"> <i>sym</i> <i>prop</i>) - remove a property
+<dd>
+ <i>sym</i> - the symbol<br>
+ <i>prop</i> - the property symbol<br>
+ returns - <code>nil</code><br>
+
+<br><dt>
+</dl><a name = "118"><h3>Array Functions</h3></a><a name="index743">
+<dl>
+<dt>
+ (aref<a name="index744"> <i>array</i> <i>n</i>) - get the nth element of an array
+<dd>
+ <i>array</i> - the array<br>
+ <i>n</i> - the array index (integer)<br>
+ returns - the value of the array element<br>
+
+<br><dt> (make-array<a name="index745"> <i>size</i>) - make a new array
+<dd>
+ <i>size</i> - the size of the new array (integer)<br>
+ returns - the new array<br>
+
+<br><dt> (vector<a name="index746"> <i>expr</i>...) - make an initialized vector
+<dd>
+ <i>expr</i> - the vector elements<br>
+ returns - the new vector<br>
+
+<br><dt>
+</dl><a name = "119"><h3>List Functions</h3></a><a name="index747">
+<dl>
+<dt>
+ (car<a name="index748"> <i>expr</i>) - return the car of a list node
+<dd>
+ <i>expr</i> - the list node<br>
+ returns - the car of the list node<br>
+
+<br><dt> (cdr<a name="index749"> <i>expr</i>) - return the cdr of a list node
+<dd>
+ <i>expr</i> - the list node<br>
+ returns - the cdr of the list node<br>
+
+<br><dt> (c<i>xx</i>r<a name="index750"> <i>expr</i>) - all c<i>xx</i>r combinations
+<dd>
+
+<br>
+<br><dt> (c<i>xxx</i>r<a name="index751"> <i>expr</i>) - all c<i>xxx</i>r combinations
+<dd>
+
+<br>
+<br><dt> (c<i>xxxx</i>r<a name="index752"> <i>expr</i>) - all c<i>xxxx</i>r combinations
+<dd>
+
+<br>
+<br><dt> (first<a name="index753"> <i>expr</i>) - a synonym for car
+<dd>
+
+<br>
+<br><dt> (second<a name="index754"> <i>expr</i>) - a synonym for cadr
+<dd>
+
+<br>
+<br><dt> (third<a name="index755"> <i>expr</i>) - a synonym for caddr
+<dd>
+
+<br>
+<br><dt> (fourth<a name="index756"> <i>expr</i>) - a synonym for cadddr
+<dd>
+
+<br>
+<br><dt> (rest<a name="index757"> <i>expr</i>) - a synonym for cdr
+<dd>
+
+<br>
+<br><dt> (cons<a name="index758"> <i>expr1</i> <i>expr2</i>) - construct a new list node
+<dd>
+ <i>expr1</i> - the car of the new list node<br>
+ <i>expr2</i> - the cdr of the new list node<br>
+ returns - the new list node<br>
+
+<br><dt> (list<a name="index759"> <i>expr</i>...) - create a list of values
+<dd>
+ <i>expr</i> - expressions to be combined into a list<br>
+ returns - the new list<br>
+
+<br><dt> (append<a name="index760"> <i>expr</i>...) - append lists
+<dd>
+ <i>expr</i> - lists whose elements are to be appended<br>
+ returns - the new list<br>
+
+<br><dt> (reverse<a name="index761"> <i>expr</i>) - reverse a list
+<dd>
+ <i>expr</i> - the list to reverse<br>
+ returns - a new list in the reverse order<br>
+
+<br><dt> (last<a name="index762"> <i>list</i>) - return the last list node of a list
+<dd>
+ <i>list</i> - the list<br>
+ returns - the last list node in the list<br>
+
+<br><dt> (member<a name="index763"> <i>expr</i> <i>list</i> &key :test :test-not) - find an expression in a list
+<dd>
+ <i>expr</i> - the expression to find<br>
+ <i>list</i> - the list to search<br>
+ :test - the test function (defaults to eql)<br>
+ :test-not - the test function (sense inverted) <br>
+ returns - the remainder of the list starting with the expression<br>
+
+<br><dt> (assoc<a name="index764"> <i>expr</i> <i>alist</i> &key :test :test-not) - find an expression in an a-list
+<dd>
+ <i>expr</i> - the expression to find<br>
+ <i>alist</i> - the association list<br>
+ :test - the test function (defaults to eql)<br>
+ :test-not - the test function (sense inverted) <br>
+ returns - the alist entry or <code>nil</code><br>
+
+<br><dt> (remove<a name="index765"> <i>expr</i> <i>list</i> &key :test :test-not) - remove elements from a list
+<dd>
+ <i>expr</i> - the element to remove<br>
+ <i>list</i> - the list<br>
+ :test - the test function (defaults to eql)<br>
+ :test-not - the test function (sense inverted) <br>
+ returns - copy of list with matching expressions removed<br>
+
+<br><dt> (remove-if<a name="index766"> <i>test</i> <i>list</i>) - remove elements that pass test
+<dd>
+ <i>test</i> - the test predicate<br>
+ <i>list</i> - the list<br>
+ returns - copy of list with matching elements removed<br>
+
+<br><dt> (remove-if-not<a name="index767"> <i>test</i> <i>list</i>) - remove elements that fail test
+<dd>
+ <i>test</i> - the test predicate<br>
+ <i>list</i> - the list<br>
+ returns - copy of list with non-matching elements removed<br>
+
+<br><dt> (length<a name="index768"> <i>expr</i>) - find the length of a list, vector or string
+<dd>
+ <i>expr</i> - the list, vector or string<br>
+ returns - the length of the list, vector or string<br>
+
+<br><dt> (nth<a name="index769"> <i>n</i> <i>list</i>) - return the nth element of a list
+<dd>
+ <i>n</i> - the number of the element to return (zero origin)<br>
+ <i>list</i> - the list<br>
+ returns - the nth element or <code>nil</code> if the list isn't that long<br>
+
+<br><dt> (nthcdr<a name="index770"> <i>n</i> <i>list</i>) - return the nth cdr of a list
+<dd>
+ <i>n</i> - the number of the element to return (zero origin)<br>
+ <i>list</i> - the list<br>
+ returns - the nth cdr or <code>nil</code> if the list isn't that long<br>
+
+<br><dt> (mapc<a name="index771"> <i>fcn</i> <i>list1</i> <i>list</i>...) - apply function to successive cars
+<dd>
+ <i>fcn</i> - the function or function name<br>
+ <i>listn</i> - a list for each argument of the function<br>
+ returns - the first list of arguments<br>
+
+<br><dt> (mapcar<a name="index772"> <i>fcn</i> <i>list1</i> <i>list</i>...) - apply function to successive cars
+<dd>
+ <i>fcn</i> - the function or function name<br>
+ <i>listn</i> - a list for each argument of the function<br>
+ returns - a list of the values returned<br>
+
+<br><dt> (mapl<a name="index773"> <i>fcn</i> <i>list1</i> <i>list</i>...) - apply function to successive cdrs
+<dd>
+ <i>fcn</i> - the function or function name<br>
+ <i>listn</i> - a list for each argument of the function<br>
+ returns - the first list of arguments<br>
+
+<br><dt> (maplist<a name="index774"> <i>fcn</i> <i>list1</i> <i>list</i>...) - apply function to successive cdrs
+<dd>
+ <i>fcn</i> - the function or function name<br>
+ <i>listn</i> - a list for each argument of the function<br>
+ returns - a list of the values returned<br>
+
+<br><dt> (subst<a name="index775"> <i>to</i> <i>from</i> <i>expr</i> &key :test :test-not) - substitute expressions
+<dd>
+ <i>to</i> - the new expression<br>
+ <i>from</i> - the old expression<br>
+ <i>expr</i> - the expression in which to do the substitutions<br>
+ :test - the test function (defaults to eql)<br>
+ :test-not - the test function (sense inverted) <br>
+ returns - the expression with substitutions<br>
+
+<br><dt> (sublis<a name="index776"> <i>alist</i> <i>expr</i> &key :test :test-not) - substitute with an a-list
+<dd>
+ <i>alist</i> - the association list<br>
+ <i>expr</i> - the expression in which to do the substitutions<br>
+ :test - the test function (defaults to eql)<br>
+ :test-not - the test function (sense inverted) <br>
+ returns - the expression with substitutions<br>
+
+<br><dt>
+</dl><a name = "120"><h3>Destructive List Functions</h3></a><a name="index777">
+<dl>
+<dt>
+ (rplaca<a name="index778"> <i>list</i> <i>expr</i>) - replace the car of a list node
+<dd>
+ <i>list</i> - the list node<br>
+ <i>expr</i> - the new value for the car of the list node<br>
+ returns - the list node after updating the car<br>
+
+<br><dt> (rplacd<a name="index779"> <i>list</i> <i>expr</i>) - replace the cdr of a list node
+<dd>
+ <i>list</i> - the list node<br>
+ <i>expr</i> - the new value for the cdr of the list node<br>
+ returns - the list node after updating the cdr<br>
+
+<br><dt> (nconc<a name="index780"> <i>list</i>...) - destructively concatenate lists
+<dd>
+ <i>list</i> - lists to concatenate<br>
+ returns - the result of concatenating the lists<br>
+
+<br><dt> (delete<a name="index781"> <i>expr</i> &key :test :test-not) - delete elements from a list
+<dd>
+ <i>expr</i> - the element to delete<br>
+ <i>list</i> - the list<br>
+ :test - the test function (defaults to eql)<br>
+ :test-not - the test function (sense inverted) <br>
+ returns - the list with the matching expressions deleted<br>
+
+<br><dt> (delete-if<a name="index782"> <i>test</i> <i>list</i>) - delete elements that pass test
+<dd>
+ <i>test</i> - the test predicate<br>
+ <i>list</i> - the list<br>
+ returns - the list with matching elements deleted<br>
+
+<br><dt> (delete-if-not<a name="index783"> <i>test</i> <i>list</i>) - delete elements that fail test
+<dd>
+ <i>test</i> - the test predicate<br>
+ <i>list</i> - the list<br>
+ returns - the list with non-matching elements deleted<br>
+
+<br><dt> (sort<a name="index784"> <i>list</i> <i>test</i>) - sort a list
+<dd>
+ <i>list</i> - the list to sort<br>
+ <i>test</i> - the comparison function<br>
+ returns - the sorted list<br>
+
+<br><dt>
+</dl><a name = "121"><h3>Predicate Functions</h3></a><a name="index785">
+<dl>
+<dt>
+ (atom<a name="index786"> <i>expr</i>) - is this an atom?
+<dd>
+ <i>expr</i> - the expression to check<br>
+ returns - <code>t</code> if the value is an atom, <code>nil</code> otherwise<br>
+
+<br><dt> (symbolp<a name="index787"> <i>expr</i>) - is this a symbol?
+<dd>
+ <i>expr</i> - the expression to check<br>
+ returns - <code>t</code> if the expression is a symbol, <code>nil</code> otherwise<br>
+
+<br><dt> (numberp<a name="index788"> <i>expr</i>) - is this a number?
+<dd>
+ <i>expr</i> - the expression to check<br>
+ returns - <code>t</code> if the expression is a number, <code>nil</code> otherwise<br>
+
+<br><dt> (null<a name="index789"> <i>expr</i>) - is this an empty list?
+<dd>
+ <i>expr</i> - the list to check<br>
+ returns - <code>t</code> if the list is empty, <code>nil</code> otherwise<br>
+
+<br><dt> (not<a name="index790"> <i>expr</i>) - is this false?
+<dd>
+ <i>expr</i> - the expression to check<br>
+ return - <code>t</code> if the value is <code>nil</code>, <code>nil</code> otherwise<br>
+
+<br><dt> (listp<a name="index791"> <i>expr</i>) - is this a list?
+<dd>
+ <i>expr</i> - the expression to check<br>
+ returns - <code>t</code> if the value is a cons or <code>nil</code>, <code>nil</code> otherwise<br>
+
+<br><dt> (endp<a name="index792"> <i>list</i>) - is this the end of a list
+<dd>
+ <i>list</i> - the list<br>
+ returns - <code>t</code> if the value is <code>nil</code>, <code>nil</code> otherwise<br>
+
+<br><dt> (consp<a name="index793"> <i>expr</i>) - is this a non-empty list?
+<dd>
+ <i>expr</i> - the expression to check<br>
+ returns - <code>t</code> if the value is a cons, <code>nil</code> otherwise<br>
+
+<br><dt> (integerp<a name="index794"> <i>expr</i>) - is this an integer?
+<dd>
+ <i>expr</i> - the expression to check<br>
+ returns - <code>t</code> if the value is an integer, <code>nil</code> otherwise<br>
+
+<br><dt> (floatp<a name="index795"> <i>expr</i>) - is this a float?
+<dd>
+ <i>expr</i> - the expression to check<br>
+ returns - <code>t</code> if the value is a float, <code>nil</code> otherwise<br>
+
+<br><dt> (stringp<a name="index796"> <i>expr</i>) - is this a string?
+<dd>
+ <i>expr</i> - the expression to check<br>
+ returns - <code>t</code> if the value is a string, <code>nil</code> otherwise<br>
+
+<br><dt> (characterp<a name="index797"> <i>expr</i>) - is this a character?
+<dd>
+ <i>expr</i> - the expression to check<br>
+ returns - <code>t</code> if the value is a character, <code>nil</code> otherwise<br>
+
+<br><dt> (arrayp<a name="index798"> <i>expr</i>) - is this an array?
+<dd>
+ <i>expr</i> - the expression to check<br>
+ returns - <code>t</code> if the value is an array, <code>nil</code> otherwise<br>
+
+<br><dt> (streamp<a name="index799"> <i>expr</i>) - is this a stream?
+<dd>
+ <i>expr</i> - the expression to check<br>
+ returns - <code>t</code> if the value is a stream, <code>nil</code> otherwise<br>
+
+<br><dt> (objectp<a name="index800"> <i>expr</i>) - is this an object?
+<dd>
+ <i>expr</i> - the expression to check<br>
+ returns - <code>t</code> if the value is an object, <code>nil</code> otherwise<br>
+
+<br><dt> (boundp<a name="index801"> <i>sym</i>) - is a value bound to this symbol?
+<dd>
+ <i>sym</i> - the symbol<br>
+ returns - <code>t</code> if a value is bound to the symbol, <code>nil</code> otherwise<br>
+
+<br><dt> (fboundp<a name="index802"> <i>sym</i>) - is a functional value bound to this symbol?
+<dd>
+ <i>sym</i> - the symbol<br>
+ returns - <code>t</code> if a functional value is bound to the symbol,<br>
+ <code>nil</code> otherwise
+
+<br>
+<br><dt> (minusp<a name="index803"> <i>expr</i>) - is this number negative?
+<dd>
+ <i>expr</i> - the number to test<br>
+ returns - <code>t</code> if the number is negative, <code>nil</code> otherwise<br>
+
+<br><dt> (zerop<a name="index804"> <i>expr</i>) - is this number zero?
+<dd>
+ <i>expr</i> - the number to test<br>
+ returns - <code>t</code> if the number is zero, <code>nil</code> otherwise<br>
+
+<br><dt> (plusp<a name="index805"> <i>expr</i>) - is this number positive?
+<dd>
+ <i>expr</i> - the number to test<br>
+ returns - <code>t</code> if the number is positive, <code>nil</code> otherwise<br>
+
+<br><dt> (evenp<a name="index806"> <i>expr</i>) - is this integer even?
+<dd>
+ <i>expr</i> - the integer to test<br>
+ returns - <code>t</code> if the integer is even, <code>nil</code> otherwise<br>
+
+<br><dt> (oddp<a name="index807"> <i>expr</i>) - is this integer odd?
+<dd>
+ <i>expr</i> - the integer to test<br>
+ returns - <code>t</code> if the integer is odd, <code>nil</code> otherwise<br>
+
+<br><dt> (eq<a name="index808"> <i>expr1</i> <i>expr2</i>) - are the expressions identical?
+<dd>
+ <i>expr1</i> - the first expression<br>
+ <i>expr2</i> - the second expression<br>
+ returns - <code>t</code> if they are equal, <code>nil</code> otherwise<br>
+
+<br><dt>(eql<a name="index809"> <i>expr1</i> <i>expr2</i>) - are the expressions
+identical? (works with all numbers)
+<dd>
+ <i>expr1</i> - the first expression<br>
+ <i>expr2</i> - the second expression<br>
+ returns - <code>t</code> if they are equal, <code>nil</code> otherwise<br>
+
+<br><dt> (equal<a name="index810"> <i>expr1</i> <i>expr2</i>) - are the expressions equal?
+<dd>
+ <i>expr1</i> - the first expression<br>
+ <i>expr2</i> - the second expression<br>
+ returns - <code>t</code> if they are equal, <code>nil</code> otherwise<br>
+
+<br><dt>
+</dl><a name = "122"><h3>Control Constructs</h3></a><a name="index811">
+<dl>
+<dt>
+ (cond<a name="index812"> <i>pair</i>...) - evaluate conditionally
+<dd>
+ <i>pair</i> - pair consisting of:<br>
+<dl><dd>
+ (<i>pred</i> <i>expr</i>...)
+</dl>
+ where:
+<dl><dd>
+ <i>pred</i> - is a predicate expression<br>
+ <i>expr</i> - evaluated if the predicate
+ is not <code>nil</code>
+</dl>
+returns - the value of the first expression whose predicate is not
+<code>nil</code>
+
+<br>
+<br><dt> (and<a name="index813"> <i>expr</i>...) - the logical and of a list of expressions
+<dd>
+ <i>expr</i> - the expressions to be anded<br>
+ returns - <code>nil</code> if any expression evaluates to <code>nil</code>,
+ otherwise the value of the last expression
+ (evaluation of expressions stops after the first
+ expression that evaluates to <code>nil</code>)
+
+<br>
+<br><dt> (or<a name="index814"> <i>expr</i>...) - the logical or of a list of expressions
+<dd>
+ <i>expr</i> - the expressions to be ored<br>
+ returns - <code>nil</code> if all expressions evaluate to <code>nil</code>,
+ otherwise the value of the first non-<code>nil</code> expression
+ (evaluation of expressions stops after the first
+ expression that does not evaluate to <code>nil</code>)
+
+<br>
+<br><dt> (if<a name="index815"> <i>texpr</i> <i>expr1</i> [<i>expr2</i>]) - evaluate expressions conditionally
+<dd>
+ <i>texpr</i> - the test expression<br>
+ <i>expr1</i> - the expression to be evaluated if texpr is non-<code>nil</code><br>
+ <i>expr2</i> - the expression to be evaluated if texpr is <code>nil</code><br>
+ returns - the value of the selected expression<br>
+
+<br><dt> (when<a name="index816"> <i>texpr</i> <i>expr</i>...) - evaluate only when a condition is true
+<dd>
+ <i>texpr</i> - the test expression<br>
+ <i>expr</i> - the expression(s) to be evaluated if texpr is non-<code>nil</code><br>
+ returns - the value of the last expression or <code>nil</code>
+
+<br>
+<br><dt> (unless<a name="index817"> <i>texpr</i> <i>expr</i>...) - evaluate only when a condition is false
+<dd>
+ <i>texpr</i> - the test expression<br>
+ <i>expr</i> - the expression(s) to be evaluated if texpr is <code>nil</code><br>
+ returns - the value of the last expression or <code>nil</code><br>
+
+<br><dt> (case<a name="index818"> <i>expr</i> <i>case</i>...) - select by case
+<dd>
+ <i>expr</i> - the selection expression<br>
+ <i>case</i> - pair consisting of:<br>
+<dl><dd>
+ (<i>value</i> <i>expr</i>...)
+</dl>
+ where:
+<dl><dd>
+ <i>value</i> - is a single expression or a list of
+ expressions (unevaluated)<br>
+ <i>expr</i> - are expressions to execute if the
+ case matches
+</dl>
+ returns - the value of the last expression of the matching case<br>
+
+<br><dt>
+
+ (let<a name="index819"> (<i>binding</i>...) <i>expr</i>...) - create local bindings<br>
+ (let*<a name="index820"> (<i>binding</i>...) <i>expr</i>...) - let with sequential binding
+
+<dd>
+ <i>binding</i> - the variable bindings each of which is either:<br>
+<dl><dd>
+ 1) a symbol (which is initialized to <code>nil</code>)<br>
+ 2) a list whose car is a symbol and whose cadr
+ is an initialization expression
+</dl>
+ <i>expr</i> - the expressions to be evaluated<br>
+ returns - the value of the last expression<br>
+
+<br><dt>
+
+ (flet<a name="index821"> (<i>binding</i>...) <i>expr</i>...) - create local functions<br>
+ (labels<a name="index822"> (<i>binding</i>...) <i>expr</i>...) - flet with recursive functions<br>
+ (macrolet<a name="index823"> (<i>binding</i>...) <i>expr</i>...) - create local macros
+
+<dd>
+ <i>binding</i> - the function bindings each of which is:<br>
+<dl><dd>
+ (<i>sym</i> <i>fargs</i> <i>expr</i>...)
+</dl>
+ where:
+<dl><dd>
+ <i>sym</i> - the function/macro name<br>
+ <i>fargs</i> - formal argument list (lambda list)<br>
+ <i>expr</i> - expressions constituting the body of
+ the function/macro
+</dl>
+ <i>expr</i> - the expressions to be evaluated<br>
+ returns - the value of the last expression
+
+<br>
+<br><dt> (catch<a name="index824"> <i>sym</i> <i>expr</i>...) - evaluate expressions and catch throws
+<dd>
+ <i>sym</i> - the catch tag<br>
+ <i>expr</i> - expressions to evaluate<br>
+ returns - the value of the last expression the throw expression<br>
+
+<br><dt> (throw<a name="index825"> <i>sym</i> [<i>expr</i>]) - throw to a catch
+<dd>
+ <i>sym</i> - the catch tag<br>
+ <i>expr</i> - the value for the catch to return (defaults to <code>nil</code>)<br>
+ returns - never returns<br>
+
+<br><dt> (unwind-protect<a name="index826"> <i>expr</i> <i>cexpr</i>...) - protect evaluation of an expression
+<dd>
+ <i>expr</i> - the expression to protect<br>
+ <i>cexpr</i> - the cleanup expressions<br>
+ returns - the value of the expression<br>
+ Note: unwind-protect guarantees to execute the cleanup expressions
+ even if a non-local exit terminates the evaluation of the
+ protected expression
+
+<br>
+<br><dt>
+</dl>
+<p>
+<a name = "123"><h3>Looping Constructs</h3></a><a name="index827">
+<dl>
+<dt>
+ (loop<a name="index828"> <i>expr</i>...) - basic looping form
+<dd>
+ <i>expr</i> - the body of the loop<br>
+ returns - never returns (must use non-local exit)<br>
+
+<br><dt>
+
+ (do<a name="index829"> (<i>binding</i>...) (<i>texpr</i> <i>rexpr</i>...) <i>expr</i>...)<br>
+ (do*<a name="index830"> (<i>binding</i>...) (<i>texpr</i> <i>rexpr</i>...) <i>expr</i>...)
+
+<dd>
+ <i>binding</i> - the variable bindings each of which is either:<br>
+<dl><dd>
+ 1) a symbol (which is initialized to <code>nil</code>)<br>
+ 2) a list of the form: (<i>sym</i> <i>init</i> [<i>step</i>])
+ where:
+<dl><dd>
+ <i>sym</i> - is the symbol to bind<br>
+ <i>init</i> - is the initial value of the symbol<br>
+ <i>step</i> - is a step expression<br>
+</dl>
+</dl>
+ <i>texpr</i> - the termination test expression<br>
+ <i>rexpr</i> - result expressions (the default is <code>nil</code>)<br>
+ <i>expr</i> - the body of the loop (treated like an implicit prog)<br>
+ returns - the value of the last result expression<br>
+
+<br><dt> (dolist<a name="index831"> (<i>sym</i> <i>expr</i> [<i>rexpr</i>]) <i>expr</i>...) - loop through a list
+<dd>
+ <i>sym</i> - the symbol to bind to each list element<br>
+ <i>expr</i> - the list expression<br>
+ <i>rexpr</i> - the result expression (the default is <code>nil</code>)<br>
+ <i>expr</i> - the body of the loop (treated like an implicit prog)<br>
+
+<br><dt> (dotimes<a name="index832"> (<i>sym</i> <i>expr</i> [<i>rexpr</i>]) <i>expr</i>...) - loop from zero to n-1
+<dd>
+ <i>sym</i> - the symbol to bind to each value from 0 to n-1<br>
+ <i>expr</i> - the number of times to loop<br>
+ <i>rexpr</i> - the result expression (the default is <code>nil</code>)<br>
+ <i>expr</i> - the body of the loop (treated like an implicit prog)<br>
+
+<br><dt>
+</dl><a name = "124"><h3>The Program Feature</h3></a><a name="index833">
+<dl>
+<dt>
+
+(prog<a name="index834"> (<i>binding</i>...) <i>expr</i>...) - the program feature<br>
+(prog*<a name="index835"> (<i>binding</i>...) <i>expr</i>...) - prog with sequential binding
+
+<dd>
+ <i>binding</i> - the variable bindings each of which is either:<br>
+<dl><dd>
+ 1) a symbol (which is initialized to <code>nil</code>)<br>
+ 2) a list whose car is a symbol and whose cadr
+ is an initialization expression
+</dl>
+ <i>expr</i> - expressions to evaluate or tags (symbols)<br>
+ returns - <code>nil</code> or the argument passed to the return function<br>
+
+<br><dt> (block<a name="index836"> <i>name</i> <i>expr</i>...) - named block
+<dd>
+ <i>name</i> - the block name (symbol)<br>
+ <i>expr</i> - the block body<br>
+ returns - the value of the last expression<br>
+
+<br><dt> (return<a name="index837"> [<i>expr</i>]) - cause a prog construct to return a value
+<dd>
+ <i>expr</i> - the value (defaults to <code>nil</code>)<br>
+ returns - never returns<br>
+
+<br><dt> (return-from<a name="index838"> <i>name</i> [<i>value</i>]) - return from a named block
+<dd>
+ <i>name</i> - the block name (symbol)<br>
+ <i>value</i> - the value to return (defaults to <code>nil</code>)<br>
+ returns - never returns<br>
+
+<br><dt> (tagbody<a name="index839"> <i>expr</i>...) - block with labels
+<dd>
+ <i>expr</i> - expression(s) to evaluate or tags (symbols)<br>
+ returns - <code>nil</code><br>
+
+<br><dt> (go<a name="index840"> <i>sym</i>) - go to a tag within a tagbody or prog
+<dd>
+ <i>sym</i> - the tag (quoted)<br>
+ returns - never returns<br>
+
+<br><dt> (progv<a name="index841"> <i>slist</i> <i>vlist</i> <i>expr</i>...) - dynamically bind symbols
+<dd>
+ <i>slist</i> - list of symbols<br>
+ <i>vlist</i> - list of values to bind to the symbols<br>
+ <i>expr</i> - expression(s) to evaluate<br>
+ returns - the value of the last expression<br>
+
+<br><dt> (prog1<a name="index842"> <i>expr1</i> <i>expr</i>...) - execute expressions sequentially
+<dd>
+ <i>expr1</i> - the first expression to evaluate<br>
+ <i>expr</i> - the remaining expressions to evaluate<br>
+ returns - the value of the first expression<br>
+
+<br><dt> (prog2<a name="index843"> <i>expr1</i> <i>expr2</i> <i>expr</i>...) - execute expressions sequentially
+<dd>
+ <i>expr1</i> - the first expression to evaluate<br>
+ <i>expr2</i> - the second expression to evaluate<br>
+ <i>expr</i> - the remaining expressions to evaluate<br>
+ returns - the value of the second expression<br>
+
+<br><dt> (progn<a name="index844"> <i>expr</i>...) - execute expressions sequentially
+<dd>
+ <i>expr</i> - the expressions to evaluate<br>
+ returns - the value of the last expression (or <code>nil</code>)<br>
+
+<br><dt>
+</dl><a name = "125"><h3>Debugging and Error Handling</h3></a><a name="index845"><a name="index846">
+<dl>
+<dt>
+ (trace<a name="index847"> <i>sym</i>) - add a function to the trace list
+<dd>
+ <i>sym</i> - the function to add (quoted)<br>
+ returns - the trace list<br>
+
+<br><dt> (untrace<a name="index848"> <i>sym</i>) - remove a function from the trace list
+<dd>
+ <i>sym</i> - the function to remove (quoted)<br>
+ returns - the trace list<br>
+
+<br><dt> (error<a name="index849"> <i>emsg</i> [<i>arg</i>]) - signal a non-correctable error
+<dd>
+ <i>emsg</i> - the error message string<br>
+ <i>arg</i> - the argument expression (printed after the message)<br>
+ returns - never returns<br>
+
+<br><dt> (cerror<a name="index850"> <i>cmsg</i> <i>emsg</i> [<i>arg</i>]) - signal a correctable error
+<dd>
+ <i>cmsg</i> - the continue message string<br>
+ <i>emsg</i> - the error message string<br>
+ <i>arg</i> - the argument expression (printed after the message)<br>
+ returns - <code>nil</code> when continued from the break loop<br>
+
+<br><dt> (break<a name="index851"> [<i>bmsg</i> [<i>arg</i>]]) - enter a break loop
+<dd>
+ <i>bmsg</i> - the break message string (defaults to <code>**break**</code>)<br>
+ <i>arg</i> - the argument expression (printed after the message)<br>
+ returns - <code>nil</code> when continued from the break loop<br>
+
+<br><dt> (clean-up<a name="index852">) - clean-up after an error
+<dd>
+ returns - never returns<br>
+
+<br><dt> (top-level<a name="index853">) - clean-up after an error and return to the top level
+<dd>
+ returns - never returns<br>
+
+<br><dt> (continue<a name="index854">) - continue from a correctable error
+<dd>
+ returns - never returns<br>
+
+<br><dt> (errset<a name="index855"> <i>expr</i> [<i>pflag</i>]) - trap errors
+<dd>
+ <i>expr</i> - the expression to execute<br>
+ <i>pflag</i> - flag to control printing of the error message<br>
+ returns - the value of the last expression consed with <code>nil</code><br>
+ or <code>nil</code> on error
+
+<br>
+<br><dt> (baktrace<a name="index856"><a name="index857"><a name="index858"> [<i>n</i>]) - print n levels of trace back information
+<dd>
+ <i>n</i> - the number of levels (defaults to all levels)<br>
+ returns - <code>nil</code><br>
+
+<br><dt> (evalhook<a name="index859"> <i>expr</i> <i>ehook</i> <i>ahook</i> [<i>env</i>]) - evaluate with hooks
+<dd>
+ <i>expr</i> - the expression to evaluate<br>
+ <i>ehook</i> - the value for <code>*evalhook*</code><br>
+ <i>ahook</i> - the value for <code>*applyhook*</code><br>
+ <i>env</i> - the environment (default is <code>nil</code>)<br>
+ returns - the result of evaluating the expression<br>
+
+<br><dt> (profile<a name="index860"> <i>flag</i>) <a href = "foot.html#foot3">(Footnote 3)</a> - turn profiling on or off.
+<dd>
+ <i>flag</i> - <code>nil</code> turns profiling off, otherwise on<br>
+ returns - the previous state of profiling.<br>
+
+<br><dt>
+</dl><a name = "126"><h3>Arithmetic Functions</h3></a><a name="index861">
+<dl>
+<dt>
+ (truncate<a name="index862"> <i>expr</i>) - truncates a floating point number to an integer
+<dd>
+ <i>expr</i> - the number<br>
+ returns - the result of truncating the number<br>
+
+<br><dt> (float<a name="index863"> <i>expr</i>) - converts an integer to a floating point number
+<dd>
+ <i>expr</i> - the number<br>
+ returns - the result of floating the integer<br>
+
+<br><dt> (+<a name="index864"> <i>expr</i>...) - add a list of numbers
+<dd>
+ <i>expr</i> - the numbers<br>
+ returns - the result of the addition<br>
+
+<br><dt> (-<a name="index865"> <i>expr</i>...) - subtract a list of numbers or negate a single number
+<dd>
+ <i>expr</i> - the numbers<br>
+ returns - the result of the subtraction<br>
+
+<br><dt> (*<a name="index866"> <i>expr</i>...) - multiply a list of numbers
+<dd>
+ <i>expr</i> - the numbers<br>
+ returns - the result of the multiplication<br>
+
+<br><dt> (/<a name="index867"> <i>expr</i>...) - divide a list of numbers
+<dd>
+ <i>expr</i> - the numbers<br>
+ returns - the result of the division<br>
+
+<br><dt> (1+<a name="index868"> <i>expr</i>) - add one to a number
+<dd>
+ <i>expr</i> - the number<br>
+ returns - the number plus one<br>
+
+<br><dt> (1-<a name="index869"> <i>expr</i>) - subtract one from a number
+<dd>
+ <i>expr</i> - the number<br>
+ returns - the number minus one<br>
+
+<br><dt> (rem<a name="index870"><a name="index871"><a name="index872"> <i>expr</i>...) - remainder of a list of numbers
+<dd>
+ <i>expr</i> - the numbers<br>
+ returns - the result of the remainder operation<br>
+
+<br><dt> (min<a name="index873"><a name="index874"> <i>expr</i>...) - the smallest of a list of numbers
+<dd>
+ <i>expr</i> - the expressions to be checked<br>
+ returns - the smallest number in the list<br>
+
+<br><dt> (max<a name="index875"><a name="index876"> <i>expr</i>...) - the largest of a list of numbers
+<dd>
+ <i>expr</i> - the expressions to be checked<br>
+ returns - the largest number in the list<br>
+
+<br><dt> (abs<a name="index877"> <i>expr</i>) - the absolute value of a number
+<dd>
+ <i>expr</i> - the number<br>
+ returns - the absolute value of the number<br>
+
+<br><dt> (gcd<a name="index878"> <i>n1</i> <i>n2</i>...) - compute the greatest common divisor
+<dd>
+ <i>n1</i> - the first number (integer)<br>
+ <i>n2</i> - the second number(s) (integer)<br>
+ returns - the greatest common divisor<br>
+
+<br><dt> (random<a name="index879"> <i>n</i>) - compute a random number between 1 and n-1
+<dd>
+ <i>n</i> - the upper bound (integer)<br>
+ returns - a random number<br>
+
+<br><dt> (sin<a name="index880"> <i>expr</i>) - compute the sine of a number
+<dd>
+ <i>expr</i> - the floating point number<br>
+ returns - the sine of the number<br>
+
+<br><dt> (cos<a name="index881"> <i>expr</i>) - compute the cosine of a number
+<dd>
+ <i>expr</i> - the floating point number<br>
+ returns - the cosine of the number<br>
+
+<br><dt> (tan<a name="index882"> <i>expr</i>) - compute the tangent of a number
+<dd>
+ <i>expr</i> - the floating point number<br>
+ returns - the tangent of the number<br>
+
+<br><dt> (expt<a name="index883"> <i>x-expr</i> <i>y-expr</i>) - compute x to the y power
+<dd>
+ <i>x-expr</i> - the floating point number<br>
+ <i>y-expr</i> - the floating point exponent<br>
+ returns - x to the y power<br>
+
+<br><dt> (exp<a name="index884"> <i>x-expr</i>) - compute e to the x power
+<dd>
+ <i>x-expr</i> - the floating point number<br>
+ returns - e to the x power<br>
+
+<br><dt> (sqrt<a name="index885"> <i>expr</i>) - compute the square root of a number
+<dd>
+ <i>expr</i> - the floating point number<br>
+ returns - the square root of the number<br>
+
+<br><dt>
+
+(<<a name="index886"> <i>n1</i> <i>n2</i>...) - test for less than<br>
+(<=<a name="index887"> <i>n1</i> <i>n2</i>...) - test for less than or equal to<br>
+(=<a name="index888"> <i>n1</i> <i>n2</i>...) - test for equal to<br>
+(/=<a name="index889"> <i>n1</i> <i>n2</i>...) - test for not equal to<br>
+(>=<a name="index890"> <i>n1</i> <i>n2</i>...) - test for greater than or equal to<br>
+(><a name="index891"> <i>n1</i> <i>n2</i>...) - test for greater than
+
+<dd>
+ <i>n1</i> - the first number to compare<br>
+ <i>n2</i> - the second number to compare<br>
+returns - <code>t</code> if the results of comparing <i>n1</i> with <i>n2</i>,
+<i>n2</i> with <i>n3</i>, etc., are all true.<br>
+
+<br><dt>
+</dl><a name = "127"><h3>Bitwise Logical Functions</h3></a><a name="index892">
+<dl>
+<dt>
+ (logand<a name="index893"> <i>expr</i>...) - the bitwise and of a list of numbers
+<dd>
+ <i>expr</i> - the numbers<br>
+ returns - the result of the and operation<br>
+
+<br><dt> (logior<a name="index894"> <i>expr</i>...) - the bitwise inclusive or of a list of numbers
+<dd>
+ <i>expr</i> - the numbers<br>
+ returns - the result of the inclusive or operation<br>
+
+<br><dt> (logxor<a name="index895"> <i>expr</i>...) - the bitwise exclusive or of a list of numbers
+<dd>
+ <i>expr</i> - the numbers<br>
+ returns - the result of the exclusive or operation<br>
+
+<br><dt> (lognot<a name="index896"> <i>expr</i>) - the bitwise not of a number
+<dd>
+ <i>expr</i> - the number<br>
+ returns - the bitwise inversion of number<br>
+
+<br><dt>
+</dl><a name = "128"><h3>String Functions</h3></a><a name="index897">
+<dl>
+<dt>
+ (string<a name="index898"> <i>expr</i>) - make a string from an integer ascii value
+<dd>
+ <i>expr</i> - the integer<br>
+ returns - a one character string<br>
+
+<br><dt> (string-search<a name="index899"> <i>pat</i> <i>str</i> &key :start :end) <a href = "foot.html#foot4">(Footnote 4)</a> - search for pattern in string
+<dd>
+ <i>pat</i> - a string to search for<br>
+ <i>str</i> - the string to be searched<br>
+ :start - the starting offset in str<br>
+ :end - the ending offset + 1<br>
+ returns - index of pat in str or NIL if not found<br>
+
+<br><dt> (string-trim<a name="index900"> <i>bag</i> <i>str</i>) - trim both ends of a string
+<dd>
+ <i>bag</i> - a string containing characters to trim<br>
+ <i>str</i> - the string to trim<br>
+ returns - a trimed copy of the string<br>
+
+<br><dt> (string-left-trim<a name="index901"> <i>bag</i> <i>str</i>) - trim the left end of a string
+<dd>
+ <i>bag</i> - a string containing characters to trim<br>
+ <i>str</i> - the string to trim<br>
+ returns - a trimed copy of the string<br>
+
+<br><dt> (string-right-trim<a name="index902"> <i>bag</i> <i>str</i>) - trim the right end of a string
+<dd>
+ <i>bag</i> - a string containing characters to trim<br>
+ <i>str</i> - the string to trim<br>
+ returns - a trimed copy of the string<br>
+
+<br><dt> (string-upcase<a name="index903"> <i>str</i> &key :start :end) - convert to uppercase
+<dd>
+ <i>str</i> - the string<br>
+ :start - the starting offset<br>
+ :end - the ending offset + 1<br>
+ returns - a converted copy of the string<br>
+
+<br><dt> (string-downcase<a name="index904"> <i>str</i> &key :start :end) - convert to lowercase
+<dd>
+ <i>str</i> - the string<br>
+ :start - the starting offset<br>
+ :end - the ending offset + 1<br>
+ returns - a converted copy of the string<br>
+
+<br><dt> (nstring-upcase<a name="index905"> <i>str</i> &key :start :end) - convert to uppercase
+<dd>
+ <i>str</i> - the string<br>
+ :start - the starting offset<br>
+ :end - the ending offset + 1<br>
+ returns - the converted string (not a copy)<br>
+
+<br><dt> (nstring-downcase<a name="index906"> <i>str</i> &key :start :end) - convert to lowercase
+<dd>
+ <i>str</i> - the string<br>
+ :start - the starting offset<br>
+ :end - the ending offset + 1<br>
+ returns - the converted string (not a copy)<br>
+
+<br><dt> (strcat<a name="index907"><a name="index908"> <i>expr</i>...) - concatenate strings
+<dd>
+ <i>expr</i> - the strings to concatenate<br>
+ returns - the result of concatenating the strings<br>
+
+<br><dt> (subseq<a name="index909"> <i>string</i> <i>start</i> [<i>end</i>]) - extract a substring
+<dd>
+ <i>string</i> - the string<br>
+ <i>start</i> - the starting position (zero origin)<br>
+ <i>end</i> - the ending position + 1 (defaults to end)<br>
+ returns - substring between <i>start</i> and <i>end</i><br>
+
+<br><dt>
+
+ (string<<a name="index910"> <i>str1</i> <i>str2</i> &key :start1 :end1 :start2 :end2)<br>
+ (string<=<a name="index911"> <i>str1</i> <i>str2</i> &key :start1 :end1 :start2 :end2)<br>
+ (string=<a name="index912"> <i>str1</i> <i>str2</i> &key :start1 :end1 :start2 :end2)<br>
+ (string/=<a name="index913"> <i>str1</i> <i>str2</i> &key :start1 :end1 :start2 :end2)<br>
+ (string>=<a name="index914"> <i>str1</i> <i>str2</i> &key :start1 :end1 :start2 :end2)<br>
+ (string><a name="index915"> <i>str1</i> <i>str2</i> &key :start1 :end1 :start2 :end2)
+
+<dd>
+ <i>str1</i> - the first string to compare<br>
+ <i>str2</i> - the second string to compare<br>
+ :start1 - first substring starting offset<br>
+ :end1 - first substring ending offset + 1<br>
+ :start2 - second substring starting offset<br>
+ :end2 - second substring ending offset + 1<br>
+ returns - <code>t</code> if predicate is true, <code>nil</code> otherwise<br>
+ Note: case is significant with these comparison functions.
+
+<br>
+<br><dt>
+
+(string-lessp<a name="index916"> <i>str1</i> <i>str2</i> &key :start1 :end1 :start2 :end2)<br>
+(string-not-greaterp<a name="index917"> <i>str1</i> <i>str2</i> &key :start1 :end1 :start2 :end2)<br>
+(string-equalp<a name="index918"> <i>str1</i> <i>str2</i> &key :start1 :end1 :start2 :end2)<br>
+(string-not-equalp<a name="index919"> <i>str1</i> <i>str2</i> &key :start1 :end1 :start2 :end2)<br>
+(string-not-lessp<a name="index920"> <i>str1</i> <i>str2</i> &key :start1 :end1 :start2 :end2)<br>
+(string-greaterp <i>str1</i> <i>str2</i> &key :start1 :end1 :start2 :end2)
+
+<dd>
+ <i>str1</i> - the first string to compare<br>
+ <i>str2</i> - the second string to compare<br>
+ :start1 - first substring starting offset<br>
+ :end1 - first substring ending offset + 1<br>
+ :start2 - second substring starting offset<br>
+ :end2 - second substring ending offset + 1<br>
+ returns - <code>t</code> if predicate is true, <code>nil</code> otherwise<br>
+ Note: case is not significant with these comparison functions.
+
+<br>
+<br><dt>
+</dl>
+<p>
+<a name = "129"><h3>Character Functions</h3></a><a name="index921">
+<dl>
+<dt>
+ (char<a name="index922"> <i>string</i> <i>index</i>) - extract a character from a string
+<dd>
+ <i>string</i> - the string<br>
+ <i>index</i> - the string index (zero relative)<br>
+ returns - the ascii code of the character<br>
+
+<br><dt> (upper-case-p<a name="index923"> <i>chr</i>) - is this an upper case character?
+<dd>
+ <i>chr</i> - the character<br>
+ returns - <code>t</code> if the character is upper case, <code>nil</code> otherwise<br>
+
+<br><dt> (lower-case-p<a name="index924"> <i>chr</i>) - is this a lower case character?
+<dd>
+ <i>chr</i> - the character<br>
+ returns - <code>t</code> if the character is lower case, <code>nil</code> otherwise<br>
+
+<br><dt> (both-case-p<a name="index925"> <i>chr</i>) - is this an alphabetic (either case) character?
+<dd>
+ <i>chr</i> - the character<br>
+ returns - <code>t</code> if the character is alphabetic, <code>nil</code> otherwise<br>
+
+<br><dt> (digit-char-p<a name="index926"> <i>chr</i>) - is this a digit character?
+<dd>
+ <i>chr</i> - the character<br>
+ returns - the digit weight if character is a digit, <code>nil</code> otherwise<br>
+
+<br><dt> (char-code<a name="index927"> <i>chr</i>) - get the ascii code of a character
+<dd>
+ <i>chr</i> - the character<br>
+ returns - the ascii character code (integer)<br>
+
+<br><dt> (code-char<a name="index928"> <i>code</i>) - get the character with a specified ascii code
+<dd>
+ <i>code</i> - the ascii code (integer)<br>
+ returns - the character with that code or <code>nil</code><br>
+
+<br><dt> (char-upcase<a name="index929"> <i>chr</i>) - convert a character to upper case
+<dd>
+ <i>chr</i> - the character<br>
+ returns - the upper case character<br>
+
+<br><dt> (char-downcase<a name="index930"> <i>chr</i>) - convert a character to lower case
+<dd>
+ <i>chr</i> - the character<br>
+ returns - the lower case character<br>
+
+<br><dt> (digit-char<a name="index931"> <i>n</i>) - convert a digit weight to a digit
+<dd>
+ <i>n</i> - the digit weight (integer)<br>
+ returns - the digit character or <code>nil</code><br>
+
+<br><dt> (char-int<a name="index932"> <i>chr</i>) - convert a character to an integer
+<dd>
+ <i>chr</i> - the character<br>
+ returns - the ascii character code<br>
+
+<br><dt> (int-char<a name="index933"> <i>int</i>) - convert an integer to a character
+<dd>
+ <i>int</i> - the ascii character code<br>
+ returns - the character with that code<br>
+
+<br><dt>
+
+ (char<<a name="index934"> <i>chr1</i> <i>chr2</i>...)<br>
+ (char<=<a name="index935"> <i>chr1</i> <i>chr2</i>...)<br>
+ (char=<a name="index936"> <i>chr1</i> <i>chr2</i>...)<br>
+ (char/=<a name="index937"> <i>chr1</i> <i>chr2</i>...)<br>
+ (char>=<a name="index938"> <i>chr1</i> <i>chr2</i>...)<br>
+ (char><a name="index939"> <i>chr1</i> <i>chr2</i>...)
+
+<dd>
+ <i>chr1</i> - the first character to compare<br>
+ <i>chr2</i> - the second character(s) to compare<br>
+ returns - <code>t</code> if predicate is true, <code>nil</code> otherwise<br>
+ Note: case is significant with these comparison functions.
+
+<br>
+<br><dt>
+
+(char-lessp<a name="index940"> <i>chr1</i> <i>chr2</i>...)<br>
+(char-not-greaterp<a name="index941"> <i>chr1</i> <i>chr2</i>...)<br>
+(char-equalp<a name="index942"> <i>chr1</i> <i>chr2</i>...)<br>
+(char-not-equalp<a name="index943"> <i>chr1</i> <i>chr2</i>...)<br>
+(char-not-lessp<a name="index944"> <i>chr1</i> <i>chr2</i>...)<br>
+(char-greaterp<a name="index945"> <i>chr1</i> <i>chr2</i>...)
+
+<dd>
+<i>chr1</i> - the first string to compare<br>
+<i>chr2</i> - the second string(s) to compare<br>
+returns - <code>t</code> if predicate is true, <code>nil</code> otherwise<br>
+
+<br><dt>
+ Note: case is not significant with these comparison functions.
+</dl>
+<p>
+<a name = "130"><h3>Input/Output Functions</h3></a><a name="index946">
+<dl>
+<dt>
+ (read<a name="index947"> [<i>stream</i> [<i>eof</i> [<i>rflag</i>]]]) - read an expression
+<dd>
+ <i>stream</i> - the input stream (default is standard input)<br>
+ <i>eof</i> - the value to return on end of file (default is <code>nil</code>)<br>
+ <i>rflag</i> - recursive read flag (default is <code>nil</code>)<br>
+ returns - the expression read<br>
+
+<br><dt> (print<a name="index948"> <i>expr</i> [<i>stream</i>]) - print an expression on a new line
+<dd>
+ <i>expr</i> - the expression to be printed<br>
+ <i>stream</i> - the output stream (default is standard output)<br>
+ returns - the expression<br>
+
+<br><dt> (prin1<a name="index949"> <i>expr</i> [<i>stream</i>]) - print an expression
+<dd>
+ <i>expr</i> - the expression to be printed<br>
+ <i>stream</i> - the output stream (default is standard output)<br>
+ returns - the expression<br>
+
+<br><dt> (princ<a name="index950"> <i>expr</i> [<i>stream</i>]) - print an expression without quoting
+<dd>
+ <i>expr</i> - the expressions to be printed<br>
+ <i>stream</i> - the output stream (default is standard output)<br>
+ returns - the expression<br>
+
+<br><dt> (pprint<a name="index951"> <i>expr</i> [<i>stream</i>]) - pretty print an expression
+<dd>
+ <i>expr</i> - the expressions to be printed<br>
+ <i>stream</i> - the output stream (default is standard output)<br>
+ returns - the expression<br>
+
+<br><dt> (terpri<a name="index952"> [<i>stream</i>]) - terminate the current print line
+<dd>
+ <i>stream</i> - the output stream (default is standard output)<br>
+ returns - <code>nil</code><br>
+
+<br><dt> (flatsize<a name="index953"> <i>expr</i>) - length of printed representation using prin1
+<dd>
+ <i>expr</i> - the expression<br>
+ returns - the length<br>
+
+<br><dt> (flatc<a name="index954"> <i>expr</i>) - length of printed representation using princ
+<dd>
+ <i>expr</i> - the expression<br>
+ returns - the length<br>
+
+<br><dt>
+</dl><a name = "131"><h3>The Format Function</h3></a><a name="index955">
+<dl>
+<dt>
+(format<a name="index956"> <i>stream</i> <i>fmt</i> <i>arg</i>...) - do formated
+output
+<dd>
+ <i>stream</i> - the output stream<br>
+ <i>fmt</i> - the format string<br>
+ <i>arg</i> - the format arguments<br>
+ returns - output string if <i>stream</i> is <code>nil</code>, <code>nil</code> otherwise<br>
+
+<br><dt>
+</dl>
+ The format string can contain characters that should be copied
+ directly to the output and formatting directives. The
+ formatting directives are:
+<blockquote>
+~A - print next argument using princ<br>
+
+~S - print next argument using prin1<br>
+
+~% - start a new line<br>
+
+~~ - print a tilde character<br>
+
+</blockquote>
+<p>
+<a name = "132"><h3>File I/O Functions</h3></a><a name="index957">
+Note that files are ordinarily opened as text. Binary files (such as standard midi files) must be opened with <code>open-binary</code> on non-unix systems.
+<dl>
+<dt>
+ (open<a name="index958"> <i>fname</i> &key :direction) - open a file stream
+<dd>
+ <i>fname</i> - the file name string or symbol<br>
+ :direction - :input or :output (default is :input)<br>
+ returns - a stream<br>
+
+<br><dt>
+ (open-binary<a name="index959"><a name="index960"> <i>fname</i> &key :direction) - open a binary file stream
+<dd>
+ <i>fname</i> - the file name string or symbol<br>
+ :direction - :input or :output (default is :input)<br>
+ returns - a stream<br>
+
+<br><dt> (close<a name="index961"> <i>stream</i>) - close a file stream
+<dd>
+ <i>stream</i> - the stream<br>
+ returns - <code>nil</code><br>
+
+<br><dt> (read-char<a name="index962"> [<i>stream</i>]) - read a character from a stream
+<dd>
+ <i>stream</i> - the input stream (default is standard input)<br>
+ returns - the character<br>
+
+<br><dt> (peek-char<a name="index963"> [<i>flag</i> [<i>stream</i>]]) - peek at the next character
+<dd>
+ <i>flag</i> - flag for skipping white space (default is <code>nil</code>)<br>
+ <i>stream</i> - the input stream (default is standard input)<br>
+ returns - the character (integer)<br>
+
+<br><dt> (write-char<a name="index964"> <i>ch</i> [<i>stream</i>]) - write a character to a stream
+<dd>
+ <i>ch</i> - the character to write<br>
+ <i>stream</i> - the output stream (default is standard output)<br>
+ returns - the character<br>
+
+<br><dt> (read-int<a name="index965"> [<i>stream</i> [<i>length</i>]]) - read a binary integer from a stream
+<dd>
+ <i>stream</i> - the input stream (default is standard input)<br>
+ <i>length</i> - the length of the integer in bytes (default is 4)<br>
+ returns - the integer<br>
+Note: Integers are assumed to be big-endian (high-order byte first) and
+signed, regardless of the platform. To read little-endian format, use a
+negative number for the length, e.g. -4 indicates a 4-bytes, low-order
+byte first. The file should be opened in binary mode.<br>
+
+<br><dt> (write-int<a name="index966"> <i>ch</i> [<i>stream</i> [<i>length</i>]]) - write a binary integer to a stream
+<dd>
+ <i>ch</i> - the character to write<br>
+ <i>stream</i> - the output stream (default is standard output)<br>
+ <i>length</i> - the length of the integer in bytes (default is 4)<br>
+ returns - the integer<br>
+Note: Integers are assumed to be big-endian (high-order byte first) and
+signed, regardless of the platform. To write in little-endian format, use a
+negative number for the length, e.g. -4 indicates a 4-bytes, low-order
+byte first. The file should be opened in binary mode.<br>
+
+<br><dt> (read-float<a name="index967"> [<i>stream</i> [<i>length</i>]]) - read a binary floating-point number from a stream
+<dd>
+ <i>stream</i> - the input stream (default is standard input)<br>
+ <i>length</i> - the length of the float in bytes (default is 4, legal values are -4, -8, 4, and 8)<br>
+ returns - the integer<br>
+Note: Floats are assumed to be big-endian (high-order byte first) and
+signed, regardless of the platform. To read little-endian format, use a
+negative number for the length, e.g. -4 indicates a 4-bytes, low-order
+byte first. The file should be opened in binary mode.<br>
+
+<br><dt> (write-float<a name="index968"> <i>ch</i> [<i>stream</i> [<i>length</i>]]) - write a binary floating-point number to a stream
+<dd>
+ <i>ch</i> - the character to write<br>
+ <i>stream</i> - the output stream (default is standard output)<br>
+ <i>length</i> - the length of the float in bytes (default is 4, legal values are -4, -8, 4, and 8)<br>
+ returns - the integer<br>
+Note: Floats are assumed to be big-endian (high-order byte first) and
+signed, regardless of the platform. To write in little-endian format, use a
+negative number for the length, e.g. -4 indicates a 4-bytes, low-order
+byte first. The file should be opened in binary mode.<br>
+
+<br><dt> (read-line<a name="index969"> [<i>stream</i>]) - read a line from a stream
+<dd>
+ <i>stream</i> - the input stream (default is standard input)<br>
+ returns - the string<br>
+
+<br><dt> (read-byte<a name="index970"> [<i>stream</i>]) - read a byte from a stream
+<dd>
+ <i>stream</i> - the input stream (default is standard input)<br>
+ returns - the byte (integer)<br>
+
+<br><dt> (write-byte<a name="index971"> <i>byte</i> [<i>stream</i>]) - write a byte to a stream
+<dd>
+ <i>byte</i> - the byte to write (integer)<br>
+ <i>stream</i> - the output stream (default is standard output)<br>
+ returns - the byte (integer)<br>
+
+<br><dt>
+</dl><a name = "133"><h3>String Stream Functions</h3></a><a name="index972">
+ These functions operate on unnamed streams. An unnamed output
+ stream collects characters sent to it when it is used as the
+ destination of any output function. The functions
+<code>get-output-stream-string</code> and string or a list of characters.
+<p>
+An unnamed input stream is setup with the
+ <code>make-string-input-stream</code> function and returns each character of the string when
+ it is used as the source of any input function.
+<p>
+<dl>
+<dt>
+<br><dt>
+ (make-string-input-stream<a name="index973"> <i>str</i> [<i>start</i> [<i>end</i>]])
+<dd>
+ <i>str</i> - the string<br>
+ <i>start</i> - the starting offset<br>
+ <i>end</i> - the ending offset + 1<br>
+ returns - an unnamed stream that reads from the string<br>
+
+<br><dt> (make-string-output-stream)<a name="index974">
+<dd>
+ returns - an unnamed output stream<br>
+
+<br><dt> (get-output-stream-string<a name="index975"> <i>stream</i>)
+<dd>
+ <i>stream</i> - the output stream<br>
+ returns - the output so far as a string<br>
+
+ Note: the output stream is emptied by this function
+<br>
+<br><dt> (get-output-stream-list<a name="index976"> <i>stream</i>)
+<dd>
+ <i>stream</i> - the output stream<br>
+ returns - the output so far as a list<br>
+
+ Note: the output stream is emptied by this function
+<br>
+<br><dt>
+</dl>
+<p>
+<a name = "134"><h3>System Functions</h3></a><a name="index977">
+Note: the <code>load</code> function first tries to load a file from the current directory. A <code>.lsp</code> extension is added if there is not already an alphanumeric extension following a period. If that fails, XLisp searches the path, which is obtained from the XLISPPATH environment variable in Unix and HKEY_LOCAL_MACHINE\SOFTWARE\CMU\Nyquist\XLISPPATH under Win32. (The Macintosh version has no search path.)
+<p>
+<dl>
+<dt>
+ (load<a name="index978"> <i>fname</i> &key :verbose :print) - load a source file
+<dd>
+ <i>fname</i> - the filename string or symbol<br>
+ :verbose - the verbose flag (default is t)<br>
+ :print - the print flag (default is <code>nil</code>)<br>
+ returns - the filename<br>
+
+<br><dt> (save<a name="index979"> <i>fname</i>) - save workspace to a file
+<dd>
+ <i>fname</i> - the filename string or symbol<br>
+ returns - <code>t</code> if workspace was written, <code>nil</code> otherwise<br>
+
+<br><dt> (restore<a name="index980"> <i>fname</i>) - restore workspace from a file
+<dd>
+ <i>fname</i> - the filename string or symbol<br>
+ returns - <code>nil</code> on failure, otherwise never returns<br>
+
+<br><dt> (dribble<a name="index981"> [<i>fname</i>]) - create a file with a transcript of a session
+<dd>
+ <i>fname</i> - file name string or symbol
+ (if missing, close current transcript)<br>
+ returns - <code>t</code> if the transcript is opened, <code>nil</code> if it is closed<br>
+
+<br><dt> (gc<a name="index982">) - force garbage collection
+<dd>
+ returns - <code>nil</code><br>
+
+<br><dt> (expand<a name="index983"> <i>num</i>) - expand memory by adding segments
+<dd>
+ <i>num</i> - the number of segments to add<br>
+ returns - the number of segments added<br>
+
+<br><dt> (alloc<a name="index984"> <i>num</i>) - change number of nodes to allocate in each segment
+<dd>
+ <i>num</i> - the number of nodes to allocate<br>
+ returns - the old number of nodes to allocate<br>
+
+<br><dt> (room<a name="index985">) - show memory allocation statistics
+<dd>
+ returns - <code>nil</code><br>
+
+<br><dt> (type-of<a name="index986"> <i>expr</i>) - returns the type of the expression
+<dd>
+ <i>expr</i> - the expression to return the type of<br>
+ returns - <code>nil</code> if the value is <code>nil</code> otherwise one of the symbols:<br>
+<dl><dd>
+ SYMBOL - for symbols<br>
+ OBJECT - for objects<br>
+ CONS - for conses<br>
+ SUBR - for built-in functions<br>
+ FSUBR - for special forms<br>
+ CLOSURE - for defined functions<br>
+ STRING - for strings<br>
+ FIXNUM - for integers<br>
+ FLONUM - for floating point numbers<br>
+ CHARACTER - for characters<br>
+ FILE-STREAM - for file pointers<br>
+ UNNAMED-STREAM - for unnamed streams<br>
+ ARRAY - for arrays<br>
+</dl>
+
+<br><dt> (peek<a name="index987"> <i>addrs</i>) - peek at a location in memory
+<dd>
+ <i>addrs</i> - the address to peek at (integer)<br>
+ returns - the value at the specified address (integer)<br>
+
+<br><dt> (poke<a name="index988"> <i>addrs</i> <i>value</i>) - poke a value into memory
+<dd>
+ <i>addrs</i> - the address to poke (integer)<br>
+ <i>value</i> - the value to poke into the address (integer)<br>
+ returns - the value<br>
+
+<br><dt> (address-of<a name="index989"> <i>expr</i>) - get the address of an xlisp node
+<dd>
+ <i>expr</i> - the node<br>
+ returns - the address of the node (integer)<br>
+
+<br><dt> (exit<a name="index990">) - exit xlisp
+<dd>
+ returns - never returns<br>
+
+<br><dt> (setup-console<a name="index991"><a name="index992">) - set default console attributes
+<dd>
+ returns - NIL<br>
+Note: Under Windows, Nyquist normally starts up in a medium-sized console window with black text and a white background, with a window title of ``Nyquist.'' This is normally accomplished by calling <code>setup-console</code> in <code>system.lsp</code>. In Nyquist, you can avoid this behavior by setting <code>*setup-console*</code> to NIL in your <code>init.lsp</code> file. If <code>setup-console</code> is not called, Nyquist uses standard input and output as is. This is what you want if you are running Nyquist inside of emacs, for example.<a name="index993"><br>
+
+</dl><a name = "135"><h3>File I/O Functions</h3></a><a name="index994"><a name = "136"><h4>Input from a File</h4></a><a name="index995">To open a file for input, use the <code>open</code> function with the keyword
+argument <code>:direction</code> set to <code>:input</code>. To open a file for output,
+use the <code>open</code> function with the keyword argument <code>:direction</code> set
+to <code>:output</code>. The <code>open</code> function takes a single required argument which
+is the name of the file to be opened. This name can be in the form of a
+string or a symbol. The <code>open</code> function returns an object of type
+<code>FILE-STREAM</code> if it succeeds in opening the specified file. It returns the
+value <code>nil</code> if it fails. In order to manipulate the file, it is
+necessary to save the value returned by the <code>open</code> function. This is
+usually done by assigning it to a variable with the <code>setq</code> special form or by
+binding it using <code>let</code> or <code>let*</code>. Here is an example:
+<pre>
+(setq fp (open "init.lsp" :direction :input))
+</pre>
+
+ Evaluating this expression will result in the file <code>init.lsp</code>
+ being opened. The file object that will be returned by the <code>open</code>
+ function will be assigned to the variable <code>fp</code>.
+<p>
+ It is now possible to use the file for input. To read an
+ expression from the file, just supply the value of the <code>fp</code>
+ variable as the optional <i>stream</i> argument to <code>read</code>.
+<pre>
+(read fp)
+</pre>
+
+ Evaluating this expression will result in reading the first
+ expression from the file <code>init.lsp</code>. The expression will be
+ returned as the result of the <code>read</code> function. More expressions
+ can be read from the file using further calls to the <code>read</code>
+ function. When there are no more expressions to read, the <code>read</code>
+ function will return <code>nil</code> (or whatever value was supplied as the
+ second argument to <code>read</code>).
+<p>
+ Once you are done reading from the file, you should close it.
+ To close the file, use the following expression:
+<pre>
+(close fp)
+</pre>
+
+ Evaluating this expression will cause the file to be closed.
+<p>
+<a name = "137"><h4>Output to a File</h4></a><a name="index996"> Writing to a file is pretty much the same as reading from one.
+ You need to open the file first. This time you should use the
+ <code>open</code> function to indicate that you will do output to the file.
+ For example:
+<pre>
+(setq fp (open "test.dat" :direction :output))
+</pre>
+
+ Evaluating this expression will open the file <code>test.dat</code> for
+ output. If the file already exists, its current contents will
+ be discarded. If it doesn't already exist, it will be created.
+ In any case, a <code>FILE-STREAM</code> object will be returned by the <code>OPEN</code>
+ function. This file object will be assigned to the <code>fp</code>
+ variable.
+<p>
+ It is now possible to write to this file by supplying the value
+ of the <code>fp</code> variable as the optional <i>stream</i> parameter in the <code>print</code> function.
+<pre>
+(print "Hello there" fp)
+</pre>
+
+ Evaluating this expression will result in the string ``Hello
+ there'' being written to the file <code>test.dat</code>. More data can be
+ written to the file using the same technique.
+<p>
+ Once you are done writing to the file, you should close it.
+ Closing an output file is just like closing an input file.
+<pre>
+(close fp)
+</pre>
+
+ Evaluating this expression will close the output file and make
+ it permanent.
+<p>
+<a name = "138"><h4>A Slightly More Complicated File Example</h4></a> This example shows how to open a file, read each Lisp expression
+ from the file and print it. It demonstrates the use of files
+ and the use of the optional <i>stream</i> argument to the <code>read</code>
+ function.
+<pre>
+(do* ((fp (open "test.dat" :direction :input))
+ (ex (read fp) (read fp)))
+ ((null ex) nil)
+ (print ex))
+</pre>
+
+<p>
+
+<hr>
+<a href = "part14.html">Previous Section</a> | <a href = "indx.html">Next Section (Index)</a> | <a href = "home.html#toc">Table of Contents</a> | <a href = "home.html">Title Page</a>
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/manual/sal.htm b/docsrc/xlisp/xlisp-doc/manual/sal.htm new file mode 100644 index 0000000..c3eeb30 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/manual/sal.htm @@ -0,0 +1,160 @@ +<html><head>
+
+<title>SAL</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="xlisp-man-index.htm">XLISP</a>
+
+<hr>
+
+<h1>SAL</h1>
+
+<hr>
+
+<h2>Data Types</h2>
+
+<hr>
+
+<p>Data types used in SAL and XLISP:</p>
+
+<p><table cellpadding="0" cellspacing="2"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td colspan="2"></td>
+ <td align="center" colspan="2">SAL</td>
+ <td align="center" colspan="2">XLISP</td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr>integer:</nobr></td>
+ <td><nobr> </nobr></td>
+ <td align="center" class="button" colspan="2"><nobr><code>1</code></nobr></td>
+ <td align="center" class="button" colspan="2"><nobr><code>1</code></nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr>float:</nobr></td>
+ <td><nobr> </nobr></td>
+ <td align="center" class="button" colspan="2"><nobr><code>1.0</code></nobr></td>
+ <td align="center" class="button" colspan="2"><nobr><code>1.0</code></nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr>string:</nobr></td>
+ <td><nobr> </nobr></td>
+ <td align="center" class="button" colspan="2"><nobr><code>"hello"</code></nobr></td>
+ <td align="center" class="button" colspan="2"><nobr><code>"hello"</code></nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr>symbol:</nobr></td>
+ <td><nobr> </nobr></td>
+ <td align="center" class="button" colspan="2"><nobr><code><font color="#0000CC">name</font></code></nobr></td>
+ <td align="center" class="button" colspan="2"><nobr><code><font color="#0000CC">name</font></code></nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr>keyword:</nobr></td>
+ <td><nobr> </nobr></td>
+ <td align="center" class="button" colspan="2"><nobr><code><font color="#0000CC">symbol</font>:</code></nobr></td>
+ <td align="center" class="button" colspan="2"><nobr><code>:<font color="#0000CC">symbol</font></code></nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr>list:</nobr></td>
+ <td><nobr> </nobr></td>
+ <td align="center" class="button" colspan="2"><nobr><code>{<font color="#0000CC">item-1 item-2</font> ...}</code></nobr></td>
+ <td align="center" class="button" colspan="2"><nobr><code>(<font color="#0000CC">item-1 item-2</font> ...)</code></nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr>array:</nobr></td>
+ <td><nobr> </nobr></td>
+ <td align="center" class="button" colspan="2"><nobr><code><font color="#0000CC">array</font>[<font color="#0000CC">index</font>]</code></nobr></td>
+ <td align="center" class="button" colspan="2"><nobr><code>(aref <font color="#0000CC">array index</font>)</code></nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr>boolean:</nobr></td>
+ <td><nobr> </nobr></td>
+ <td align="center" class="button"><nobr><code><font color="#008844">#t</font></code></nobr></td>
+ <td align="center" class="button"><nobr><code><font color="#AA0000">#f</font></code></nobr></td>
+ <td align="center" class="button"><nobr><code> <font color="#008844">t</font> </code></nobr></td>
+ <td align="center" class="button"><nobr><code><font color="#AA0000">nil</font></code></nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>Data types with different concepts:</p>
+
+<p>SAL:</p>
+
+<ul>
+<li>expressions - evaluated to produce a return value</li>
+<li>statements - evaluated for side-effects</li>
+</ul>
+
+<p>XLISP:</p>
+
+<ul>
+<li>character - a single ASCII character</li>
+<li>object - the XLISP object system</li>
+<li>stream - data type of unknown length</li>
+<li>subr - built-in function</li>
+<li>fsubr - special form</li>
+<li>closure - user defined function</li>
+</ul>
+
+<p>A function to print the Lisp code, produced by the SAL compiler, to the
+screen:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">test</font> (string)
+ (if (not (stringp string))
+ (error "not a string" string)
+ (pprint (third (second (sal-compile string nil nil "<console>"))))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<br>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/manual/xlisp-man-033.htm b/docsrc/xlisp/xlisp-doc/manual/xlisp-man-033.htm new file mode 100644 index 0000000..223e3c6 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/manual/xlisp-man-033.htm @@ -0,0 +1,356 @@ +<html><head><title>XLISP: An Object-oriented Lisp</title></head>
+
+<style type="text/css">
+ pre.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+ td.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+</style>
+
+<body>
+
+<a href="../start.htm">XLISP</a> >
+<a href="xlisp-man-index.htm">XLISP 2.0</a> -
+<a href="contents.htm#34">Contents</a> -
+<a href="../reference/reference-index.htm">Reference</a> -
+<a href="xlisp-man-032.htm">Previous</a> |
+<a href="xlisp-man-index.htm">Next</a>
+
+<hr>
+
+<h1>33 Nyquist Functions</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#predicate-functions">Predicate Functions</a></nobr></li>
+<ul>
+<li><nobr><a href="#filep">filep</a> - is this a file ?</nobr></li>
+</ul>
+<li><nobr><a href="#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+<ul>
+<li><nobr><a href="#rrandom">rrandom</a> - compute a random real number between 0 and 1 inclusive</li>
+</ul>
+<li><nobr><a href="#string-functions">String Functions</a></nobr></li>
+<ul>
+<li><nobr><a href="#string-search">string-search</a> - search for pattern in string</nobr></li>
+</ul>
+<li><nobr><a href="#file-io-functions">File I/O Functions</a></nobr></li>
+<ul>
+<li><nobr><a href="#open-binary">open-binary</a> - open a binary file stream</nobr></li>
+<li><nobr><a href="#setdir">setdir</a> - set current directory</nobr></li>
+<li><nobr><a href="#listdir">listdir</a> - get a directory listing</nobr></li>
+<li><nobr><a href="#get-temp-path">get-temp-path</a> - get a path where a temporary file can be created</nobr></li>
+<li><nobr><a href="#read-int">read-int</a> - read a binary integer from a stream</nobr></li>
+<li><nobr><a href="#write-int">write-int</a> - write a binary integer to a stream</nobr></li>
+<li><nobr><a href="#read-float">read-float</a> - read a binary floating-point number from a stream</nobr></li>
+<li><nobr><a href="#write-float">write-float</a> - write a binary floating-point number to a stream</nobr></li>
+</ul>
+<li><nobr><a href="#system-functions">System Functions</a></nobr></li>
+<ul>
+<li><nobr><a href="#info">info</a> - show information about memory usage</nobr></li>
+<li><nobr><a href="#bigendiap">bigendiap</a> - is this a big-endian machine ?</nobr></li>
+<li><nobr><a href="#setup-console">setup-console</a> - set default console attributes</nobr></li>
+<li><nobr><a href="#echoenabled">echoenabled</a> - turn console input echoing on or off</nobr></li>
+</ul>
+<li><nobr><a name="11" href="#profiling">Profiling</a></nobr></li>
+<ul>
+<li><nobr><a href="#profile">profile</a> - turn profiling on or off</nobr></li>
+</ul>
+</ol>
+
+<p><b>Note:</b> if you're interested in *all* functions added by Nyquist to
+the XLISP language, I suggest you download the Nyquist manual from:</p>
+
+<ul>
+<li><a href="http://www.cs.cmu.edu/~music/music.software.html"
+>http://www.cs.cmu.edu/~music/music.software.html</a></li>
+</ul>
+
+<p>The following is a list of all Nyquist functions I have found in the
+XLISP section of the <nobr>Nyquist 2.36</nobr> manual but I cannot even
+guarantee that the list is complete. I'm willing to add more functions here
+if you find that some are missing but the best information source is the
+Nyquist manual itself. Roger is always a step ahead and I do not want to
+spread obsolete or wrong information.</p>
+
+<a name="predicate-functions"></a>
+
+<hr>
+
+<h2>Predicate Functions</h2>
+
+<hr>
+
+<a name="filep"></a>
+
+<dl>
+
+<dt>(filep <i>expr</i>) - is this a <nobr>file ?</nobr></dt>
+<dd><i>expr</i> - the expression to check<br>
+returns - T if the value is an object, NIL otherwise</dd>
+
+</dl>
+
+<p><nobr> <a href="#top">Back to Top</a></nobr></p>
+
+<a name="debugging-functions"></a>
+
+<hr>
+
+<h2>Arithmetic Functions</h2>
+
+<hr>
+
+<a name="rrandom"></a>
+
+<dl>
+
+<dt>(rrandom) - compute a random real number between 0 and 1 inclusive</dt>
+<dd>returns - a random floating point number</dd>
+
+</dl>
+
+<p><nobr> <a href="#top">Back to Top</a></nobr></p>
+
+<a name="string-functions"></a>
+
+<hr>
+
+<h2>String Functions</h2>
+
+<hr>
+
+<a name="string-search"></a>
+
+<dl>
+
+<dt>(string-search <i>pat</i> <i>str</i> &key :start :end)
+- search for pattern in string</dt><dd>
+<i>pat</i> - a string to search for<br>
+<i>str</i> - the string to be searched<br>
+:start - the starting offset in str<br>
+:end - the ending offset + 1<br>
+returns - index of <i>pat</i> in <i>str</i> or NIL if not found</dd>
+
+</dl>
+
+<p><nobr> <a href="#top">Back to Top</a></nobr></p>
+
+<a name="file-io-functions"></a>
+
+<hr>
+
+<h2>File I/O Functions</h2>
+
+<hr>
+
+<a name="open-binary"></a>
+
+<p><b>Note:</b> Files are ordinarily opened as text. Binary files [such
+as standard MIDI files] must be opened with 'open-binary' on non-unix
+systems.</p>
+
+<dl>
+
+<dt>(open-binary <i>fname</i> &key :direction) - open a binary file stream</dt>
+<dd><i>fname</i> - the file name string or symbol<br>
+:direction - :input or :output [default is :input]<br>
+returns - a stream</dd>
+
+<a name="setdir"></a><br>
+
+<dt>(setdir <i>path</i>) - set current directory</dt>
+<dd><i>path</i> - the path of the new directory<br>
+returns - the resulting full path, e.g. (setdir ".") gets the current
+working directory, or NIL if an error occurs</dd>
+
+<a name="listdir"></a><br>
+
+<dt>(listdir <i>path</i>) - get a directory listing</dt>
+<dd><i>path</i> - the path of the directory to be listed<br>
+returns - list of filenames in the directory</dd>
+
+<a name="get-temp-path"></a><br>
+
+<dt>(get-temp-path) - get a path where a temporary file can be created</dt>
+<dd>returns - the resulting full path as a string</dd>
+
+</dl>
+
+<p><b>Note:</b> Under Windows, the 'get-temp-path' function is based on
+environment variables. If XLISP is running as a sub-process to Java, the
+environment may not exist, in which case the default result is the
+unfortunate choice 'c:\windows\'.</p>
+
+<dl>
+
+<a name="read-int"></a>
+
+<dt>(read-int [<i>stream</i> [<i>length</i>]]) - read a binary integer from a stream</dt>
+<dd><i>stream</i> - the input stream [default is standard input]<br>
+<i>length</i> - the length of the integer in bytes [default is 4]<br>
+returns - the integer</dd>
+
+<a name="write-int"></a><br>
+
+<dt>(write-int <i>ch</i> [<i>stream</i> [<i>length</i>]]) - write a binary integer to a stream</dt>
+<dd><i>ch</i> - the character to write<br>
+<i>stream</i> - the output stream [default is standard output]<br>
+<i>length</i> - the length of the integer in bytes [default is 4]<br>
+returns - the integer</dd>
+
+<a name="read-float"></a><br>
+
+<dt>(read-float [<i>stream</i> [<i>length</i>]]) - read a binary
+floating-point number from a stream</dt>
+<dd><i>stream</i> - the input stream (default is standard input)<br>
+<i>length</i> - the length of the float in bytes [default is 4,
+legal values are -4, -8, 4, and 8]<br>
+returns - the float</dd>
+
+<a name="write-float"></a><br>
+
+<dt>(write-float <i>ch</i> [<i>stream</i> [<i>length</i>]]) - write a binary floating-point number to a stream</dt>
+<dd><i>ch</i> - the character to write<br>
+<i>stream</i> - the output stream [default is standard output]<br>
+<i>length</i> - the length of the float in bytes [default is 4,
+legal values are -4, -8, 4, and 8]<br>
+returns - the float</dd>
+
+</dl>
+
+<p><b>Note:</b> Integers and floats are assumed to be big-endian [high-order
+byte first] and signed, regardless of the platform. To read little-endian
+format, use a negative number for the length, e.g. '-4' indicates a 4-bytes,
+low-order byte first. The file should be opened in binary mode.</p>
+
+<p><nobr> <a href="#top">Back to Top</a></nobr></p>
+
+<a name="system-functions"></a>
+
+<hr>
+
+<h2>System Functions</h2>
+
+<hr>
+
+<p><b>Note:</b> in Nyquist, the XLISP
+<a href="../reference/load.htm">load</a> function first tries to
+load a file from the current directory. A '.lsp' extension is added if there
+is not already an alphanumeric extension following a period. If that fails,
+XLISP searches the path, which is obtained from the XLISPPATH environment
+variable in Unix and HKEY_LOCAL_MACHINE\SOFTWARE\CMU\Nyquist\XLISPPATH under
+Win32. [The Macintosh version has no search path.]</p>
+
+<a name="info"></a>
+
+<dl>
+<dt>(info) - show information about memory usage.</dt>
+<dd>returns - NIL</dd>
+</dl>
+
+<a name="bigendiap"></a>
+
+<dl>
+<dt>(bigendiap) - is this a big-endian <nobr>machine ?</nobr></dt>
+<dd>returns - T if this a big-endian architecture, storing the high-order
+byte of an integer at the lowest byte address of the integer, otherwise
+NIL.</dd>
+</dl>
+
+<p><b>Note:</b> Under Windows, Nyquist normally starts up in a medium-sized
+console window with black text and a white background, with a window title
+of "Nyquist." This is normally accomplished by calling 'setup-console' in
+'system.lsp'. In Nyquist, you can avoid this behavior by setting
+*setup-console* to NIL in your 'init.lsp' file. If 'setup-console' is not
+called, Nyquist uses standard input and output as is. This is what you want
+if you are running Nyquist inside of emacs, for example.</p>
+
+<a name="setup-console"></a>
+
+<dl>
+<dt>(setup-console) - set default console attributes</dt>
+<dd>returns - NIL</dd>
+</dl>
+
+<p><b>Note:</b> The 'echoenabled' function is only implemented under Linux
+and <nobr>Mac OS X.</nobr> If Nyquist I/O is redirected through pipes, the
+Windows version does not echo the input, but the Linux and Mac versions do.
+You can turn off echoing with this function. Under windows it is defined to
+do nothing.</p>
+
+<a name="echoenabled"></a>
+
+<dl>
+<dt>(echoenabled <i>flag</i>) - turn console input echoing on or off</dt>
+<dd><i>flag</i> - T to enable echo, NIL to disable<br>
+returns - NIL</dd>
+</dl>
+
+<p><nobr> <a href="#top">Back to Top</a></nobr></p>
+
+<a name="profiling"></a>
+
+<hr>
+
+<h1>Profiling</h1>
+
+<hr>
+
+<p>The Xlisp 2.0 release has been extended with a profiling facility, which
+counts how many times and where
+<a href="../reference/eval.htm">eval</a> is executed. A separate
+count is maintained for each named function, closure, or macro, and a count
+indicates an <a href="../reference/eval.htm">eval</a> in the
+immediately [lexically] enclosing named function, closure, or macro. Thus,
+the count gives an indication of the amount of time spent in a function, not
+counting nested function calls.</p>
+
+<p>The list of all functions executed is maintained on the global *profile*
+variable. These functions in turn have *profile* properties, which maintain
+the counts. The profile system merely increments counters and puts symbols
+on the *profile* list. It is up to the user to initialize data and gather
+results. Profiling is turned on or off with the 'profile' function.</p>
+
+<a name="profile"></a>
+
+<dl>
+<dt>(profile <i>flag</i>) - turn profiling on or off</dt>
+<dd><i>flag</i> - NIL turns profiling off, otherwise on<br>
+returns - the previous state of profiling</dd>
+</dl>
+
+<p>Unfortunately, methods cannot be profiled with this facility.</p>
+
+<p>[Nyquist sources: xlsys.c, xleval.c]</p>
+
+<p> <a href="#top">Back to Top</a></p>
+
+<hr>
+
+<a href="../start.htm">XLISP</a> >
+<a href="xlisp-man-index.htm">XLISP 2.0</a> -
+<a href="contents.htm#34">Contents</a> -
+<a href="../reference/reference-index.htm">Reference</a> -
+<a href="xlisp-man-032.htm">Previous</a> |
+<a href="xlisp-man-index.htm">Next</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/manual/xlisp.htm b/docsrc/xlisp/xlisp-doc/manual/xlisp.htm new file mode 100644 index 0000000..c32b7a0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/manual/xlisp.htm @@ -0,0 +1,1256 @@ +<html><head>
+
+<title>XLISP 2.0</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #the-readtable08080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #the-readtable08080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #the-readtable08080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>XLISP 2.0</h1>
+
+<hr>
+
+<p><nobr><b>XLISP: An Object-oriented Lisp</b> </nobr> <nobr>Version
+2.0</nobr>, <nobr>February 6, 1988</nobr>, by <nobr>David Michael
+Betz</nobr>, <nobr>127 Taylor Road</nobr>, Peterborough, <nobr>NH
+03458</nobr></p>
+
+<p><nobr>Copyright (c) 1988</nobr>, by <nobr>David Michael Betz</nobr>,
+<nobr>All Rights Reserved</nobr>, Permission is granted for unrestricted
+<nobr>non-commercial use</nobr>.</p>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#introduction">Introduction</a></nobr></li>
+<li><nobr><a href="#a-note-from-the-author">A Note From The Author</a></nobr></li>
+<li><nobr><a href="#command-loop">Command Loop</a></nobr></li>
+<li><nobr><a href="#break-loop">Break Loop</a></nobr></li>
+<li><nobr><a href="#data-types">Data Types</a></nobr></li>
+<li><nobr><a href="#the-evaluator">The Evaluator</a></nobr></li>
+<li><nobr><a href="#lexical-conventions">Lexical Conventions</a></nobr></li>
+<li><nobr><a href="#the-readtable">The Readtable</a></nobr></li>
+<li><nobr><a href="#lambda-lists">Lambda Lists</a></nobr></li>
+<ul>
+<li><nobr><a href="#arguments">Arguments</a></nobr></li>
+<ul>
+<li><nobr><a href="#required-arguments">Required Arguments</a></nobr></li>
+<li><nobr><a href="#optional-arguments">Optional Arguments</a></nobr></li>
+<li><nobr><a href="#rest-argument">Rest Argument</a></nobr></li>
+<li><nobr><a href="#keyword-arguments">Keyword Arguments</a></nobr></li>
+<li><nobr><a href="#auxiliary-variables">Auxiliary Variables</a></nobr></li>
+</ul>
+<li><nobr><a href="#lambda-list-syntax">Lambda List Syntax</a></nobr></li>
+</ul>
+</ol>
+
+<a name="introduction"></a>
+
+<hr>
+
+<h2>1 Introduction</h2>
+
+<hr>
+
+<p>XLISP is an experimental programming language combining some of the
+features of Common Lisp with an object-oriented extension capability. It was
+implemented to allow experimentation with object-oriented programming on
+small computers. Implementations of XLISP run on virtually every operating
+system. XLISP is completely written in the programming language C and is
+easily extended with user written built-in functions and classes. It is
+available in source form to non-commercial users. Many Common Lisp functions
+are built into XLISP. In addition, XLISP defines the objects <a
+href="../reference/object.htm">object</a> and <a
+href="../reference/class.htm">class</a> as primitives. Object is the
+only class that has no superclass and hence is the root of the class
+hierarchy tree. Class is the class of which all classes are instances [it is
+the only object that is an instance of itself].</p>
+
+<p>This document is a brief description of XLISP. It assumes some knowledge
+of LISP and some understanding of the concepts of object-oriented
+programming. I recommend the book 'Lisp' by Winston and Horn and published
+by Addison Wesley for learning Lisp. The first edition of this book is based
+on MacLisp and the second edition is based on Common Lisp. You will probably
+also need a copy of 'Common Lisp, The Language' by Guy L. Steele, Jr.,
+published by Digital Press to use as a reference for some of the Common Lisp
+functions that are described only briefly in this document.</p>
+
+<p>A list with Lisp books and documents available for free in the internet
+can be found under <a href="../misc/links.htm">Lisp Links</a>.</p>
+
+<p><nobr> <a href="#top">Back to Top</a></nobr></p>
+
+<a name="a-note-from-the-author"></a>
+
+<hr>
+
+<h2>2 A Note From The Author</h2>
+
+<hr>
+
+<p>If you have any problems with XLISP, feel free to contact me [David Betz]
+for help or advice. Please remember that since XLISP is available in source
+form in a high level language, many users have been making versions
+available on a variety of machines. If you call to report a problem with a
+specific version, I may not be able to help you if that version runs on a
+machine to which I don't have access. Please have the version number of the
+version that you are running readily accessible before calling me.</p>
+
+<p>If you find a bug in XLISP, first try to fix the bug yourself using the
+source code provided. If you are successful in fixing the bug, send the bug
+report along with the fix to me. If you don't have access to a C compiler or
+are unable to fix a bug, please send the bug report to me and I'll try to
+fix it.</p>
+
+<p>Any suggestions for improvements will be welcomed. Feel free to extend
+the language in whatever way suits your needs. However,</p>
+
+<p><div class="box">
+
+<p><b>PLEASE DO NOT RELEASE ENHANCED VERSIONS WITHOUT CHECKING WITH ME
+FIRST!!</b></p>
+
+</div></p>
+
+<p>I would like to be the clearing house for new features added to XLISP. If
+you want to add features for your own personal use, go ahead. But, if you
+want to distribute your enhanced version, contact me first. Please remember
+that the goal of XLISP is to provide a language to learn and experiment with
+LISP and object-oriented programming on small computers. I don't want it to
+get so big that it requires megabytes of memory to run.</p>
+
+<p>The official XLISP homepage is:</p>
+
+<ul>
+<li><a href="http://www.mv.com/ipusers/xlisper/">http://www.mv.com/ipusers/xlisper/</a></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="command-loop"></a>
+
+<hr>
+
+<h2>3 Command Loop</h2>
+
+<hr>
+
+<p>When XLISP is started, it first tries to load the workspace 'xlisp.wks'
+from the current directory. If that file doesn't exist, XLISP builds an
+initial workspace, empty except for the built-in functions and symbols. Then
+XLISP attempts to load 'init.lsp' from the current directory. It then loads
+any files named as parameters on the command line [after appending '.lsp' to
+their names].</p>
+
+<p>XLISP then issues the following prompt:</p>
+
+<pre class="example">
+>
+</pre>
+
+<p>This indicates that XLISP is waiting for an expression to be typed. When
+a complete expression has been entered, XLISP attempts to evaluate that
+expression. If the expression evaluates successfully, XLISP prints the
+result and then returns to the initial prompt waiting for another expression
+to be typed.</p>
+
+<a name="interactive-programming"></a>
+
+<p><div class="box">
+
+<p><b>Interactive Programming</b></p>
+
+<p>There are several symbols maintained by the <nobr>read-eval-print</nobr>
+loop:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>*</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>the most recent result</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>**</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>the second recent result</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>***</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>the third recent result</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>+</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>the most recent input expression</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>++</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>the second recent input expression</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>+++</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>the third recent input expression</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>−</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">the expression currently being evaluated, becomes the
+ value of + at the end of the evaluation</td>
+</tr>
+</tbody></table></p>
+
+<p>These symbols are for interactive programming. <nobr>It is</nobr> not
+recommended to use them in program code.</p>
+
+</div></p>
+
+<a name="special-characters"></a>
+
+<p><div class="box">
+
+<p><b>Special Characters</b></p>
+
+<p>When XLISP is running from a console <nobr>[not in</nobr> the Nyquist
+<nobr>Java IDE]</nobr>, some control characters invoke operations:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>Control-c</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">executes the <a href="../reference/top-level.htm">top-level</a> function</td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>Control-g</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">executes the <a href="../reference/clean-up.htm">clean-up</a> function</td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>Control-p</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">executes the <a href="../reference/continue.htm">continue</a> function</td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>Control-b</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">stops execution and enters the break command loop,
+ execution can be continued by typing Control-p <nobr>or
+ (<a href="../reference/continue.htm">continue</a>)</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>Control-e</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">turns on character echoing [Linux and <nobr>Mac OS X</nobr> only]</td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>Control-f</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">turns off character echoing [Linux and <nobr>Mac OS X</nobr> only]</td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>Control-t</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">evaluates the <a href="../reference/info.htm">info</a> function</td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>Control-u</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">erases the entire input line</td>
+</tr>
+</tbody></table></p>
+
+<p>Backspace and Delete characters erase the previous character on the input
+line <nobr>[if any]</nobr>.</p>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="break-loop"></a>
+
+<hr>
+
+<h2>4 Break Loop</h2>
+
+<hr>
+
+<p>When XLISP encounters an error while evaluating an expression, it
+attempts to handle the error in the following way:</p>
+
+<dl>
+
+<p><b>1.</b> If the symbol
+<a href="../reference/global-breakenable.htm">*breakenable*</a> is true, the
+message corresponding to the error is printed. <nobr>If the</nobr> error is
+correctable, the correction message is printed.</p>
+
+<dd>
+<ul>
+
+<li><p>If the symbol
+<a href="../reference/global-tracenable.htm">*tracenable*</a> is true, a
+trace back is printed. The number of entries printed depends on the value of
+the symbol <a href="../reference/global-tracelimit.htm">*tracelimit*</a>.
+<nobr>If this</nobr> symbol is set to something other than a number, the
+entire trace back stack is printed.</p></li>
+
+</ul>
+
+<p>XLISP then enters a '<nobr>read-eval-print</nobr>' loop to allow the user
+to examine the state of the interpreter in the context of the error. This
+loop differs from the normal <nobr>top-level</nobr>
+'<nobr>read-eval-print</nobr>' loop in that if the user invokes the
+<a href="../reference/continue.htm">continue</a> function:</p>
+
+<pre class="example">
+1> (continue)
+</pre>
+
+<p>XLISP will continue from a correctable error. <nobr>If the</nobr> user
+invokes the <a href="../reference/clean-up.htm">clean-up</a> function:</p>
+
+<pre class="example">
+1> (clean-up)
+</pre>
+
+<p>XLISP will abort the break loop and return to the top level or the next
+lower numbered break loop. When in a break loop, XLISP prefixes the break
+level to the normal prompt with a number.</p></dd>
+
+<dt><p><b>2.</b> If the symbol
+<a href="../reference/global-breakenable.htm">*breakenable*</a>
+is <a href="../reference/nil.htm">NIL</a>, XLISP looks for a surrounding
+<a href="../reference/errset.htm">errset</a> function:</p></dt>
+
+</dl>
+
+<ul>
+
+<li type="circle"><p>If an error happened within the scope of an
+<a href="../reference/errset.htm">errset</a> function, XLISP examines the
+value of the <a href="../reference/errset.htm">errset</a> print flag.
+<nobr>If this</nobr> flag is true, the error message is printed.
+<nobr>In case</nobr> of an error, the
+<a href="../reference/errset.htm">errset</a> function always <nobr>returns
+<a href="../reference/nil.htm">NIL</a></nobr>.</p></li>
+
+<li type="circle"><p>If there is no surrounding
+<a href="../reference/errset.htm">errset</a> function, XLISP prints the
+error message and returns to the top level.</p></li>
+
+</ul>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="data-types"></a>
+
+<hr>
+
+<h2>5 Data Types</h2>
+
+<hr>
+
+<p>There are several different data types available to XLISP
+programmers:</p>
+
+<ul>
+<li><nobr><a href="../reference/nil.htm">nil</a> - boolean false as well as the empty <a href="../reference/listp.htm">list</a></nobr></li>
+<li><nobr><a href="../reference/arrayp.htm">array</a> - including <a href="../reference/hash.htm">hash</a>-tables</nobr></li>
+<li><a href="../reference/characterp.htm">character</a></li>
+<li><a href="../reference/numberp.htm">number</a></li>
+<ul>
+<li><a href="../reference/integerp.htm">fixnum</a> - integer number</li>
+<li><a href="../reference/floatp.htm">flonum</a> - floating point number</li>
+</ul>
+<li><nobr><a href="../reference/consp.htm">cons</a> - a non-empty list, where a <a href="../reference/listp.htm">list</a> is of type <a href="../reference/consp.htm">cons</a> or <a href="../reference/nil.htm">nil</a></nobr></li>
+<li><a href="../reference/objectp.htm">object</a></li>
+<li><a href="../reference/streamp.htm">stream</a></li>
+<ul>
+<li><nobr><b>file-stream</b> - returned by <a href="../reference/open.htm">open</a></nobr></li>
+<li><nobr><b>unnamed-stream</b> - returned by <a href="../reference/make-string-input-stream.htm">make-string-input-stream</a></nobr></li>
+</ul>
+<li><nobr><a href="../reference/stringp.htm">string</a></nobr></li>
+<li><nobr><a href="../reference/symbolp.htm">symbol</a> - including keywords</nobr></li>
+<li><nobr><b>subr</b> - built-in function</nobr></li>
+<li><nobr><b>fsubr</b> - special form</nobr></li>
+<li><nobr><b>closure</b> - user defined function</nobr></li>
+<li><nobr><a href="../reference/filep.htm">file</a></nobr></li>
+<li><nobr><a href="../reference/soundp.htm">sound</a> - a Nyquist sound</nobr></li>
+</ul>
+
+<p>See also the <nobr><a href="../reference/type-of.htm">type-of</a></nobr>
+function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="the-evaluator"></a>
+
+<hr>
+
+<h2>6 The Evaluator</h2>
+
+<hr>
+
+<p>The process of evaluation in XLISP:</p>
+
+<ul>
+
+<li><p>The following Lisp objects evaluate to themselves:</p>
+
+<ul>
+<li><nobr><a href="../reference/stringp.htm">string</a></nobr></li>
+<li><nobr><a href="../reference/integerp.htm">fixnum</a></nobr></li>
+<li><nobr><a href="../reference/characterp.htm">character</a></nobr></li>
+<li><nobr><a href="../reference/floatp.htm">flonum</a></nobr></li>
+<li><nobr><a href="../reference/objectp.htm">object</a></nobr></li>
+<li><nobr><a href="../reference/arrayp.htm">array</a></nobr></li>
+<li><nobr><a href="../reference/streamp.htm">stream</a></nobr></li>
+<li><nobr><b>subr</b> - built-in function</nobr></li>
+<li><nobr><b>fsubr</b> - special form</nobr></li>
+<li><nobr><b>closure</b> - user defined function</nobr></li>
+</ul>
+</li>
+
+<li><p><font color="#000088"><b>Symbols</b></font> act as variables and are
+evaluated by retrieving the value associated with their current
+binding.</p></li>
+
+<li><p><font color="#000088"><b>Lists</b></font> are evaluated by examining
+the first element of the list and then taking one of the following
+actions:</p></li>
+
+<ul>
+
+<li><p>If it is a <font color="#000088"><b>symbol</b></font>, the functional
+binding of the symbol is retrieved.</p></li>
+
+<li><p>If it is a <font color="#000088"><b>lambda expression</b></font>, a
+closure is constructed for the function described by the lambda
+expression.</p></li>
+
+<li><p>If it is a <font color="#000088"><b>subr</b></font> [built-in
+function], <font color="#000088"><b>fsubr</b></font> [special form] or <font
+color="#000088"><b>closure</b></font> [user defined function], it stands for
+itself.</p></li>
+
+<li><p>Any other value is an <font color="#AA0000"><b>error</b></font>.</p></li>
+
+</ul>
+
+<p>Then, the value produced by the previous step is examined:</p>
+
+<ul>
+
+<li><p>If it is a <font color="#000088"><b>subr</b></font>
+<nobr>[built-in</nobr> function] or <font
+color="#000088"><b>closure</b></font> [user defined function], the remaining
+list elements are evaluated and the subr or closure is called with these
+evaluated expressions as arguments.</p></li>
+
+<li><p>If it is an <font color="#000088"><b>fsubr</b></font> [special form],
+the fsubr is called using the remaining list elements as arguments
+[unevaluated].</p></li>
+
+<li><p>If it is a<font color="#000088"><b> macro</b></font>, the macro is
+expanded using the remaining list elements as arguments [unevaluated]. The
+macro expansion is then evaluated in place of the original macro
+call.</p></li>
+
+</ul>
+
+</ul>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lexical-conventions"></a>
+
+<hr>
+
+<h2>7 Lexical Conventions</h2>
+
+<hr>
+
+<p>The following conventions must be followed when entering XLISP
+programs:</p>
+
+<ul>
+
+<li><p>Comments in XLISP code begin with a semicolon character and continue
+to the end of the line.</p></li>
+
+<li><p>Symbol names in XLISP can consist of any sequence of non-blank
+printable characters except the following:</p></li>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr>(</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>opening parenthesis</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr>)</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>closing parenthesis</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr>'</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>single-quote</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr>`</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>backquote</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr>,</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>comma</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr>"</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>double-quote</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr>;</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>semicolon</nobr></td>
+</tr>
+</tbody></table></p>
+
+<li><p>Uppercase and lowercase characters are not distinguished within
+symbol names. All lowercase characters are mapped to uppercase on
+input.</p></li>
+
+<li><p>Integer literals consist of a sequence of digits optionally beginning
+with a '+' [plus] or '-' [minus]. The range of values an integer can
+represent is limited by the size of a C 'long' value on the machine on which
+XLISP is running. <nobr>Also be</nobr> aware that Nyquist doesn't check for
+CPU register overflow with integer numbers, so for example if you add 1 to
+the biggest Nyquist integer number, the result will be a negative
+number.</p></li>
+
+<li><p>Floating point literals consist of a sequence of digits optionally
+beginning with a '+' [plus] or '-' [minus] and including an embedded decimal
+point. The range of values a floating point number can represent is limited
+by the size of a C 'float' [or 'double' on machines with 32 bit addresses]
+on the machine on which XLISP is running.</p></li>
+
+<li><p>Literal strings are sequences of characters surrounded by double
+quotes. Within quoted strings the '\' [backslash] character is used to allow
+non-printable characters to be included. The codes recognized are:</p></li>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>\\</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">the character '\' [backslash]</td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>\n</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">newline</td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>\t</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">tab</td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>\r</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">return</td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>\f</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">form feed</td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>\<font color="#0000CC">nnn</font></code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">the character whose octal code is 'nnn'</td>
+</tr>
+</tbody></table></p>
+
+<p>An <a href="../misc/ascii-table.htm">ASCII</a> table
+is provided with this version of the XLISP manual with all octal, decimal
+and hexadecimal character values.</p>
+
+</ul>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="the-readtable"></a>
+
+<hr>
+
+<h2>8 The Readtable</h2>
+
+<hr>
+
+<a name="constituent"></a><a name="white-space"></a>
+<a name="tmacro"></a><a name="nmacro"></a>
+<a name="sescape"></a><a name="mescape"></a>
+
+<p>The behavior of the reader is controlled by a data structure called a
+'readtable'. The reader uses the symbol
+<a href="../reference/global-readtable.htm">*readtable*</a> to locate the
+current readtable. This table controls the interpretation of input
+characters. It is an array with 128 entries, one for each of the
+<a href="../misc/ascii-table.htm">ASCII</a> character codes. Each
+entry contains one of the following things:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code> NIL</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr>indicating an invalid character</nobr></td>
+ <td width="100%"><nobr> [see
+ <a href="../reference/nil.htm">nil</a>]</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>:CONSTITUENT</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr>indicating a symbol constituent</nobr></td>
+ <td width="100%"><nobr> [see
+ <a href="../reference/keyword-constituent.htm">:constituent</a>]</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>:WHITE-SPACE</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr>indicating a whitespace character</nobr></td>
+ <td width="100%"><nobr> [see
+ <a href="../reference/keyword-white-space.htm">:white-space</a>]</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>(:TMACRO . <font color="#0000CC">function</font>)</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr>terminating readmacro</nobr></td>
+ <td width="100%"><nobr> [see
+ <a href="../reference/keyword-tmacro.htm">:tmacro</a>]</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>(:NMACRO . <font color="#0000CC">function</font>)</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr>non-terminating readmacro</nobr></td>
+ <td width="100%"><nobr> [see
+ <a href="../reference/keyword-nmacro.htm">:nmacro</a>]</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>:SESCAPE</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr>single escape character '\'</nobr></td>
+ <td width="100%"><nobr> [see
+ <a href="../reference/keyword-sescape.htm">:sescape</a>]</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>:MESCAPE</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr>multiple escape character '|'</nobr></td>
+ <td width="100%"><nobr> [see
+ <a href="../reference/keyword-mescape.htm">:mescape</a>]</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>In the case of <a href="../reference/keyword-tmacro.htm">:tmacro</a> and
+<a href="../reference/keyword-nmacro.htm">:nmacro</a>, the 'fun' component
+is a function. This can either be a built-in readmacro function or a
+<a href="../reference/lambda.htm">lambda</a> expression. The
+function should take two parameters. The first is the input stream and the
+second is the character that caused the invocation of the readmacro. The
+readmacro function should return
+<a href="../reference/nil.htm">NIL</a> to indicate that the
+character should be treated as white space or a value
+<a href="../reference/cons.htm">cons</a>ed with
+<a href="../reference/nil.htm">NIL</a> to indicate that the
+readmacro should be treated as an occurence of the specified value. Of
+course, the readmacro code is free to
+<a href="../reference/read.htm">read</a> additional characters
+from the input stream.</p>
+
+<a name="quote"></a><a name="function"></a><a name="array"></a>
+<a name="hexadecimal"></a><a name="octal"></a><a name="binary"></a>
+<a name="character"></a><a name="comment"></a><a name="uninterned"></a>
+<a name="backquote"></a><a name="comma"></a><a name="comma-at"></a>
+
+<p>XLISP defines several useful read macros:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>'<font color="#0000CC">expression</font></code></nobr></td>
+ <td><nobr> = </nobr></td>
+ <td width="100%"><nobr>(<a href="../reference/quote.htm">quote</a>
+ <i>expr</i>)</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>#'<font color="#0000CC">expression</font></code></nobr></td>
+ <td><nobr> = </nobr></td>
+ <td width="100%"><nobr>(<a href="../reference/function.htm">function</a>
+ <i>expr</i>)</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>#(<font color="#0000CC">expression</font><font color="#008844">...</font>)</code></nobr></td>
+ <td><nobr> = </nobr></td>
+ <td width="100%"><nobr>an array of the specified expressions</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>#x<font color="#0000CC">digits</font></code></nobr></td>
+ <td><nobr> = </nobr></td>
+ <td width="100%"><nobr>a hexadecimal number [0-9,A-F]</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>#o<font color="#0000CC">digits</font></code></nobr></td>
+ <td><nobr> = </nobr></td>
+ <td width="100%"><nobr>an octal number [0-7]</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>#b<font color="#0000CC">digits</font></code></nobr></td>
+ <td><nobr> = </nobr></td>
+ <td width="100%"><nobr>a binary number [0-1]</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>#\<font color="#0000CC">character</font></code></nobr></td>
+ <td><nobr> = </nobr></td>
+ <td width="100%"><nobr>a single character</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>#| <font color="#008844">...</font> |#</code></nobr></td>
+ <td><nobr> = </nobr></td>
+ <td width="100%"><nobr>a comment</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>#:<font color="#0000CC">symbol</font></code></nobr></td>
+ <td><nobr> = </nobr></td>
+ <td width="100%"><nobr>an uninterned symbol</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>`<font color="#0000CC">expression</font></code></nobr></td>
+ <td><nobr> = </nobr></td>
+ <td width="100%"><nobr>(<a href="../reference/backquote.htm">backquote</a>
+ <i>expr</i>)</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>,<font color="#0000CC">expression</font></code></nobr></td>
+ <td><nobr> = </nobr></td>
+ <td width="100%"><nobr>(<a href="../reference/backquote.htm">comma</a>
+ <i>expr</i>)</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>,@<font color="#0000CC">expression</font></code></nobr></td>
+ <td><nobr> = </nobr></td>
+ <td width="100%"><nobr>(<a href="../reference/backquote.htm">comma-at</a>
+ <i>expr</i>)</nobr></td>
+</tr>
+</tbody></table></p>
+
+<a name="Tab"></a><a name="Newline"></a><a name="Space"></a>
+
+<p>Characters names handled by the reader:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>#\Tab</code></nobr></td>
+ <td><nobr> = </nobr></td>
+ <td><nobr>horiz. tab</nobr></td>
+ <td><nobr> [<a href="../misc/ascii-table.htm">ASCII</a> decimal value 9]</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>#\Newline</code></nobr></td>
+ <td><nobr> = </nobr></td>
+ <td><nobr>newline</nobr></td>
+ <td><nobr> [<a href="../misc/ascii-table.htm">ASCII</a> decimal value 10]</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>#\Space</code></nobr></td>
+ <td><nobr> = </nobr></td>
+ <td><nobr>space</nobr></td>
+ <td><nobr> [<a href="../misc/ascii-table.htm">ASCII</a> decimal value 32]</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lambda-lists"></a>
+
+<hr>
+
+<h2>9 Lambda Lists</h2>
+
+<a name="arguments"></a>
+
+<hr>
+
+<h2>9.1 Arguments</h2>
+
+<hr>
+
+<p>There are several forms in XLISP that require that a <nobr>'lambda
+list'</nobr> be specified. A lambda list is a definition of the arguments
+accepted by a function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="required-arguments"></a>
+
+<hr>
+
+<h2>9.1.1 Required Arguments</h2>
+
+<hr>
+
+<p>The lambda list starts with 'required' arguments. Required arguments must
+be specified in every call to the function.</p>
+
+<p>The function '<nobr>print-x</nobr>' has exactly one required
+<nobr>argument 'x'</nobr>:</p>
+
+<pre class="example">
+(defun print-x (x)
+ (print x))
+
+(print-x 1) => 1
+(print-x) => <font color="#AA0000">error: too few arguments</font>
+(print-x 1 2) => <font color="#AA0000">error: too many arguments</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="optional-arguments"></a>
+
+<hr>
+
+<h2>9.1.2 Optional Arguments</h2>
+
+<hr>
+
+<p>The <nobr><a href="#required-arguments">Required Arguments</a></nobr> are followed by
+the <a href="../reference/lambda-keyword-optional.htm">&optional</a>
+arguments. Optional arguments may be provided or omitted in a call. An
+initialization expression may be specified to provide a default value for an
+<a href="../reference/lambda-keyword-optional.htm">&optional</a>
+argument if it is omitted from a call. If no initialization expression is
+specified, an omitted argument is initialized to
+<a href="../reference/nil.htm">NIL</a>.</p>
+
+<p>It is also possible to provide the name of a 'supplied-p' variable that
+can be used to determine if a call provided a value for the argument or if
+the initialization expression was used. If specified, the 'supplied-p'
+variable will be bound to
+<a href="../reference/t.htm"> T </a> if a value was
+specified in the call and
+<a href="../reference/nil.htm">NIL</a> if the default value was
+used.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="rest-argument"></a>
+
+<hr>
+
+<h2>9.1.3 Rest Argument</h2>
+
+<hr>
+
+<p>The <nobr><a href="#optional-arguments">Optional Arguments</a></nobr> are followed by
+the <a href="../reference/lambda-keyword-rest.htm">&rest</a> argument.
+<nobr>The <a href="../reference/lambda-keyword-rest.htm">&rest</a></nobr>
+argument gets bound to the remainder of the argument list after the required
+and <a href="../reference/lambda-keyword-optional.htm">&optional</a>
+arguments have been removed.</p>
+
+<p><div class="box">
+
+<p><b>Known Problems with the Rest Argument</b></p>
+
+<p>A subtle problem arises if
+<nobr><a href="#optional-arguments">Optional Arguments</a></nobr> are used together with
+a <a href="../reference/lambda-keyword-rest.htm">&rest</a> argument:</p>
+
+<pre class="example">
+(defun test (&optional opt &rest rest)
+ (format t "opt = ~a, rest = ~a~%" opt rest))
+
+(test 1) => opt = 1, rest = NIL
+(test 1 2) => opt = 1, rest = (2)
+(test 1 2 3) => opt = 1, rest = (2 3)
+</pre>
+
+<p>Now the
+<a href="../reference/lambda-keyword-optional.htm">&optional</a>
+argument is not optional anymore, there is no way to make the first argument
+appear in the <a href="../reference/lambda-keyword-rest.htm">&rest</a>
+list and not in the
+<a href="../reference/lambda-keyword-optional.htm">&optional</a>
+variable. This is not a XLISP bug, this is a general Lisp phenomenon.
+<nobr>In Lisp</nobr> it's not a good idea to use
+<nobr><a href="#optional-arguments">Optional Arguments</a></nobr> together with a
+<a href="../reference/lambda-keyword-rest.htm">&rest</a> argument.</p>
+
+<p>If a <a href="../reference/lambda-keyword-rest.htm">&rest</a>
+argument is used togethter with
+<nobr><a href="#keyword-arguments">Keyword Arguments</a></nobr>, then the keywords and
+their arguments appear in the list bound to the
+<a href="../reference/lambda-keyword-rest.htm">&rest</a></nobr>
+argument. This is not neccessarily a XLISP bug, this also happens with
+other Lisps. <nobr>In Lisp</nobr> it's also not a good idea to use
+<nobr><a href="#keyword-arguments">Keyword Arguments</a></nobr> together with a
+<a href="../reference/lambda-keyword-rest.htm">&rest</a> argument.</p>
+
+<p><b>XLISP Bug:</b> <nobr>If the</nobr> number of elements in a
+<a href="../reference/lambda-keyword-rest.htm">&rest</a> list
+is odd, then <a href="../reference/lambda-keyword-key.htm">&key</a>
+variables have wrong values:</p>
+
+<pre class="example">
+(defun test (&rest rest &key (key t))
+ (format t "rest = ~a, key = ~a~%" rest key))
+
+(test 1 :key 'a) => rest = (1 :KEY A), key = T <font color="#AA0000">; wrong KEY value</font>
+(test 1 2 :key 'a) => rest = (1 2 :KEY A), key = A <font color="#008844">; quirk, but correct KEY value</font>
+(test 1 2 3 :key 'a)) => rest = (1 2 3 :KEY A), key = T <font color="#AA0000">; again wrong KEY value</font>
+</pre>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="keyword-arguments"></a>
+
+<hr>
+
+<h2>9.1.4 Keyword Arguments</h2>
+
+<hr>
+
+<p>The <nobr><a href="#rest-argument">Rest Argument</a></nobr> is
+followed by the <a href="../reference/lambda-keyword-key.htm">&key</a>
+arguments. When a keyword argument is passed to a function, a pair of values
+appears in the argument list. The first expression in the pair should
+evaluate to a keyword symbol [a symbol that begins with a <nobr>colon
+':'].</nobr> The value of the second expression is the value of the keyword
+argument.</p>
+
+<p>Like <a href="../reference/lambda-keyword-optional.htm">&optional</a>
+arguments, <a href="../reference/lambda-keyword-key.htm">&key</a> arguments can
+have initialization expressions and 'supplied-p' variables. In addition, it
+is possible to specify the keyword to be used in a function call. If no
+keyword is specified, the keyword obtained by adding a colon ':' to the
+beginning of the keyword argument symbol is used.</p>
+
+<p>In other words, if the keyword argument symbol is:</p>
+
+<pre class="example">
+foo
+</pre>
+
+<p>the keyword will be:</p>
+
+<pre class="example">
+:foo
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="auxiliary-variables"></a>
+
+<hr>
+
+<h2>9.1.5 Auxiliary Variables</h2>
+
+<hr>
+
+<p>The <nobr><a href="#keyword-arguments">Keyword Arguments</a></nobr> are followed by
+the <a href="../reference/lambda-keyword-aux.htm">&aux</a> variables.
+These are local variables that are bound during the evaluation of the
+function body. It is possible to have initialization expressions for the
+<a href="../reference/lambda-keyword-aux.htm">&aux</a> variables.</p>
+
+<p><nobr> <a href="#top">Back to Top</a></nobr></p>
+
+<a name="lambda-list-syntax"></a>
+
+<hr>
+
+<h2>9.2 Lambda List Syntax</h2>
+
+<hr>
+
+<p>Here is the complete syntax for lambda lists:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td width="100%" colspan="2"><nobr>(<i>required-arg</i> ...</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td width="100%"><nobr>[<b>&optional</b> [<i>optional-arg</i> | (<i>optional-arg</i> [<i>init-form</i> [<i>supplied-var</i>]])] ... ]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td width="100%"><nobr>[<b>&rest</b> <i>rest-arg</i>]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td width="100%"><nobr>[<b>&key</b> [<i>key-arg</i> | ([<i>key-arg</i> | (<i>keyword</i> <i>key-arg</i>)] [<i>init-form</i> [<i>supplied-var</i>]]) ...] <b>&allow-other-keys</b>]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td width="100%"><nobr>[<b>&aux</b> [<i>aux-var</i> | (<i>aux-var</i> [<i>init-form</i>])] ... ])</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>where:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr><i>required-arg</i></nobr></td>
+ <td><nobr> — </nobr></td>
+ <td width="100%">is a <a href="#required-arguments">required</a> argument symbol</td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr><i>optional-arg</i></nobr></td>
+ <td><nobr> — </nobr></td>
+ <td width="100%">is an <a href="#optional-arguments">&optional</a> argument symbol</td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr><i>rest-arg</i></nobr></td>
+ <td><nobr> — </nobr></td>
+ <td width="100%">is the <a href="#rest-argument">&rest</a> argument symbol</td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr><i>key-arg</i></nobr></td>
+ <td><nobr> — </nobr></td>
+ <td width="100%">is a <a href="#keyword-arguments">&key</a> argument symbol</td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr><i>keyword</i></nobr></td>
+ <td><nobr> — </nobr></td>
+ <td width="100%">is a <a href="#keyword-arguments">keyword</a> symbol</td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr><i>aux-var</i></nobr></td>
+ <td><nobr> — </nobr></td>
+ <td width="100%">is an <a href="#auxiliary-variables">auxiliary</a> variable symbol</td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr><i>init-form</i></nobr></td>
+ <td><nobr> — </nobr></td>
+ <td width="100%">is an initialization expression</td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="right"><nobr><i>supplied-var</i></nobr></td>
+ <td><nobr> — </nobr></td>
+ <td width="100%">is a supplied-p variable symbol</td>
+</tr>
+</tbody></table></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/misc/ascii-table.htm b/docsrc/xlisp/xlisp-doc/misc/ascii-table.htm new file mode 100644 index 0000000..a313dd5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/misc/ascii-table.htm @@ -0,0 +1,1403 @@ +<html><head><title>ASCII Character Set</title> + +<style type="text/css"> +.example { + color: #000000; + background-color: #F5F5F5; + padding: 8px; + border: #808080; + border-style: solid; + border-width: 1px; + width:auto; +} +.button { + color: #000000; + background-color: #F5F5F5; + padding-top: 1px; + padding-bottom: 1px; + padding-left: 4px; + padding-right: 8px; + border: #808080; + border-style: solid; + border-width: 1px; + white-space: pre; +} +.box { + color: #000000; + padding-top: 4px; + padding-bottom: 4px; + padding-left: 16px; + padding-right: 16px; + border: #808080; + border-style: solid; + border-width: 1px; +} +</style> + +</head> + +<body> + +<a href="../start.htm">Nyquist / XLISP 2.0</a> - +<a href="../manual/contents.htm">Contents</a> | +<a href="../tutorials/tutorials.htm">Tutorials</a> | +<a href="../examples/examples.htm">Examples</a> | +<a href="../reference/reference-index.htm">Reference</a> + +<hr> + +<H1>The ASCII Character Set</H1> + +<hr> + +<p>The standard ASCII character set uses only 7 bits of the 8 bit byte for +each character. There are several larger character sets that use all 8 bits +of the byte, which gives them an 128 additional characters in the set. The +extra characters are used to represent characters not used in the English +language, graphics characters or symbols, and mathematical representations +or symbols.</p> + +<p><b>ASCII Control Characters</b></p> + +<p>ASCII control characters are actually commands for the terminal, monitor, +computer, I/O devices, printer or other peripherals to do something. The +first 32 values are non-printing control characters, such as 'carriage +return' and 'line feed'. You generate these characters on the keyboard by +holding down the 'control' key while you strike another key. These +characters are also capable of being sent to the device by a software +sequence, most often by a program. They are usually sent as a string of +characters following an attention character, usually 'escape', but not +always.</p> + +<h2>ASCII Control Characters</h2> + +<p><table cellpadding="0" cellspacing="1" style="margin-left:10px"><tbody> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>Ctrl-key</b></td> + <td class="button"><b>XLISP</b></td> +</tr> +<tr> + <td class="button">NUL</td> + <td class="button" align="right">0</td> + <td class="button" align="right">0</td> + <td class="button" align="right">0</td> + <td class="button">Ctrl+@</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>null character</td> +</tr> +<tr> + <td class="button">SOH</td> + <td class="button" align="right">1</td> + <td class="button" align="right">1</td> + <td class="button" align="right">1</td> + <td class="button">Ctrl+a</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>start of heading</td> +</tr> +<tr> + <td class="button">STX</td> + <td class="button" align="right">2</td> + <td class="button" align="right">2</td> + <td class="button" align="right">2</td> + <td class="button">Ctrl+b</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>start of text</td> +</tr> +<tr> + <td class="button">ETX</td> + <td class="button" align="right">3</td> + <td class="button" align="right">3</td> + <td class="button" align="right">3</td> + <td class="button">Ctrl+c</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>end of text</td> +</tr> +<tr> + <td class="button">EOT</td> + <td class="button" align="right">4</td> + <td class="button" align="right">4</td> + <td class="button" align="right">4</td> + <td class="button">Ctrl+d</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>end of transmission</td> +</tr> +<tr> + <td class="button">ENQ</td> + <td class="button" align="right">5</td> + <td class="button" align="right">5</td> + <td class="button" align="right">5</td> + <td class="button">Ctrl+e</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>enquiry</td> +</tr> +<tr> + <td class="button">ACK</td> + <td class="button" align="right">6</td> + <td class="button" align="right">6</td> + <td class="button" align="right">6</td> + <td class="button">Ctrl+f</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>acknowledge</td> +</tr> +<tr> + <td class="button">BEL</td> + <td class="button" align="right">7</td> + <td class="button" align="right">7</td> + <td class="button" align="right">7</td> + <td class="button">Ctrl+g</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>rings terminal bell</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>Ctrl-key</b></td> + <td class="button"><b>XLISP</b></td> +<tr> + <td class="button">BS</td> + <td class="button" align="right">10</td> + <td class="button" align="right">8</td> + <td class="button" align="right">8</td> + <td class="button">Ctrl+h</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>backspace (non-destructive)</td> +</tr> +<tr> + <td class="button">HT</td> + <td class="button" align="right">11</td> + <td class="button" align="right">9</td> + <td class="button" align="right">9</td> + <td class="button">Ctrl+i</td> + <td class="button"><code>#\Tab</code></td> + <td><nobr> - </nobr></td> + <td>horizontal tab</td> +</tr> +<tr> + <td class="button">LF</td> + <td class="button" align="right">12</td> + <td class="button" align="right">10</td> + <td class="button" align="right">A</td> + <td class="button">Ctrl+j</td> + <td class="button"><code>#\Newline</code></td> + <td><nobr> - </nobr></td> + <td>line feed</td> +</tr> +<tr> + <td class="button">VT</td> + <td class="button" align="right">13</td> + <td class="button" align="right">11</td> + <td class="button" align="right">B</td> + <td class="button">Ctrl+k</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>vertical tab</td> +</tr> +<tr> + <td class="button">FF</td> + <td class="button" align="right">14</td> + <td class="button" align="right">12</td> + <td class="button" align="right">C</td> + <td class="button">Ctrl+l</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>form feed</td> +</tr> +<tr> + <td class="button">CR</td> + <td class="button" align="right">15</td> + <td class="button" align="right">13</td> + <td class="button" align="right">D</td> + <td class="button">Ctrl+m</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>carriage return</td> +</tr> +<tr> + <td class="button">SO</td> + <td class="button" align="right">16</td> + <td class="button" align="right">14</td> + <td class="button" align="right">E</td> + <td class="button">Ctrl+n</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>shift out</td> +</tr> +<tr> + <td class="button">SI</td> + <td class="button" align="right">17</td> + <td class="button" align="right">15</td> + <td class="button" align="right">F</td> + <td class="button">Ctrl+o</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>shift in</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>Ctrl-key</b></td> + <td class="button"><b>XLISP</b></td> +</tr> +<tr> + <td class="button">DLE</td> + <td class="button" align="right">20</td> + <td class="button" align="right">16</td> + <td class="button" align="right">10</td> + <td class="button">Ctrl+p</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>data link escape</td> +</tr> +<tr> + <td class="button">DC1</td> + <td class="button" align="right">21</td> + <td class="button" align="right">17</td> + <td class="button" align="right">11</td> + <td class="button">Ctrl+q</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>device control 1, normally 'xon'</td> +</tr> +<tr> + <td class="button">DC2</td> + <td class="button" align="right">22</td> + <td class="button" align="right">18</td> + <td class="button" align="right">12</td> + <td class="button">Ctrl+r</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>device control 2</td> +</tr> +<tr> + <td class="button">DC3</td> + <td class="button" align="right">23</td> + <td class="button" align="right">19</td> + <td class="button" align="right">13</td> + <td class="button">Ctrl+s</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>device control 3, normally 'xoff'</td> +</tr> +<tr> + <td class="button">DC4</td> + <td class="button" align="right">24</td> + <td class="button" align="right">20</td> + <td class="button" align="right">14</td> + <td class="button">Ctrl+t</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>device control 4</td> +</tr> +<tr> + <td class="button">NAK</td> + <td class="button" align="right">25</td> + <td class="button" align="right">21</td> + <td class="button" align="right">15</td> + <td class="button">Ctrl+u</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>negative acknowledge</td> +</tr> +<tr> + <td class="button">SYN</td> + <td class="button" align="right">26</td> + <td class="button" align="right">22</td> + <td class="button" align="right">16</td> + <td class="button">Ctrl+v</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>synchronous idle</td> +</tr> +<tr> + <td class="button">ETB</td> + <td class="button" align="right">27</td> + <td class="button" align="right">23</td> + <td class="button" align="right">17</td> + <td class="button">Ctrl+w</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>end transmission block</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>Ctrl-key</b></td> + <td class="button"><b>XLISP</b></td> +<tr> + <td class="button">CAN</td> + <td class="button" align="right">30</td> + <td class="button" align="right">24</td> + <td class="button" align="right">17</td> + <td class="button">Ctrl+x</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>cancel line</td> +</tr> +<tr> + <td class="button">EM</td> + <td class="button" align="right">31</td> + <td class="button" align="right">25</td> + <td class="button" align="right">19</td> + <td class="button">Ctrl+y</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>end of medium</td> +</tr> +<tr> + <td class="button">SUB</td> + <td class="button" align="right">32</td> + <td class="button" align="right">26</td> + <td class="button" align="right">1A</td> + <td class="button">Ctrl+z</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>substitute</td> +</tr> +<tr> + <td class="button">ESC</td> + <td class="button" align="right">33</td> + <td class="button" align="right">27</td> + <td class="button" align="right">1B</td> + <td class="button">Ctrl+[</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>escape</td> +</tr> +<tr> + <td class="button">FS</td> + <td class="button" align="right">34</td> + <td class="button" align="right">28</td> + <td class="button" align="right">1C</td> + <td class="button">Ctrl+\</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>file separator</td> +</tr> +<tr> + <td class="button">GS</td> + <td class="button" align="right">35</td> + <td class="button" align="right">29</td> + <td class="button" align="right">1D</td> + <td class="button">Ctrl+]</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>group separator</td> +</tr> +<tr> + <td class="button">RS</td> + <td class="button" align="right">36</td> + <td class="button" align="right">30</td> + <td class="button" align="right">1E</td> + <td class="button">Ctrl+^</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>record separator</td> +</td> +<tr> + <td class="button">US</td> + <td class="button" align="right">37</td> + <td class="button" align="right">31</td> + <td class="button" align="right">1F</td> + <td class="button">Ctrl+_</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>unit separator</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>Ctrl-key</b></td> + <td class="button"><b>XLISP</b></td> +</tr> +</tbody></table></p> + +<h2>ASCII Printing Characters</h2> + +<p><table cellpadding="0" cellspacing="1" style="margin-left:10px"><tbody> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>XLISP</b></td> + +</tr> +<tr> + <td class="button"> </td> + <td class="button" align="right">40</td> + <td class="button" align="right">32</td> + <td class="button" align="right">20</td> + <td class="button"><code>#\Space</code></td> + <td><nobr> - </nobr></td> + <td>space</td> +</tr> +<tr> + <td class="button">!</td> + <td class="button" align="right">41</td> + <td class="button" align="right">33</td> + <td class="button" align="right">21</td> + <td class="button"><code>#\!</code></td> + <td><nobr> - </nobr></td> + <td>exclamation mark</td> +</tr> +<tr> + <td class="button">"</td> + <td class="button" align="right">42</td> + <td class="button" align="right">34</td> + <td class="button" align="right">22</td> + <td class="button"><code>#\"</code></td> + <td><nobr> - </nobr></td> + <td>quotation mark</td> +</tr> +<tr> + <td class="button">#</td> + <td class="button" align="right">43</td> + <td class="button" align="right">35</td> + <td class="button" align="right">23</td> + <td class="button"><code>#\#</code></td> + <td><nobr> - </nobr></td> + <td>cross hatch, number sign</td> +</tr> +<tr> + <td class="button">$</td> + <td class="button" align="right">44</td> + <td class="button" align="right">36</td> + <td class="button" align="right">24</td> + <td class="button"><code>#\$</code></td> + <td><nobr> - </nobr></td> + <td>dollar sign</td> +<tr> + <td class="button">%</td> + <td class="button" align="right">45</td> + <td class="button" align="right">37</td> + <td class="button" align="right">25</td> + <td class="button"><code>#\%</code></td> + <td><nobr> - </nobr></td> + <td>percent sign</td> +</tr> +<tr> + <td class="button">&</td> + <td class="button" align="right">46</td> + <td class="button" align="right">38</td> + <td class="button" align="right">26</td> + <td class="button"><code>#\&</code></td> + <td><nobr> - </nobr></td> + <td>ampersand</td> +</tr> +<tr> + <td class="button">`</td> + <td class="button" align="right">47</td> + <td class="button" align="right">39</td> + <td class="button" align="right">27</td> + <td class="button"><code>#\`</code></td> + <td><nobr> - </nobr></td> + <td>backquote, apostrophe</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>XLISP</b></td> +</tr> +<tr> + <td class="button">(</td> + <td class="button" align="right">50</td> + <td class="button" align="right">40</td> + <td class="button" align="right">28</td> + <td class="button"><code>#\(</code></td> + <td><nobr> - </nobr></td> + <td>opening parentheses</td> +</tr> +<tr> + <td class="button">)</td> + <td class="button" align="right">51</td> + <td class="button" align="right">41</td> + <td class="button" align="right">29</td> + <td class="button"><code>#\)</code></td> + <td><nobr> - </nobr></td> + <td>closing parentheses</td> +</tr> +<tr> + <td class="button">*</td> + <td class="button" align="right">52</td> + <td class="button" align="right">42</td> + <td class="button" align="right">2A</td> + <td class="button"><code>#\*</code></td> + <td><nobr> - </nobr></td> + <td>asterisk, star, multiply</td> +</tr> +<tr> + <td class="button">+</td> + <td class="button" align="right">53</td> + <td class="button" align="right">43</td> + <td class="button" align="right">2B</td> + <td class="button"><code>#\+</code></td> + <td><nobr> - </nobr></td> + <td>plus</td> +</tr> +<tr> + <td class="button">,</td> + <td class="button" align="right">54</td> + <td class="button" align="right">44</td> + <td class="button" align="right">2C</td> + <td class="button"><code>#\,</code></td> + <td><nobr> - </nobr></td> + <td>comma</td> +</tr> +<tr> + <td class="button">-</td> + <td class="button" align="right">55</td> + <td class="button" align="right">45</td> + <td class="button" align="right">2D</td> + <td class="button"><code>#\-</code></td> + <td><nobr> - </nobr></td> + <td>hyphen, dash, minus</td> +</tr> +<tr> + <td class="button">.</td> + <td class="button" align="right">56</td> + <td class="button" align="right">46</td> + <td class="button" align="right">2E</td> + <td class="button"><code>#\.</code></td> + <td><nobr> - </nobr></td> + <td>period</td> +</tr> +<tr> + <td class="button">/</td> + <td class="button" align="right">57</td> + <td class="button" align="right">47</td> + <td class="button" align="right">2F</td> + <td class="button"><code>#\/</code></td> + <td><nobr> - </nobr></td> + <td>slash forward, divide</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>XLISP</b></td> +</tr> +<tr> + <td class="button">0</td> + <td class="button" align="right">60</td> + <td class="button" align="right">48</td> + <td class="button" align="right">30</td> + <td class="button"><code>#\0</code></td> + <td><nobr> - </nobr></td> + <td>zero</td> +</tr> +<tr> + <td class="button">1</td> + <td class="button" align="right">61</td> + <td class="button" align="right">49</td> + <td class="button" align="right">31</td> + <td class="button"><code>#\1</code></td> + <td><nobr> - </nobr></td> + <td>one</td> +</tr> +<tr> + <td class="button">2</td> + <td class="button" align="right">62</td> + <td class="button" align="right">50</td> + <td class="button" align="right">32</td> + <td class="button"><code>#\2</code></td> + <td><nobr> - </nobr></td> + <td>two</td> +</tr> +<tr> + <td class="button">3</td> + <td class="button" align="right">63</td> + <td class="button" align="right">51</td> + <td class="button" align="right">33</td> + <td class="button"><code>#\3</code></td> + <td><nobr> - </nobr></td> + <td>three</td> +</tr> +<tr> + <td class="button">4</td> + <td class="button" align="right">64</td> + <td class="button" align="right">52</td> + <td class="button" align="right">34</td> + <td class="button"><code>#\4</code></td> + <td><nobr> - </nobr></td> + <td>four</td> +</tr> +<tr> + <td class="button">5</td> + <td class="button" align="right">65</td> + <td class="button" align="right">53</td> + <td class="button" align="right">35</td> + <td class="button"><code>#\5</code></td> + <td><nobr> - </nobr></td> + <td>five</td> +</tr> +<tr> + <td class="button">6</td> + <td class="button" align="right">66</td> + <td class="button" align="right">54</td> + <td class="button" align="right">36</td> + <td class="button"><code>#\6</code></td> + <td><nobr> - </nobr></td> + <td>six</td> +</tr> +<tr> + <td class="button">7</td> + <td class="button" align="right">67</td> + <td class="button" align="right">55</td> + <td class="button" align="right">37</td> + <td class="button"><code>#\7</code></td> + <td><nobr> - </nobr></td> + <td>seven</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>XLISP</b></td> +</tr> +<tr> + <td class="button">8</td> + <td class="button" align="right">70</td> + <td class="button" align="right">56</td> + <td class="button" align="right">38</td> + <td class="button"><code>#\8</code></td> + <td><nobr> - </nobr></td> + <td>eight</td> +</tr> +<tr> + <td class="button">9</td> + <td class="button" align="right">71</td> + <td class="button" align="right">57</td> + <td class="button" align="right">39</td> + <td class="button"><code>#\9</code></td> + <td><nobr> - </nobr></td> + <td>nine</td> +</tr> +<tr> + <td class="button">:</td> + <td class="button" align="right">72</td> + <td class="button" align="right">58</td> + <td class="button" align="right">3A</td> + <td class="button"><code>#\:</code></td> + <td><nobr> - </nobr></td> + <td>colon</td> +</tr> +<tr> + <td class="button">;</td> + <td class="button" align="right">73</td> + <td class="button" align="right">59</td> + <td class="button" align="right">3B</td> + <td class="button"><code>#\;</code></td> + <td><nobr> - </nobr></td> + <td>semicolon</td> +</tr> +<tr> + <td class="button"><</td> + <td class="button" align="right">74</td> + <td class="button" align="right">60</td> + <td class="button" align="right">3C</td> + <td class="button"><code>#\<</code></td> + <td><nobr> - </nobr></td> + <td>less than sign</td> +</tr> +<tr> + <td class="button">=</td> + <td class="button" align="right">75</td> + <td class="button" align="right">61</td> + <td class="button" align="right">3D</td> + <td class="button"><code>#\=</code></td> + <td><nobr> - </nobr></td> + <td>equals sign</td> +</tr> +<tr> + <td class="button">></td> + <td class="button" align="right">76</td> + <td class="button" align="right">62</td> + <td class="button" align="right">3E</td> + <td class="button"><code>#\></code></td> + <td><nobr> - </nobr></td> + <td>greater than sign</td> +</tr> +<tr> + <td class="button">?</td> + <td class="button" align="right">77</td> + <td class="button" align="right">63</td> + <td class="button" align="right">3F</td> + <td class="button"><code>#\?</code></td> + <td><nobr> - </nobr></td> + <td>question mark</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>XLISP</b></td> +</tr> +<tr> + <td class="button">@</td> + <td class="button" align="right">100</td> + <td class="button" align="right">64</td> + <td class="button" align="right">40</td> + <td class="button"><code>#\@</code></td> + <td><nobr> - </nobr></td> + <td>at-sign</td> +</tr> +<tr> + <td class="button">A</td> + <td class="button" align="right">101</td> + <td class="button" align="right">65</td> + <td class="button" align="right">41</td> + <td class="button"><code>#\A</code></td> + <td><nobr> - </nobr></td> + <td>upper case A</td> +</tr> +<tr> + <td class="button">B</td> + <td class="button" align="right">102</td> + <td class="button" align="right">66</td> + <td class="button" align="right">42</td> + <td class="button"><code>#\B</code></td> + <td><nobr> - </nobr></td> + <td>upper case B</td> +</tr> +<tr> + <td class="button">C</td> + <td class="button" align="right">103</td> + <td class="button" align="right">67</td> + <td class="button" align="right">43</td> + <td class="button"><code>#\C</code></td> + <td><nobr> - </nobr></td> + <td>upper case C</td> +</tr> +<tr> + <td class="button">D</td> + <td class="button" align="right">104</td> + <td class="button" align="right">68</td> + <td class="button" align="right">44</td> + <td class="button"><code>#\D</code></td> + <td><nobr> - </nobr></td> + <td>upper case D</td> +</tr> +<tr> + <td class="button">E</td> + <td class="button" align="right">105</td> + <td class="button" align="right">69</td> + <td class="button" align="right">45</td> + <td class="button"><code>#\E</code></td> + <td><nobr> - </nobr></td> + <td>upper case E</td> +</tr> +<tr> + <td class="button">F</td> + <td class="button" align="right">106</td> + <td class="button" align="right">70</td> + <td class="button" align="right">46</td> + <td class="button"><code>#\F</code></td> + <td><nobr> - </nobr></td> + <td>upper case F</td> +</tr> +<tr> + <td class="button">G</td> + <td class="button" align="right">107</td> + <td class="button" align="right">71</td> + <td class="button" align="right">47</td> + <td class="button"><code>#\G</code></td> + <td><nobr> - </nobr></td> + <td>upper case G</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>XLISP</b></td> +</tr> +<tr> + <td class="button">H</td> + <td class="button" align="right">110</td> + <td class="button" align="right">72</td> + <td class="button" align="right">48</td> + <td class="button"><code>#\H</code></td> + <td><nobr> - </nobr></td> + <td>upper case H</td> +</tr> +<tr> + <td class="button">I</td> + <td class="button" align="right">111</td> + <td class="button" align="right">73</td> + <td class="button" align="right">49</td> + <td class="button"><code>#\I</code></td> + <td><nobr> - </nobr></td> + <td>upper case I</td> +</tr> +<tr> + <td class="button">J</td> + <td class="button" align="right">112</td> + <td class="button" align="right">74</td> + <td class="button" align="right">4A</td> + <td class="button"><code>#\J</code></td> + <td><nobr> - </nobr></td> + <td>upper case J</td> +</tr> +<tr> + <td class="button">K</td> + <td class="button" align="right">113</td> + <td class="button" align="right">75</td> + <td class="button" align="right">4B</td> + <td class="button"><code>#\K</code></td> + <td><nobr> - </nobr></td> + <td>upper case K</td> +</tr> +<tr> + <td class="button">L</td> + <td class="button" align="right">114</td> + <td class="button" align="right">76</td> + <td class="button" align="right">4C</td> + <td class="button"><code>#\L</code></td> + <td><nobr> - </nobr></td> + <td>upper case L</td> +</tr> +<tr> + <td class="button">M</td> + <td class="button" align="right">115</td> + <td class="button" align="right">77</td> + <td class="button" align="right">4D</td> + <td class="button"><code>#\M</code></td> + <td><nobr> - </nobr></td> + <td>upper case M</td> +</tr> +<tr> + <td class="button">N</td> + <td class="button" align="right">116</td> + <td class="button" align="right">78</td> + <td class="button" align="right">4E</td> + <td class="button"><code>#\N</code></td> + <td><nobr> - </nobr></td> + <td>upper case N</td> +</tr> +<tr> + <td class="button">O</td> + <td class="button" align="right">117</td> + <td class="button" align="right">79</td> + <td class="button" align="right">4F</td> + <td class="button"><code>#\O</code></td> + <td><nobr> - </nobr></td> + <td>upper case O</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>XLISP</b></td> +</tr> +<tr> + <td class="button">P</td> + <td class="button" align="right">120</td> + <td class="button" align="right">80</td> + <td class="button" align="right">50</td> + <td class="button"><code>#\P</code></td> + <td><nobr> - </nobr></td> + <td>upper case P</td> +</tr> +<tr> + <td class="button">Q</td> + <td class="button" align="right">121</td> + <td class="button" align="right">81</td> + <td class="button" align="right">51</td> + <td class="button"><code>#\Q</code></td> + <td><nobr> - </nobr></td> + <td>upper case Q</td> +</tr> +<tr> + <td class="button">R</td> + <td class="button" align="right">122</td> + <td class="button" align="right">82</td> + <td class="button" align="right">52</td> + <td class="button"><code>#\R</code></td> + <td><nobr> - </nobr></td> + <td>upper case R</td> +</tr> +<tr> + <td class="button">S</td> + <td class="button" align="right">123</td> + <td class="button" align="right">83</td> + <td class="button" align="right">53</td> + <td class="button"><code>#\S</code></td> + <td><nobr> - </nobr></td> + <td>upper case S</td> +</tr> +<tr> + <td class="button">T</td> + <td class="button" align="right">124</td> + <td class="button" align="right">84</td> + <td class="button" align="right">54</td> + <td class="button"><code>#\T</code></td> + <td><nobr> - </nobr></td> + <td>upper case T</td> +</tr> +<tr> + <td class="button">U</td> + <td class="button" align="right">125</td> + <td class="button" align="right">85</td> + <td class="button" align="right">55</td> + <td class="button"><code>#\U</code></td> + <td><nobr> - </nobr></td> + <td>upper case U</td> +</tr> +<tr> + <td class="button">V</td> + <td class="button" align="right">126</td> + <td class="button" align="right">86</td> + <td class="button" align="right">56</td> + <td class="button"><code>#\V</code></td> + <td><nobr> - </nobr></td> + <td>upper case V</td> +</tr> +<tr> + <td class="button">W</td> + <td class="button" align="right">127</td> + <td class="button" align="right">87</td> + <td class="button" align="right">57</td> + <td class="button"><code>#\W</code></td> + <td><nobr> - </nobr></td> + <td>upper case W</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>XLISP</b></td> +</tr> +<tr> + <td class="button">X</td> + <td class="button" align="right">130</td> + <td class="button" align="right">88</td> + <td class="button" align="right">58</td> + <td class="button"><code>#\X</code></td> + <td><nobr> - </nobr></td> + <td>upper case X</td> +</tr> +<tr> + <td class="button">Y</td> + <td class="button" align="right">131</td> + <td class="button" align="right">89</td> + <td class="button" align="right">59</td> + <td class="button"><code>#\Y</code></td> + <td><nobr> - </nobr></td> + <td>upper case Y</td> +</tr> +<tr> + <td class="button">Z</td> + <td class="button" align="right">132</td> + <td class="button" align="right">90</td> + <td class="button" align="right">5A</td> + <td class="button"><code>#\Z</code></td> + <td><nobr> - </nobr></td> + <td>upper case Z</td> +</tr> +<tr> + <td class="button">[</td> + <td class="button" align="right">133</td> + <td class="button" align="right">91</td> + <td class="button" align="right">5B</td> + <td class="button"><code>#\[</code></td> + <td><nobr> - </nobr></td> + <td>opening square bracket</td> +</tr> +<tr> + <td class="button">\</td> + <td class="button" align="right">134</td> + <td class="button" align="right">92</td> + <td class="button" align="right">5C</td> + <td class="button"><code>#\\</code></td> + <td><nobr> - </nobr></td> + <td>backslash, reverse slant</td> +</tr> +<tr> + <td class="button">]</td> + <td class="button" align="right">135</td> + <td class="button" align="right">93</td> + <td class="button" align="right">5D</td> + <td class="button"><code>#\]</code></td> + <td><nobr> - </nobr></td> + <td>closing square bracket</td> +</tr> +<tr> + <td class="button">^</td> + <td class="button" align="right">136</td> + <td class="button" align="right">94</td> + <td class="button" align="right">5E</td> + <td class="button"><code>#\^</code></td> + <td><nobr> - </nobr></td> + <td>caret, circumflex</td> +</tr> +<tr> + <td class="button">_</td> + <td class="button" align="right">137</td> + <td class="button" align="right">95</td> + <td class="button" align="right">5F</td> + <td class="button"><code>#\_</code></td> + <td><nobr> - </nobr></td> + <td>underscore</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>XLISP</b></td> +</tr> +<tr> + <td class="button">`</td> + <td class="button" align="right">140</td> + <td class="button" align="right">96</td> + <td class="button" align="right">60</td> + <td class="button"><code>#\`</code></td> + <td><nobr> - </nobr></td> + <td>opening single quote</td> +</tr> +<tr> + <td class="button">a</td> + <td class="button" align="right">141</td> + <td class="button" align="right">97</td> + <td class="button" align="right">61</td> + <td class="button"><code>#\a</code></td> + <td><nobr> - </nobr></td> + <td>lower case a</td> +</tr> +<tr> + <td class="button">b</td> + <td class="button" align="right">142</td> + <td class="button" align="right">98</td> + <td class="button" align="right">62</td> + <td class="button"><code>#\b</code></td> + <td><nobr> - </nobr></td> + <td>lower case b</td> +</tr> +<tr> + <td class="button">c</td> + <td class="button" align="right">143</td> + <td class="button" align="right">99</td> + <td class="button" align="right">63</td> + <td class="button"><code>#\c</code></td> + <td><nobr> - </nobr></td> + <td>lower case c</td> +</tr> +<tr> + <td class="button">d</td> + <td class="button" align="right">144</td> + <td class="button" align="right">100</td> + <td class="button" align="right">64</td> + <td class="button"><code>#\d</code></td> + <td><nobr> - </nobr></td> + <td>lower case d</td> +</tr> +<tr> + <td class="button">e</td> + <td class="button" align="right">145</td> + <td class="button" align="right">101</td> + <td class="button" align="right">65</td> + <td class="button"><code>#\e</code></td> + <td><nobr> - </nobr></td> + <td>lower case e</td> +</tr> +<tr> + <td class="button">f</td> + <td class="button" align="right">146</td> + <td class="button" align="right">102</td> + <td class="button" align="right">66</td> + <td class="button"><code>#\f</code></td> + <td><nobr> - </nobr></td> + <td>lower case f</td> +</tr> +<tr> + <td class="button">g</td> + <td class="button" align="right">147</td> + <td class="button" align="right">103</td> + <td class="button" align="right">67</td> + <td class="button"><code>#\g</code></td> + <td><nobr> - </nobr></td> + <td>lower case g</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>XLISP</b></td> +</tr> +<tr> + <td class="button">h</td> + <td class="button" align="right">150</td> + <td class="button" align="right">104</td> + <td class="button" align="right">68</td> + <td class="button"><code>#\h</code></td> + <td><nobr> - </nobr></td> + <td>lower case h</td> +</tr> +<tr> + <td class="button">i</td> + <td class="button" align="right">151</td> + <td class="button" align="right">105</td> + <td class="button" align="right">69</td> + <td class="button"><code>#\i</code></td> + <td><nobr> - </nobr></td> + <td>lower case i</td> +</tr> +<tr> + <td class="button">j</td> + <td class="button" align="right">152</td> + <td class="button" align="right">106</td> + <td class="button" align="right">6A</td> + <td class="button"><code>#\j</code></td> + <td><nobr> - </nobr></td> + <td>lower case j</td> +</tr> +<tr> + <td class="button">k</td> + <td class="button" align="right">153</td> + <td class="button" align="right">107</td> + <td class="button" align="right">6B</td> + <td class="button"><code>#\k</code></td> + <td><nobr> - </nobr></td> + <td>lower case k</td> +</tr> +<tr> + <td class="button">l</td> + <td class="button" align="right">154</td> + <td class="button" align="right">108</td> + <td class="button" align="right">6C</td> + <td class="button"><code>#\l</code></td> + <td><nobr> - </nobr></td> + <td>lower case l</td> +</tr> +<tr> + <td class="button">m</td> + <td class="button" align="right">155</td> + <td class="button" align="right">109</td> + <td class="button" align="right">6D</td> + <td class="button"><code>#\m</code></td> + <td><nobr> - </nobr></td> + <td>lower case m</td> +</tr> +<tr> + <td class="button">n</td> + <td class="button" align="right">156</td> + <td class="button" align="right">110</td> + <td class="button" align="right">6E</td> + <td class="button"><code>#\n</code></td> + <td><nobr> - </nobr></td> + <td>lower case n</td> +</tr> +<tr> + <td class="button">o</td> + <td class="button" align="right">157</td> + <td class="button" align="right">111</td> + <td class="button" align="right">6F</td> + <td class="button"><code>#\o</code></td> + <td><nobr> - </nobr></td> + <td>lower case o</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>XLISP</b></td> +</tr> +<tr> + <td class="button">p</td> + <td class="button" align="right">160</td> + <td class="button" align="right">112</td> + <td class="button" align="right">70</td> + <td class="button"><code>#\p</code></td> + <td><nobr> - </nobr></td> + <td>lower case p</td> +</tr> +<tr> + <td class="button">q</td> + <td class="button" align="right">161</td> + <td class="button" align="right">113</td> + <td class="button" align="right">71</td> + <td class="button"><code>#\q</code></td> + <td><nobr> - </nobr></td> + <td>lower case q</td> +</tr> +<tr> + <td class="button">r</td> + <td class="button" align="right">162</td> + <td class="button" align="right">114</td> + <td class="button" align="right">72</td> + <td class="button"><code>#\r</code></td> + <td><nobr> - </nobr></td> + <td>lower case r</td> +</tr> +<tr> + <td class="button">s</td> + <td class="button" align="right">163</td> + <td class="button" align="right">115</td> + <td class="button" align="right">73</td> + <td class="button"><code>#\s</code></td> + <td><nobr> - </nobr></td> + <td>lower case s</td> +</tr> +<tr> + <td class="button">t</td> + <td class="button" align="right">164</td> + <td class="button" align="right">116</td> + <td class="button" align="right">74</td> + <td class="button"><code>#\t</code></td> + <td><nobr> - </nobr></td> + <td>lower case t</td> +</tr> +<tr> + <td class="button">u</td> + <td class="button" align="right">165</td> + <td class="button" align="right">117</td> + <td class="button" align="right">75</td> + <td class="button"><code>#\u</code></td> + <td><nobr> - </nobr></td> + <td>lower case u</td> +</tr> +<tr> + <td class="button">v</td> + <td class="button" align="right">166</td> + <td class="button" align="right">118</td> + <td class="button" align="right">76</td> + <td class="button"><code>#\v</code></td> + <td><nobr> - </nobr></td> + <td>lower case v</td> +</tr> +<tr> + <td class="button">w</td> + <td class="button" align="right">167</td> + <td class="button" align="right">119</td> + <td class="button" align="right">77</td> + <td class="button"><code>#\w</code></td> + <td><nobr> - </nobr></td> + <td>lower case w</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>XLISP</b></td> +</tr> +<tr> + <td class="button">x</td> + <td class="button" align="right">170</td> + <td class="button" align="right">120</td> + <td class="button" align="right">78</td> + <td class="button"><code>#\x</code></td> + <td><nobr> - </nobr></td> + <td>lower case x</td> +</tr> +<tr> + <td class="button">y</td> + <td class="button" align="right">171</td> + <td class="button" align="right">121</td> + <td class="button" align="right">79</td> + <td class="button"><code>#\y</code></td> + <td><nobr> - </nobr></td> + <td>lower case y</td> +</tr> +<tr> + <td class="button">z</td> + <td class="button" align="right">172</td> + <td class="button" align="right">122</td> + <td class="button" align="right">7A</td> + <td class="button"><code>#\z</code></td> + <td><nobr> - </nobr></td> + <td>lower case z</td> +</tr> +<tr> + <td class="button">{</td> + <td class="button" align="right">173</td> + <td class="button" align="right">123</td> + <td class="button" align="right">7B</td> + <td class="button"><code>#\{</code></td> + <td><nobr> - </nobr></td> + <td>opening curly brace</td> +</tr> +<tr> + <td class="button">|</td> + <td class="button" align="right">174</td> + <td class="button" align="right">124</td> + <td class="button" align="right">7C</td> + <td class="button"><code>#\|</code></td> + <td><nobr> - </nobr></td> + <td>vertical line</td> +</tr> +<tr> + <td class="button">}</td> + <td class="button" align="right">175</td> + <td class="button" align="right">125</td> + <td class="button" align="right">7D</td> + <td class="button"><code>#\}</code></td> + <td><nobr> - </nobr></td> + <td>closing curly brace</td> +</tr> +<tr> + <td class="button">~</td> + <td class="button" align="right">176</td> + <td class="button" align="right">126</td> + <td class="button" align="right">7E</td> + <td class="button"><code>#\~</code></td> + <td><nobr> - </nobr></td> + <td>tilde, approximate</td> +</tr> +<tr> + <td class="button">DEL</td> + <td class="button" align="right">177</td> + <td class="button" align="right">127</td> + <td class="button" align="right">7F</td> + <td class="button"><code></code></td> + <td><nobr> - </nobr></td> + <td>delete, cross-hatch box</td> +</tr> +<tr> + <td class="button"><b>Char</b></td> + <td class="button"><b>Oct</b></td> + <td class="button"><b>Dec</b></td> + <td class="button"><b>Hex</b></td> + <td class="button"><b>XLISP</b></td> +</tr> +</tbody></table></p> + +<hr> + +<a href="../start.htm">Nyquist / XLISP 2.0</a> - +<a href="../manual/contents.htm">Contents</a> | +<a href="../tutorials/tutorials.htm">Tutorials</a> | +<a href="../examples/examples.htm">Examples</a> | +<a href="../reference/reference-index.htm">Reference</a> + +</body></html> diff --git a/docsrc/xlisp/xlisp-doc/misc/c-printf.htm b/docsrc/xlisp/xlisp-doc/misc/c-printf.htm new file mode 100644 index 0000000..f87d62a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/misc/c-printf.htm @@ -0,0 +1,560 @@ +<html><head>
+
+<title>ANSI C 'printf' Format</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>ANSI C 'printf' Format</h1>
+
+<hr>
+
+<p><b>Nyquist/XLISP:</b> The
+<nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr> and
+<nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
+variables define format strings for the underlying 'sprintf' <nobr>C
+function</nobr>. <nobr>In C,</nobr> the same format string specification is
+used for 'fprint' [writes to <nobr>a file]</nobr>, 'printf' [writes to
+standard output] and 'sprintf' [writes to another string]. These three
+functions are meant in the following text with 'the printf functions'.</p>
+
+<p><b>ANSI C:</b> The printf functions write output under control of a
+format string that specifies how subsequent arguments are converted for
+output. If there are insufficient arguments for the format, the behavior is
+undefined. If the format is exhausted while arguments remain, the excess
+arguments are evaluated but are otherwise ignored. The printf functions
+return when the end of the format string is encountered.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="format-string"></a>
+
+<hr>
+
+<h2>Format String</h2>
+
+<hr>
+
+<p>The format string is composed of zero or more directives, which are
+ordinary characters <nobr>[except "%"]</nobr>, which are copied
+unchanged to the output stream, and conversion specifications, each of which
+results in fetching zero or more subsequent arguments. Each conversion
+specification is introduced by the <nobr>character "%"</nobr>:</p>
+
+<pre class="example">
+<font color="#AA0000">%</font>[<font color="#0000CC">flags</font>][<font color="#0000CC">field-with</font>][<font color="#0000CC">precision</font>][<font color="#0000CC">data-type</font>]<font color="#880000">conversion-type</font>
+</pre>
+
+<p>After the "%", the following appear in sequence:</p>
+
+<ul>
+
+<li><p><b>Flags</b> - Zero or more <a href="#flags">flags</a> that modify
+the meaning of the conversion specification.</p></li>
+
+<li><p><b>Field Width</b> - <nobr>An optional</nobr> decimal integer
+specifying a minimum field width. <nobr>If the</nobr> converted value has
+fewer characters than the field width, it will be padded with spaces on the
+left to the field width. <nobr>The field</nobr> is padded on the right if
+the <nobr><a href="#minus-flag"> − </a> flag</nobr> has been
+given, or padded with zeros if the
+<nobr><a href="#zero-flag"> 0 </a> flag</nobr> had been
+given. <nobr>A negative</nobr> integer, given as '<nobr>field width</nobr>'
+argument, is interpreted as a
+<nobr><a href="#minus-flag"> − </a> flag</nobr> followed by
+a positive <nobr>field width</nobr>.</p></li>
+
+<li><p><b>Precision</b> - <nobr>An optional</nobr> decimal integer that
+gives the minimum number of digits to appear for
+<a href="#integer">integer</a> conversions, the number of digits to appear
+after the
+<nobr>decimal-point</nobr> character for <nobr>floating-point</nobr>
+<nobr><a href="#float-e"> e </a></nobr> and
+<nobr><a href="#float-f"> f </a></nobr> conversions, or the
+maximum number of significant digits for the <nobr>floating-point</nobr>
+<nobr><a href="#float-g"> g </a></nobr> conversion.</p>
+
+<p>The precision takes the form of a period character followed by an
+optional decimal integer:</p>
+
+<pre class="example">
+.[<font color="#0000CC">integer</font>]
+</pre>
+
+<p><nobr>If the</nobr> integer is omitted, it is treated as zero, a
+negative precision argument is taken as if it were missing.</p>
+
+<p><b>Note:</b> <nobr>In C</nobr>, the precision also specifies the
+maximum number of characters to be written from a string in <nobr>'s'
+conversion</nobr>, but "%s" should not be used in the XLISP
+<nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr> or
+<nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
+variables, otherwise XLISP will crash.</p></li>
+
+</li>
+
+<li><p><b>Data Type</b> - <nobr>An optional</nobr> character specifying a
+<nobr><a href="#data-type">data type</a></nobr> to be used for the
+conversion.</p>
+
+<p><b>XLISP:</b> Nyquist/XLISP uses <nobr>C 'long'</nobr> signed integers
+and <nobr>C 'double'</nobr> floats only, so with <nobr>floating-point</nobr>
+numbers no special <nobr><a href="#data-type">data type</a></nobr> needs to
+be given, while <a href="#integer">integer</a> conversions should always be
+prefixed by a <nobr>'l' [lowercase L]</nobr>, otherwise the printed
+representation of integer numbers may be differently than the behaviour of
+the Nyquist/XLISP functions.</nobr></p></li>
+
+<li><p><b>Conversion Type</b> - <nobr>A character</nobr> that specifies the
+<nobr><a href="#conversion-type">conversion type</a></nobr> to be
+applied.</p></li>
+
+</ul>
+
+<p><b>Not with Nyquist/XLISP:</b> <nobr>In C</nobr>, a '<nobr>field
+width</nobr>' or 'precision', or both, may be indicated by an asterisk *
+instead of a digit string. In this case, an int argument supplies the field
+width or precision. The arguments specifying field width or precision, or
+both, shall appear [in that order] before the argument [if any] to be
+converted.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="flags"></a>
+
+<hr>
+
+<h2>Flags</h2>
+
+<hr>
+
+<p>The flag characters and their meanings are:</p>
+
+<p><div class="box">
+
+<dl>
+
+<a name="minus-flag"></a>
+
+<dt><p><nobr>− [minus sign character]</nobr></p></dt>
+
+<dd><p>The result of the conversion will be <nobr>left-justified</nobr>
+within the field.</p></dd>
+
+<a name="plus-flag"></a>
+
+<dt><p><nobr>+ [plus sign character]</nobr></p></dt>
+
+<dd><p>The result of a signed conversion will always begin with a plus or
+minus sign.</p></dd>
+
+<a name="space-flag"></a>
+
+<dt><p><nobr><i>space</i> [space character]</nobr></p></dt>
+
+<dd><p>If the first character of a signed conversion is not a sign, or if a
+signed conversion results in no characters, a space will be prepended to the
+result. <nobr>If the</nobr> 'space' and
+<nobr><a href="#plus-flag"> + </a> flags</nobr> both appear, the
+'space' flag will be ignored.</p></dd>
+
+<a name="hash-flag"></a>
+
+<dt><p><nobr># [hash character]</nobr></p></dt>
+
+<dd><p>The result is to be converted to an 'alternate form':</p>
+
+<p>Octal Numbers - For o conversion, it increases the precision to force the
+first digit of the result to be a zero.</p>
+
+<p>Hexadecimal Numbers - For x or X conversion, a nonzero result will have
+0x or 0X prepended to it.</p>
+
+<p>Floating-point Numbers - For e, E, f, g, and G conversions, the result
+will always contain a decimal-point character, even if no digits follow it
+(normally, a decimal-point character appears in the result of these
+conversions only if a digit follows it). For g and G conversions, trailing
+zeros will not be removed from the result. For other conversions, the
+behavior is undefined.</p>
+
+</dd>
+
+<a name="zero-flag"></a>
+
+<dt><p><nobr>0 [number zero character]</nobr></p></dt>
+
+<dd><p>For integer d, i, o, u, x, X, and floating-point e, E, f, g, G
+conversions, leading zeros [following any indication of sign or base] are
+used to pad to the <nobr><a href="#format-string">field width</a></nobr>.
+<nobr>No <a href="#space-flag">space</a></nobr> padding is performed.
+<nobr>If the</nobr> '0' and
+<nobr><a href="#minus-flag"> − </a> flags</nobr> both
+appear, the <nobr>'0' flag</nobr> will be ignored. For integer d, i, o, u,
+x, X conversions, if a <a href="#format-string">precision</a> is specified,
+the <nobr>'0' flag</nobr> will be ignored. <nobr>For other</nobr>
+conversions, the behavior is undefined.</p></dd>
+
+</dl>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="data-type"></a>
+
+<hr>
+
+<h2>Data Type</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+
+<dt><p><nobr><b>h</b> [lowercase H character]</nobr></p></dt>
+
+<dd><p>A following d, i, o, u, x, or X conversion specifier applies to a
+short int or unsigned short int argument [the argument will have been
+promoted according to the integral promotions, and its value shall be
+converted to short int or unsigned short int before printing].</p>
+
+<p>A following n conversion specifier applies to a pointer to a short int
+argument.</p></dd>
+
+<dt><p><nobr><b>l</b> [lowercase L character]</nobr></p></dt>
+
+<dd><p>A following d, i, o, u, x, or X conversion specifier applies to a
+long int or unsigned long int argument.</p>
+
+<p>A following n conversion specifier applies to a pointer to a long int
+argument.</p></dd>
+
+<dt><p><nobr><b>L</b> [uppercase L character]</nobr></p></dt>
+
+<dd><p>A following e, E, f, g, or G conversion specifier applies to a long
+double argument.</p></dd>
+
+</dl>
+
+</div></p>
+
+<p>If an h, l, or L appears with any other conversion specifier, the
+behavior is undefined.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="conversion-type"></a>
+
+<hr>
+
+<h2>Conversion Type</h2>
+
+<hr>
+
+<p><b>Integer</b> conversion:</p>
+
+<p><div class="box">
+
+<dl>
+
+<a name="integer"></a>
+
+<dt><p><nobr><b>d</b>, <b>i</b>, <b>o</b>, <b>u</b>, <b>x</b>,
+<b>X</b></nobr></p></dt>
+
+<dd><p>The integer argument is converted to:
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="center"><nobr>d</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td><nobr>signed decimal</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="center"><nobr>i</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td><nobr>signed decimal</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="center"><nobr>o</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td><nobr>unsigned octal</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="center"><nobr>u</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td><nobr>unsigned decimal</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="center"><nobr>x</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td><nobr>unsigned hexadecimal, using 'abcdef'</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td align="center"><nobr>X</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td><nobr>unsigned hexadecimal, using 'ABCDEF'</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>The <a href="#format-string">precision</a> specifies the minimum number
+of digits to appear. <nobr>If the</nobr> value being converted can be
+represented in fewer digits, it will be expanded with leading zeros. The
+default precision <nobr>is 1</nobr>. The result of converting a zero value
+with an explicit precision of zero results in no characters.</p>
+
+<b>XLISP:</b> Nyquist/XLISP uses <nobr>C 'long'</nobr> signed integers, so
+the integer conversions should always be prefixed by a <nobr>'l' [lowercase
+L]</nobr> indicating a '<nobr>long int</nobr>' <nobr>C
+<a href="#data-type">data type</a></nobr>, otherwise the printed
+representation of integer numbers may be differently than the behaviour of
+the Nyquist/XLISP functions.</p></dd>
+
+</dl>
+
+</div></p>
+
+<p><b>Floating-point</b> conversion:</p>
+
+<p><div class="box">
+
+<dl>
+
+<a name="float-f"></a>
+
+<dt><p><b>f</b></p></dt>
+
+<dd><p>The <nobr>floating-point</nobr> argument of <nobr>C data</nobr> type
+'double' is converted to decimal notation in the style:</p>
+
+<pre class="example">
+[-]<font color="#0000CC">ddd</font>.<font color="#0000CC">ddd</font>
+</pre>
+
+<p>The number of digits after the <nobr>decimal-point</nobr> character
+is equal to the <a href="#format-string">precision</a> specification.
+<nobr>If the</nobr> <a href="#format-string">precision</a> is missing, it is
+taken <nobr>as 6</nobr>. <nobr>If the</nobr>
+<a href="#format-string">precision</a> is explicitly zero, no
+<nobr>decimal-point</nobr> character appears. <nobr>If a</nobr>
+<nobr>decimal-point</nobr> character appears, at least one digit appears
+<nobr>before it</nobr>. <nobr>The value</nobr> is rounded to the appropriate
+number of digits.</p></dd>
+
+<a name="float-e"></a>
+
+<dt><p><b>e</b>, <b>E</b></p></dt>
+
+<dd><p>The <nobr>floating-point</nobr> argument of <nobr>C data</nobr> type
+'double' is converted in the style:</p>
+
+<pre class="example">
+[-]<font color="#0000CC">d</font>.<font color="#0000CC">ddd</font><font color="#AA0000">e</font>+-<font color="#0000CC">dd</font>
+</pre>
+
+<p>There is one digit before the <nobr>decimal-point</nobr> character
+[which is nonzero if the argument is nonzero] and the number of digits after
+it is equal to the <a href="#format-string">precision</a>. <nobr>If
+the</nobr> <a href="#format-string">precision</a> is missing, it is taken
+<nobr>as 6</nobr>. <nobr>If the</nobr>
+<a href="#format-string">precision</a> is zero, no
+<nobr>decimal-point</nobr> character appears. <nobr>The value</nobr> is
+rounded to the appropriate number of digits. <nobr>The exponent</nobr>
+always contains at least two digits. <nobr>If the</nobr> value is zero, the
+exponent is zero. <nobr>The "E"</nobr> conversion specifier will
+produce a number with 'E' instead of 'e' introducing the exponent.</p> </dd>
+
+<a name="float-g"></a>
+
+<dt><p><b>g</b>, <b>G</b></p></dt>
+
+<dd><p>The <nobr>floating-point</nobr> argument of <nobr>C data</nobr> type
+'double' is converted in style <a href="#float-f"> f </a> or
+<a href="#float-e"> e </a>, or in style
+<a href="#float-e"> E </a> in the case of a "G"
+conversion specifier, with the <a href="#format-string">precision</a>
+specifying the number of significant digits. <nobr>If an</nobr> explicit
+<a href="#format-string">precision</a> is zero, it is taken <nobr>as
+1</nobr>. <nobr>The style</nobr> used depends on the value converted.
+<nobr>Style <a href="#float-"> e </a></nobr> will be used only if
+the exponent resulting from such a conversion is less <nobr>than -4</nobr>
+or greater than or equal to the <a href="#format-string">precision</a>.
+Trailing zeros are removed from the fractional portion of the result.
+<nobr>A decimal-point</nobr> character appears only if it is followed by
+<nobr>a digit</nobr>.</p></dd>
+
+</dl>
+
+</div></p>
+
+<p>If a conversion specification is invalid, the behavior is undefined.
+<nobr>In no</nobr> case does a nonexistent or small
+<nobr><a href="#format-string">field width</a></nobr> cause truncation of a
+field. <nobr>If the</nobr> result of a conversion is wider than the
+<nobr><a href="#format-string">field width</a></nobr>, the field is expanded
+to contain the conversion result.</p>
+
+<p>The minimum value for the maximum number of characters produced by
+any single conversion shall be 509.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="other-conversion-types"></a>
+
+<hr>
+
+<h2>Other Conversion Types</h2>
+
+<hr>
+
+<p>This section contains a list of all other conversion types defined
+<nobr>in ANSI C</nobr>.</p>
+
+<p><b>Warning:</b> Do <b>not</b> use thse conversions with the XLISP
+<nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr> and
+<nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
+variables, because XLISP will produce nonsense or just simply will crash.
+<nobr>The XLISP</nobr> behaviour described below was tested with
+<nobr>Nyquist 3.03</nobr> in <nobr>December 2010</nobr>, compiled with
+<nobr>GCC 4.3.2</nobr> and <nobr>glibc 2.7</nobr> on <nobr>Debian 5
+[Lenny]</nobr>. <nobr>The behaviour</nobr> may be different with different
+Nyquist or XLISP versions, different <nobr>C compilers</nobr> and/or
+libraries, or different operating systems.</p>
+
+<p><div class="box">
+
+<dl>
+
+<dt><p><b>c</b></p></dt>
+
+<dd><p><b>ANSI C:</b> The integer argument is converted to an
+'<nobr>unsigned char</nobr>', and the resulting character is written.</p>
+
+<p><b>XLISP:</b> If the
+<nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr> or
+<nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
+is set <nobr>to "%c"</nobr>, then the lowest <nobr>8 bit</nobr>
+of the internal binary representation of the respective numbers will be
+printed as an <a href="ascii-table.htm">ASCII</a> character.</p></dd>
+
+<dt><p><b>s</b></p></dt>
+
+<dd><p><b>ANSI C:</b> The argument shall be a pointer to an array of
+character type. Characters from the array are written up to [but not
+including] a terminating null character. <nobr>If the</nobr>
+<a href="#format-string">precision</a> is specified, no more than that many
+characters are written. <nobr>If the</nobr>
+<a href="#format-string">precision</a> is not specified or is greater than
+the size of the array, the array shall contain a null character.</p>
+
+<b>XLISP:</b> If the
+<nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr> or
+<nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
+is set to "%s" and XLISP tries to print a respective number,
+XLISP crashes.</dd>
+
+<dt><p><b>p</b></p></dt>
+
+<dd><p><b>ANSI C:</b> The argument shall be a pointer to 'void'. The value
+of the pointer is converted to a sequence of printable characters, in an
+<nobr>implementation-defined</nobr> manner.</p>
+
+<p><b>XLISP:</b> If the
+<nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr>
+is set <nobr>to "%p"</nobr>, then floating-point numbers are
+printed <nobr>as "(nil)"</nobr>. <nobr>If the</nobr>
+<nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
+is set <nobr>to "%p"</nobr>, the integer numbers are printed as
+hexadecimal numbers, prefixed <nobr>with "0x"</nobr>.</p></dd>
+
+<dt><p><b>n</b></p></dt>
+
+<dd><p><b>ANSI C:</b> The argument shall be a pointer to an integer into
+which is written the number of characters written to the output stream so
+far by this call to the <nobr>C 'fprintf'</nobr> function.<nobr> No
+argument</nobr> is converted.</p>
+
+<b>XLISP:</b> If the
+<nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr> or
+<nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
+is set to "%n" and XLISP tries to print a respective number,
+XLISP crashes.</dd>
+
+<dt><p><b>%</b></p></dt>
+
+<dd><p><nobr><b>ANSI C:</b> A "%"</nobr> is written. <nobr>No
+argument</nobr> is converted. <nobr>The complete</nobr> conversion
+specification <nobr>shall be "%%"</nobr>.</p>
+
+<b>XLISP:</b> If the
+<nobr><a href="../reference/global-float-format.htm">*float-format*</a></nobr>
+is set to "%g%%" or the
+<nobr><a href="../reference/global-integer-format.htm">*integer-format*</a></nobr>
+is set to "%ld%%" then all respective numbers will be printed
+with a <nobr>trailing "%"</nobr>.</dd>
+
+</dl>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/misc/links.htm b/docsrc/xlisp/xlisp-doc/misc/links.htm new file mode 100644 index 0000000..d0e47d7 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/misc/links.htm @@ -0,0 +1,115 @@ +<html><head>
+<title>Lisp Links</title></head>
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Lisp Links</h1>
+
+<hr>
+
+<p>The most helpful book to learn XLISP I found 'Common Lisp, A Gentle
+Introduction to Symbolic Computation' by David Touretzky, mentioned in the
+Nyquist manual by Roger Dannenberg. The book can be downloaded for free
+from:</p>
+
+<ul>
+<li><nobr><a href="http://www.cs.cmu.edu/~dst/LispBook/index.html"
+>http://www.cs.cmu.edu/~dst/LispBook/index.html</a></nobr></li>
+</ul>
+
+<p>It's a book about Lisp in general, not only about Common Lisp, explaining
+and helping a lot to understand the the fundamental principles of Lisp
+programming.</p>
+
+<p>Unfortunately there seems to be no specific information source about
+XLISP programming in the internet [beside the David Betz manual and the Tim
+I Mikkelsen documents], probably because most Lisp dialects have been merged
+into the Common Lisp standard in the 1980s and 1990s.</p>
+
+<p>As a result of this I first had to learn Common Lisp to be able to
+re-construct how the examples in all the books could work with XLISP. This
+was a quite tedious way to learn and the main reason to start this document
+collection.</p>
+
+<hr>
+
+<h2>XLISP links</h2>
+
+<hr>
+
+<p>The official XLISP homepage is:</p>
+
+<ul>
+<li><a href="http://www.mv.com/ipusers/xlisper/">http://www.mv.com/ipusers/xlisper/</a></li>
+</ul>
+
+<p>The official Nyquist homepage is:</p>
+
+<ul>
+<li><a href="http://www.cs.cmu.edu/~music/music.software.html"
+>http://www.cs.cmu.edu/~music/music.software.html</a></li>
+</ul>
+
+<hr>
+
+<h2>Common Lisp links</h2>
+
+<hr>
+
+<p>Copies of 'Common Lisp, the Language, <nobr>2nd Edition'</nobr> by Guy
+Steele [known as 'CltL2'] can be downloaded in various formats for free
+from the CMU archives:</p>
+
+<ul>
+<li><nobr><a href="http://www.cs.cmu.edu/Groups/AI/html/cltl/cltl2.html"
+>http://www.cs.cmu.edu/Groups/AI/html/cltl/cltl2.html</a></nobr></li>
+</ul>
+
+<p>It is a quite huge book explaining all details and discussions about the
+Common Lisp standard and is a real good Common Lisp information source.
+Unfortunately it is not very useful for learning XLISP out of it.</p>
+
+<p>The most recent document about the Common Lisp standard is the 'Common
+Lisp Hypespec' [re-worked in 2005]. It is available for online reading
+under:</p>
+
+<ul>
+<li><nobr><a href="http://www.lispworks.com/documentation/HyperSpec/Front/index.htm"
+>http://www.lispworks.com/documentation/HyperSpec/Front/index.htm</a></nobr></li>
+</ul>
+
+<p>or as a 'tar.gz' package for offline reading from:</p>
+
+<ul>
+<li><nobr><a href="ftp://ftp.lispworks.com/pub/software_tools/reference/HyperSpec-7-0.tar.gz"
+>ftp://ftp.lispworks.com/pub/software_tools/reference/HyperSpec-7-0.tar.gz</a></nobr></li>
+</ul>
+
+<p>If you have no idea how to deal with 'tar.gz' packages on Windows
+computers and the 'tar.gz' file doesn't open automatically by clicking on
+it, the probably most easiest way is using the '7-zip' program available for
+free from:</p>
+
+<ul>
+<li><nobr><a href="http://www.7-zip.org/"
+>http://www.7-zip.org/</a></nobr></li>
+</ul>
+
+<br>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/misc/preface.htm b/docsrc/xlisp/xlisp-doc/misc/preface.htm new file mode 100644 index 0000000..eb3293f --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/misc/preface.htm @@ -0,0 +1,116 @@ +<html><head>
+<title>XLISP Preface</title></head>
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Preface</h1>
+
+<hr>
+
+
+<p>This is a collection of documents about <nobr>'XLISP 2.0'</nobr> as a
+programming language in general. It is intended to be used together with
+Nyquist, a language for composition and sound synthesis. It includes the
+second re-work of the Tim I Mikkelsen 'XLISP Language Reference', linked
+against the original <nobr>'XLISP 2.0</nobr> Manual' by David Betz.</p>
+
+<p>Both manuals are linked against each other and intended to be used as
+'one' manual. You can jump back and forth from a function description in the
+'XLISP Manual' to the description in the 'Language Reference' and vice versa
+with ease.</p>
+
+<p>The navigation bar at the top and the bottom of each page need some
+explanation. From the left to right you will find the following links:</p>
+
+<ul>
+
+<li><p><a href="../start.htm">XLISP</a> - always returns to the main
+page from everywhere, helping you to find your way back if you get lost in
+the information jungle.</p></li>
+
+<li><p><a href="../manual/xlisp-man-index.htm">XLISP 2.0</a> - opens the
+front page of the <nobr>'XLISP 2.0</nobr> Manual' by David Betz with links
+to all chapters so you can read it like a book.</p></li>
+
+<li><p><a href="../manual/contents.htm">Contents</a> - opens
+the detailed contents page of the <nobr>'XLISP 2.0</nobr> Manual' with
+links to all functions and symbols sorted by topic.</p></li>
+
+<li><p><a href="../reference/reference-index.htm">Reference</a> - opens the
+index page of the 'XLISP Language Reference' with links to all XLISP
+functions and symbols sorted in alphabetical order.</p></li>
+
+<li><p>The <font color="#0000CC"><u>Previous</u></font> and <font
+color="#0000CC"><u>Next</u></font> links are a bit tricky. As expected they
+move to the previous and next pages, but in the <nobr>'XLISP 2.0</nobr>
+Manual' they move through the manual while in the 'XLISP Language Reference'
+they move through the reference. This needs some accustomisation but I have
+worked like this during the last few month and found it the best possible
+solution. You can always go back to the pages where you have been before by
+using the 'back' button of your browser.</p></li>
+
+</ul>
+
+<p>During the second re-work of the 'XLISP Language Reference' I have sorted
+out all functions that were related to <nobr>'XLISP 2.1'</nobr> and
+<nobr>'XLISP Plus'.</nobr> They can now be found on their own page under
+<a href="../xlisp-plus/xlisp-plus-index.htm">XLISP Plus Functions</a>.</p>
+
+<p>I also have sorted out of the 'XLISP 2.0 Manual' all functions added by
+Nyquist to the XLISP interpreter to an extra page, for just the simple
+reason that unlike <nobr>XLISP 2.0,</nobr> Nyquist still evolves and it is
+easier to maintain a single page with <nobr><a
+href="../manual/xlisp-man-033.htm">Nyquist Functions</a></nobr> than
+sixteen [or more] functions spread all over the manual.</p>
+
+<hr>
+
+<p>Things still to be done and how you can help:</p>
+
+<hr>
+
+<p>First of all, please note that this is a work in progress and not a final
+version. There probably still are bugs and quirks that need to be resolved
+and you can help by writing an e-mail to
+<a href="mailto:edgar-rft@web.de">edgar-rft@web.de</a> if you find some and
+I will try to fix it as soon as possible.</p>
+
+<p>This does not mean that these documents are 'overloaded with
+bugs' but XLISP was <nobr>[and is]</nobr> an experimental language that
+itself was re-worked several times and most of the time during the last
+months I was busy with sorting out what really matters out of the manuals I
+had collected over a period of two and a half years about several XLISP
+versions and mutations.</p>
+
+<p>In case of doubt I will prefer the Nyquist version of <nobr>XLISP
+2.0</nobr> because this is the version I work with most often and the
+original intention of this document collection was to support the Nyquist
+manual with better XLISP information.</p>
+
+<p>Also please note that I do not want to change the David Betz manual more
+than necessary, because I consider it as the most original information
+source. Instead I whould like to improve the 'XLISP Language <a
+href="../reference/reference-index.htm">Reference</a>' by better
+explanations and source code examples. I also have not tested really *all*
+examples with Nyquist yet. If you find bugs please write me an email.</p>
+
+<p>If you have any further ideas or suggestions how these documents can be
+improved please write to
+<a href="mailto:edgar-rft@web.de">edgar-rft@web.de</a>.</p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/objects/advanced-objects.htm b/docsrc/xlisp/xlisp-doc/objects/advanced-objects.htm new file mode 100644 index 0000000..925d0a8 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/objects/advanced-objects.htm @@ -0,0 +1,590 @@ +<html><head>
+
+<title>Advanced XLISP Objects</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Advanced XLISP Objects</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="standard-xlisp-objects">Standard XLISP Objects</a></nobr></li>
+<li><nobr><a href="initializing-class-variables">Initializing Class Variables</a></nobr></li>
+<li><nobr><a href="accessing-class-and-instance-variables">Accessing Class and Instance Variables</a></nobr></li>
+</ol>
+
+<a name="standard-xlisp-objects"></a>
+
+<hr>
+
+<h2>Standard XLISP Objects</h2>
+
+<hr>
+
+<p>Define a class with an instance variable and a class variable:</p>
+
+<pre class="example">
+(setq my-class (send class :new '(instance-var) '(class-var)))
+</pre>
+
+<p>Look at the layout of the new class:</p>
+
+<pre class="example">
+> (send my-class :show)
+Object is #<Object...>, Class is #<Object...>
+ MESSAGES = NIL
+ IVARS = (INSTANCE-VAR)
+ CVARS = (CLASS-VAR)
+ CVALS = #(NIL) <font color="#008844">; default init-value of class variables</font>
+ SUPERCLASS = #<Object...>
+ IVARCNT = 1
+ IVARTOTAL = 1
+#<Object...>
+</pre>
+
+<p>Make an instance of '<nobr>my-class</nobr>':</p>
+
+<pre class="example">
+(setq my-object (send my-class :new))
+</pre>
+
+<p>Look at the layout of the new object:</p>
+
+<pre class="example">
+> (send my-object :show)
+Object is #<Object...>, Class is #<Object...>
+ INSTANCE-VAR = NIL <font color="#008844">; default init-value of instance variables</font>
+#<Object...>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>Initializing Class Variables</h2>
+
+<hr>
+
+<p><b>1.</b> Add an :isnew <nobr>init-method</nobr> to '<nobr>my-class</nobr>':</p>
+
+<pre class="example">
+(send my-class :answer :isnew nil '((setq class-var 1)))
+</pre>
+
+<p>Now reset the class:</p>
+
+<pre class="example">
+(send my-class :isnew) => <font color="#AA0000">error: too few arguments</font>
+</pre>
+
+<p>It turns out that :isnew needs at least a list of instance variables plus
+an optional list of class variables:</p>
+
+<pre class="example">
+(send my-class :isnew '(ivar)) <font color="#008844">; overwrites INSTANCE-VAR, deletes CLASS-VAR</font>
+(send my-class :isnew '(ivar) '(cvar))) <font color="#008844">; overwrites INSTANCE-VAR and CLASS-VAR</font>
+</pre>
+
+<p><b>2.</b> Add an :init method to '<nobr>my-class</nobr>':</p>
+
+<pre class="example">
+(send my-class :answer :init nil '((setq class-var 1)))
+</pre>
+
+<p>Now call the :init method:</p>
+
+<pre class="example">
+(send my-class :init) => <font color="#AA0000">error: no method for this message - :INIT</font>
+</pre>
+
+<p>This is not true, there is an :init method:</p>
+
+<pre class="example">
+> (send my-class :show)
+Object is #<Object...>, Class is #<Object...>
+ MESSAGES = ((<font color="#0000CC">:INIT</font> . <font color="#0000CC">#<Closure-:INIT:...></font>))
+ IVARS = (INSTANCE-VAR)
+ CVARS = (CLASS-VAR)
+ CVALS = #(NIL)
+ SUPERCLASS = #<Object...>
+ IVARCNT = 1
+ IVARTOTAL = 1
+#<Object...>
+</pre>
+
+<p>The problem here is that in XLISP, methods cannot be called from the
+class they were defined in, methods only can be called from instances, and
+exactly the same happens with manipulating class variables. There seems to
+be no standard XLISP way to initialize class variables with values at the
+time when the class is defined.</p>
+
+<p><b>3.</b> The only way I know in XLISP to initialize a class variable is
+to create an instance of the class and set the class variable e.g. from the
+:isnew method of the instance:</p>
+
+<pre class="example">
+(setq my-object (send my-class :new))
+</pre>
+
+<p>The :isnew method of '<nobr>my-object</nobr>', inherited from
+'<nobr>my-class</nobr>', has set the class variable in
+'<nobr>my-class</nobr>' to a new value:</p>
+
+<pre class="example">
+> (send my-class :show)
+Object is #<Object...>, Class is #<Object...>
+ MESSAGES = ((:ISNEW . #<Closure-:ISNEW:...>))
+ IVARS = (INSTANCE-VAR)
+ CVARS = (CLASS-VAR)
+ CVALS = #(1) <font color="#008844">; new value of CLASS-VAR</font>
+ SUPERCLASS = #<Object...>
+ IVARCNT = 1
+ IVARTOTAL = 1
+#<Object...>
+</pre>
+
+<p>This works, but now I have two problems:</p>
+
+<ol>
+
+<li><p>If a class variable is set from an instance's :isnew method,
+inherited from the superclass, then, whenever an instance is created, the
+class variable will be reset to its initial value. <nobr>Note that</nobr> in
+Lisp, instances can be created at arbitrary <nobr>run-time</nobr>, not only
+at the beginning of a program. Setting class variables from an :isnew method
+can produce unexpected <nobr>side-effects</nobr> if a class variable is used
+for object <nobr>inter-communication</nobr>.</p></li>
+
+<li><p>Because instances can be created at arbitrary runtime, a framework
+would need to be written when a class variable is allowed to be set or reset
+and <nobr>when not</nobr>. <nobr>Ok, if</nobr> class variables are used for
+object <nobr>inter-communication</nobr>, a framework needs to be witten
+anyway, but I do not want to be forced to think about this only because I
+want to initialize a single class variable.</p></li>
+
+</ol>
+
+<p><b>4.</b> Here is a trick I use to initialize class variables.</p>
+
+<p>Create a class with class variables:</p>
+
+<pre class="example">
+(setq my-class (send class :new nil '(cvar-1 cvar-2)))
+</pre>
+
+<p>Add an :isnew method to set the class variables:</p>
+
+<pre class="example">
+(send my-class :answer :isnew nil '((setq cvar-1 "a" cvar-2 "b")))
+</pre>
+
+<p>Create a temporary dummy object to initialize the class variables:</p>
+
+<pre class="example">
+(let ((x (send my-class :new))))
+</pre>
+
+<p>Replace the :isnew method with a dummy version <nobr>[or a</nobr> real
+version, initializing the instance variables]:</p>
+
+<pre class="example">
+(send my-class :answer :isnew nil nil)
+</pre>
+
+<p>Now I have a class with initialized class variables:</p>
+
+<pre class="example">
+> (send my-class :show)
+Object is #<Object...>, Class is #<Object...>
+ MESSAGES = ((:ISNEW . #<Closure-:ISNEW...>)) <font color="#008844">; dummy method</font>
+ IVARS = NIL
+ CVARS = (CVAR-1 CVAR-2) <font color="#008844">; class variables</font>
+ CVALS = #("a" "b") <font color="#008844">; init values</font>
+ SUPERCLASS = #<Object...>
+ IVARCNT = 0
+ IVARTOTAL = 0
+#<Object...>
+</pre>
+
+<p>See defclass below how to make this work automatically.</p>
+
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>Accessing Class and Instance Variables</h2>
+
+<hr>
+
+<pre class="example">
+(setq my-class (send class :new '(i-var) '(c-var)))
+(setq my-object (send my-class :new))
+</pre>
+
+<p>A message to read internal class and instance variables:</p>
+
+<pre class="example">
+(send my-class :answer :<font color="#0000CC">internal-slot-get</font> '(slot-name)
+ '((eval slot-name)))
+</pre>
+
+<p>A message to write internal class and instance variables:</p>
+
+<pre class="example">
+(send my-class :answer :<font color="#0000CC">internal-slot-set</font> '(slot-name value)
+ '((eval (list 'setq slot-name value))))
+</pre>
+
+<p><div class="box">
+
+<p><b>Implementation Notes</b></p>
+
+<p><b>1.</b> It's not really good Lisp style to explicitely call 'eval' in
+Lisp code at <nobr>run-time</nobr>, because 'eval' produces a lot of
+overhead, but here the only way to get access to the internal environment of
+an object is passing the message arguments to 'eval' inside the object
+itself.</p>
+
+<p><b>2.</b> In the XLISP object system, an :answer message can only be
+accessed in an <b>instance</b> of a class <nobr>[a sub-class</nobr> or on
+object], but not in the class, where the :answer message has been defined,
+so the :internal-slot accessor will only work in '<nobr>my-object</nobr>'
+but ont in '<nobr>my-class</nobr>'.</p>
+
+<p><b>3.</b> If a method had been changed in a superclass, the change will
+automatically be inherited by all instances of the class
+[<nobr>sub-classes</nobr> and objects], with no need to redefine them.</p>
+
+<p><b>Warning:</b> If '<nobr>internal-slot-set</nobr>' is given a
+<nobr>slot-name</nobr> that doesn't exist inside the object, a global
+variable will be created.</p>
+
+</div></p>
+
+<p>Reading and writing an instance variable:</p>
+
+<pre class="example">
+> (send my-object :internal-slot-get 'i-var) <font color="#008844">; read</font>
+NIL
+
+> (send my-object :internal-slot-set 'i-var 55) <font color="#008844">; write</font>
+55
+
+> (send my-object :internal-slot-get 'i-var) <font color="#008844">; read</font>
+55
+
+> (send my-object :show)
+Object is #<Object: #9b95998>, Class is #<Object: #9b95c50>
+ I-VAR = 55 <font color="#008844">; new value</font>
+#<Object: #9b95998>
+</pre>
+
+<p>Reading and writing a class variable:</p>
+
+<pre class="example">
+> (send my-object :internal-slot-get 'c-var) <font color="#008844">; read</font>
+NIL
+
+> (send my-object :internal-slot-set 'c-var 123) <font color="#008844">; write</font>
+123
+
+> (send my-object :internal-slot-get 'c-var) <font color="#008844">; read</font>
+123
+
+> (send my-class :show)
+Object is #<Object: #9b95c50>, Class is #<Object: #9af7dd4>
+ MESSAGES = ((:INTERNAL-SLOT-GET . #<Closure-:INTERNAL-SLOT-GET: #9b90080>)
+ (:INTERNAL-SLOT-SET . #<Closure-:INTERNAL-SLOT-SET: #9b900d4>))
+ IVARS = (I-VAR)
+ CVARS = (C-VAR)
+ CVALS = #(123) <font color="#008844">; new value</font>
+ SUPERCLASS = #<Object: #9af7dc8>
+ IVARCNT = 1
+ IVARTOTAL = 1
+#<Object: #9b95c50>
+</pre>
+
+<p>See the '<nobr>slot-get</nobr>' and '<nobr>slot-set</nobr>' functions
+below how this can be generalized to access any class or instance variable
+in any class or object via only two functions.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="defclass"></a>
+
+<hr>
+
+<h2>defclass</h2>
+
+<hr>
+
+<p>The original RBD 'defclass' macro:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">defclass</font> (name super locals class-vars)
+ (if (not (boundp name))
+ (if super
+ `(setq ,name (send class :new ',locals ',class-vars ,super))
+ `(setq ,name (send class :new ',locals ',class-vars)))))
+</pre>
+
+<p>In order to read or write XLISP class or object variables two
+<nobr>slot-acessor</nobr> messages need to be added to every new
+<nobr>top-level</nobr> class:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">defclass</font> (name super locals class-vars)
+ (when (boundp name)
+ (format t <font color="#880000">";; WARNING: redefining ~a~%"</font> name))
+ (if super
+ `(setq ,name (send class :new ',locals ',class-vars ,super))
+ `(progn
+ (setq ,name (send class :new ',locals ',class-vars))
+ (send ,name :answer :internal-slot-set '(slot-name value)
+ '((eval (list 'setq slot-name value))))
+ (send ,name :answer :internal-slot-get '(slot-name)
+ '((eval slot-name))))))
+</pre>
+
+<p>The third version provides <nobr>'let'-syntax</nobr> with instance and
+class variables. <nobr>A list</nobr> of symbols will create variables
+initialized <nobr>to NIL</nobr>. This is the XLISP default behaviour.
+<nobr>If an</nobr> element is a <nobr>(symbol value)</nobr> list, then the
+variable will be initialized with 'value', as soon as an instance of the
+class is created.</p>
+
+<p><div class="box">
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td colspan="7"><nobr>(<b>defclass</b> <i>class</i> {<i>superclass</i> | NIL}</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code>({</nobr></td>
+ <td align="center"><nobr><i>ivar</i></nobr></td>
+ <td><nobr> | (</nobr></td>
+ <td align="center"><nobr><i>ivar</i></nobr></td>
+ <td><nobr> <i>init-form</i></nobr></td>
+ <td><nobr>)} ... )<code> </code></nobr></td>
+ <td><nobr>; instance variables</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code>({</nobr></td>
+ <td align="center"><nobr><i>cvar</i></nobr></td>
+ <td><nobr> | (</nobr></td>
+ <td align="center"><nobr><i>cvar</i></nobr></td>
+ <td><nobr> <i>init-form</i></nobr></td>
+ <td><nobr>)} ... ))<code> </code></nobr></td>
+ <td><nobr>; class variables</nobr></td>
+</tr>
+</tbody></table></p>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">expand-init-values</font> (vars var-list init-list)
+ (let ((var (gensym)))
+ `(dolist (,var ,vars (setq ,var-list (reverse ,var-list)
+ ,init-list (reverse ,init-list)))
+ (cond ((symbolp ,var)
+ <font color="#008844">;; if the element is a single symbol,</font>
+ <font color="#008844">;; then add it to the variable list</font>
+ (push ,var ,var-list))
+ ((and (listp ,var) (symbolp (first ,var)))
+ <font color="#008844">;; if the element is a (symbol value) list, then add</font>
+ <font color="#008844">;; an (setq symbol value) element to the init-list</font>
+ (push (list 'setq (first ,var) (second ,var)) ,init-list)
+ <font color="#008844">;; and add the symbol to the variable-list</font>
+ (push (first ,var) ,var-list))
+ (t (error <font color="#880000">"bad argument type"</font> ,var))))))
+
+(defmacro <font color="#0000CC">with-unique-names</font> (symbols &rest body)
+ `(let ,(mapcar #'(lambda (x) `(,x (gensym))) symbols) ,@body))
+
+(defmacro <font color="#0000CC">defclass</font> (name super class-vars instance-vars)
+ (with-unique-names (class-list class-init instance-list instance-init x)
+ `(let (,instance-list ,instance-init ,class-list ,class-init)
+ (expand-init-values ',class-vars ,class-list ,class-init)
+ (expand-init-values ',instance-vars ,instance-list ,instance-init)
+ (if (boundp ',name)
+ (format t <font color="#880000">";; Redefining ~a~%"</font> ',name)
+ (format t <font color="#880000">";; CLASS ~a~%"</font> ',name))
+ (format t <font color="#880000">";; CVARS ~a~%"</font> ',class-vars)
+ (format t <font color="#880000">";; IVARS ~a~%"</font> ',instance-vars)
+ ,(if super
+ `(setq ,name (send class :new ,instance-list ,class-list ,super))
+ `(setq ,name (send class :new ,instance-list ,class-list)))
+ <font color="#008844">;; initialize class and instance variables</font>
+ (when ,class-list
+ (send ,name :answer :isnew nil ,class-init)
+ (let ((,x (send ,name :new)))))
+ (when (or ,instance-list ,class-list)
+ (send ,name :answer :isnew nil ,instance-init))
+ <font color="#008844">;; add slot-accessors to top-level classes</font>
+ ,(unless super
+ `(progn
+ (send ,name :answer :internal-slot-set '(slot-name value)
+ '((eval (list 'setq slot-name value))))
+ (send ,name :answer :internal-slot-get '(slot-name)
+ '((eval slot-name))))))))
+</pre>
+
+<p><nobr>Sub-classes</nobr> and objects inherit their acessors from the
+<nobr>super-class</nobr>.</p>
+
+<p>Define a class with an <nobr>instance-variable</nobr>, a
+<nobr>class-variable</nobr> and slot acessors:</p>
+
+<pre class="example">
+> (defclass my-class nil
+ ((a 1) (b 2) (c 3))
+ ((d 4) (e 5) (f 6)))
+
+>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="slot-value"></a>
+
+<hr>
+
+<h2>Generalized Slot Accessors</h2>
+
+<hr>
+
+<p>Now the slot accessors for internal class and instance variables can be
+defined as ordinary XLISP functions:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">slot-set</font> (object slot-name value)
+ (send object :internal-slot-set slot-name value))
+
+(defun <font color="#0000CC">slot-get</font> (object slot-name)
+ (send object :internal-slot-get slot-name))
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+> (slot-set my-object 'i-var 333)
+333
+
+> (slot-get my-object 'i-var)
+333
+</pre>
+
+<p>Even typing the quote could be saved if 'slot-set' and 'slot-get' are
+defined as macros:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">slot-set</font> (object slot-name value)
+ `(send ,object :internal-slot-set ',slot-name ,value))
+
+(defmacro <font color="#0000CC">slot-get</font> (object slot-name)
+ (send ,object :internal-slot-set ',slot-name ,value))
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+> (slot-set my-object i-var 444)
+444
+
+> (slot-get my-object i-var)
+444
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>Removing a Method from a Class or Instance</h2>
+
+<hr>
+
+<p>In Smalltalk, if a method's body is unbound and no other object refernces
+the method, then the method is automatically garbage collected.
+Unfortunately in XLISP this doesn't work because the instance variables,
+including the list of methods, are not accessed by the garbage collector
+<nobr>at all</nobr>. This means that even if the message body is set to NIL,
+the message is not garbage collected, instead the '<nobr>no function</nobr>'
+message returns NIL and blocks the <nobr>built-in</nobr> search for
+<nobr>super-class</nobr> messages.</p>
+
+<p>Because messages cannot be removed from XLISP objects, the only way to
+make a message 'disappear' is to replage it's body by a call to the
+<nobr>super-class</nobr>, passing the arguments of the original message:</p>
+
+<pre class="example">
+(defun remove-method (object message-selector &rest args)
+ (send object message-selector
+ (send-super message-selector args))
+</pre>
+
+<p>Shit: this doesn't work if the metod is defined in a super-class.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/objects/smalltalk.htm b/docsrc/xlisp/xlisp-doc/objects/smalltalk.htm new file mode 100644 index 0000000..48c4712 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/objects/smalltalk.htm @@ -0,0 +1,441 @@ +<html><head>
+
+<title>Smalltalk Object Model</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>The Smalltalk Object Model</h1>
+
+<hr>
+
+<p>This page is based on a document written by Glenn Hollowell:</p>
+
+<ul>
+<li><nobr><a href="http://www.objs.com/x3h7/smalltalk.htm"
+>http://www.objs.com/x3h7/smalltalk.htm</a></nobr></li>
+</ul>
+
+<p>The original document has been adapted for use with the <nobr>XLISP
+2.0</nobr> object system.</p>
+
+<hr>
+
+<h2>1 Basic Concepts</h2>
+
+<hr>
+
+<p>Within the context of Smalltalk, objects are implemented in code through
+encapsulation and polymorphism.</p>
+
+<p>Encapsulation is the approach used in Smalltalk to bundle everything
+needed into an object to preserve the integrity of the enclosed data.
+<nobr>The code</nobr> within an object performs operations on the objects
+internal data. Operations in Smalltalk are performed as the result of a
+messages being sent to an object to execute a specific portion of its code,
+usually called <nobr>a 'method'</nobr>.</p>
+
+<p>Polymorphism is the way that the Smalltalk language allows methods of the
+same name to have predictable and meaningful results in related instances,
+yet perform the operations differently to achieve the results.</p>
+
+<p>Polymorphism is typically implemented in Smalltalk through the
+abstraction of the common properties of a group of objects into classes and
+hierarchically subclassing shared properties using inheritance, along with
+specialization of the subclass to define the differences.</p>
+
+<p>Classes serve as templates because they define the instance variables for
+all the class instance variables and methods. <nobr>The instance</nobr> of a
+class is created by sending a
+<a href="../reference/keyword-new.htm">:new</a> message to the class which
+uniquely identifies the object instance and allocates space for its
+variables.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>2 Objects</h2>
+
+<hr>
+
+<p>An object is an encapsulated software component made up of memory and
+operations that creates a coherent programming entity. All objects are an
+instance of a class. Objects have public and private properties. An object's
+implementation details are private and are hidden from other objects.
+
+<ul>
+
+<li><p>An object's public properties are its messages that make up its
+interface.</p></li>
+
+<li><p>The object's private properties are its variables.</p></li>
+
+</ul>
+
+<p>Interaction with an object only occurs via these messages to its
+interface. <nobr>All object</nobr> instances of a given class have a common
+message interface.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>2.1 Operations</h2>
+
+<hr>
+
+<p>An operation is the action taken by an object instance as result of a
+message being received through the object's interface. Messages requesting
+operations are addressed to specific recipient object instances, thus
+Smalltalk uses the 'classical' object model and the method to execute in
+response to a message is determined by searching the object's class
+hierarchy.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>2.2 Requests</h2>
+
+<hr>
+
+<p>A request is act of sending a message to an object's interface with the
+expectation that the object will perform a known operation that is
+associated with the message.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>2.3 Messages</h2>
+
+<hr>
+
+<p>A message is a request to an object instance to perform an operation. A
+message expression consists of a receiver, selector [message name], and
+potentially some arguments. <nobr>The selector</nobr> must be mapped to a
+method of the same name, encapsulated in the receiver object's class
+hierarchy. <nobr>The arguments</nobr>, if any, are used by the method to
+perform its operation.</p>
+
+<pre class="example">
+(send <font color="#0000CC">receiver :selector</font> [<font color="#0000CC">arguments</font>])
+</pre>
+
+<p>In Smalltalk there exist several message types, like unary, binary, and
+keyword messages. <nobr>In XLISP</nobr> there is only one message type, so
+the description of the Smalltalk message types has been omitted from this
+document.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>2.4 Specification of Behavioral Semantics</h2>
+
+<hr>
+
+<p>Behavior is defined by methods specified in classes which are implemented
+as class instances and execution is triggered in those instances by message
+requests.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>2.5 Methods</h2>
+
+<hr>
+
+<p>A method is the executable code rendered in the class and executed in the
+context of an object instance. It defines how to perform an operation in the
+object instance. It is made up of a message pattern that is used to match
+against incoming messages, temporary variables, and a sequence of
+instructions. A method execution is triggered when message is received that
+matches the methods' message pattern.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>2.6 State</h2>
+
+<hr>
+
+<p>The state of an instance is represented by the values of its instance
+variables.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>2.7 Object Lifetime</h2>
+
+<hr>
+
+<p>Object instances are created with the
+<a href="../reference/keyword-new.htm">:new</a> method. Each object
+instance is given a unique identifier called an object pointer or object
+reference.</p>
+
+<p><div class="box">
+
+<p>New classes are created by using the "subclass" method. The "new" and
+"subclass" methods are inheritedby almost all classes. Every instance object
+pointer is also associated with an object pointer of a class. Unlike the
+"new" and "subclass" methods, there are no specific methods that remove an
+object that is no longer useful. Smalltalk objects are deleted when they are
+no longer reachable (garbage collected).</p>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>2.8 Behavior/State Grouping</h2>
+
+<hr>
+
+<p>Smalltalk uses the 'classical' object model.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>2.9 Communication Model</h2>
+
+<hr>
+
+<p>All communications within Smalltalk occur through messages between
+objects and most Smalltalk implementations support a form of concurrency.
+For example, Smalltalk-80 provides for multiple independent processes, and
+semaphores provide the common mechanism for synchronizing the independent
+processes.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>2.10 Events</h2>
+
+<hr>
+
+<p>No specific mechanisms for handling events are built into the
+Smalltalk language, but "event handling" logic is commonly implemented in
+Smalltalk applications through its normal messaging techniques.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>4 Polymorphism</h2>
+
+<hr>
+
+<p>Polymorphism is the way that the Smalltalk language allows methods of
+same name to have predictable and meaningful results in related instances,
+yet perform the operations differently to achieve similar results.</p>
+
+<p>Smalltalk supports polymorphism by allowing methods defined in classes to
+be overridden with methods of the same name, but different logic, in a
+subsequent subclass. In addition, methods of the same name can be defined in
+a total different subclass hierarchy.</p>
+
+<p>In the class hierarchy below, all of the lowest level classes are defined
+to accept the message <nobr>'moveForward' (mFabstract)</nobr>, but several
+different versions are implemented as indicated by (MFn) in the diagram.
+<nobr>The message</nobr> sent to the instances of 'Bus' or 'Auto' uses the
+method defined in the 'Motorized' class. <nobr>The same</nobr> method is
+inherited by 'Train' and 'Motorcycle', but both have overridden the
+inherited method by defining a method with different logic using the same
+message pattern. <nobr>All the</nobr> others instances in the diagram have
+the 'moveForward' message pattern in their interface, but are not in the
+'Motorized' inheritance chain. <nobr>All of</nobr> the <nobr>'moveForward'
+(mFabstract)</nobr> methods function as you intuitively expect.</p>
+
+<pre class="example">
+ Transport Mechanism (mFabstract)
+ /--------------- | -------------------\
+Animal Powered Human Powered Motorized
+ / (mF1) \ / \ / (mF5) \
+Buggy Wagon Land-based Water-based Public Private
+ / \ / (mF4) \ / \ / \
+ Bike Skates Row Boat Canoe Bus Train Auto Motorcycle
+ (mF2) (mF3) (mF6) (mF7)
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>5 Encapsulation</h2>
+
+<hr>
+
+<p>The approach used in Smalltalk is to encapsulate all objects, whether a
+complex as a sorted list or as simple as a string, into a single programming
+entity that includes data and logic. Further, other objects can not invoke
+the encapsulated data or logic. In order to interact, other objects must
+send messages to an object's interface that will cause the object to perform
+a function that will have a known effect. See also entry under
+<nobr><a href="#2-3">2.3 Messages</a></nobr>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>6 Identity, Equality, Copy</h2>
+
+<hr>
+
+<p><div class="box">
+
+<p>Smalltalk provides unique identity for all objects. Objects can be tested
+for equivalence (Are the objects being compared the same object?) and
+equality (every object may implement its own definition of equality).</p>
+
+<p>Copying of objects can be performed as a deep copy (object's structure
+and the objects pointed to by its variables are copied) or shallow copy
+(objects pointed to by variables, their variables are not copied, but are
+shared with the original object).</p>
+
+</div></p>
+
+<p>XLISP does not provide <nobr>build-in</nobr> functions or methods to
+compare or to copy objects.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>7 Types and Classes</h2>
+
+<hr>
+
+<p>Smalltalk does not have a separate notion of 'type' [message protocol
+shared by a group of objects] apart from 'class'.</p>
+
+<p>A class is a group of objects that represent the same type of entity and
+share the same methods. A class describes the implementation of a set of
+similar objects. Classes are themselves objects. All objects belong to some
+class and an object is an instance of the class of which it belongs.</p>
+
+<p><b>XLISP:</b> If an object is a member of a class can be tested by
+sending an <a href="../reference/keyword-isa.htm">:isa</a> message.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>8 Inheritance and Delegation</h2>
+
+<hr>
+
+<p>Smalltalk class relationships are defined in terms of inheritance. The
+properties of one class are be inherited from another class in a
+hierarchical structure beginning with the <nobr>upper-most</nobr>
+<nobr>class <a href="../reference/object.htm">object</a></nobr>. <nobr>In
+inheritance</nobr>, the inheriting class is called the 'subclass' and the
+class being inherited from is call the 'superclass'. <nobr>A subclass</nobr>
+inherits all of its superclass' variables and methods.</p>
+
+<p>Abstract classes are classes from which other classes are inherited
+(subclassed) only. Instances can be implemented any non-abstract class.</p>
+
+<p>Subclasses are specialization of their superclasses. A subclass may add
+variables, but it cannot delete those inherited from the superclass. A
+subclass may accept an inherited method or it may override the method by
+providing an new method with the same name (or message selector).</p>
+
+<p>Object instances are instances of a class. Smalltalk does not provide for
+delegation (defined as object instances being created from other object
+instances and not a class).</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/reference/abs.htm b/docsrc/xlisp/xlisp-doc/reference/abs.htm new file mode 100644 index 0000000..3069cb2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/abs.htm @@ -0,0 +1,78 @@ +<html><head><title>XLISP abs</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>abs</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlisp/xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>abs</b> <i>number</i>)</nobr></dt>
+<dd><i>number</i> - an integer or floating point expression<br>
+returns - the absolute value of the number</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'abs' function computes the absolute value of a number and returns
+the result. <nobr>A 'bad argument</nobr> type' error is signalled if the
+argument is not a numebr.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(abs 1) => 1
+(abs -99) => 99
+(abs -99.9) => 99.9
+(abs -32768) => 32768
+(abs "123") => <font color="#AA0000">error: bad argument type</font>
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/acos.htm b/docsrc/xlisp/xlisp-doc/reference/acos.htm new file mode 100644 index 0000000..8351556 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/acos.htm @@ -0,0 +1,93 @@ +<html><head><title>XLISP acos</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>acos</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp function (closure)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr></nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>acos</b> <i>flonum</i>)</nobr></dt>
+<dd><i>flonum</i> - an integer or floating point expression<br>
+returns - the <nobr>arc-cosine</nobr> of the number</dd>
+</dl>
+
+</div></p>
+
+<p><b>Note:</b> the 'acos' function is not implemented in Nyquist. Here
+is a Lisp implementation of 'acos', using the <a href="atan.htm">atan</a>
+function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">acos</font> (x)
+ (cond ((not (numberp x)) (error <font color="#880000">"bad argument type"</font> x))
+ ((= x 1) 0.0)
+ ((= x -1) pi)
+ ((< -1 x 1) (+ (atan (/ (- x) (sqrt (1+ (* x (- (float x))))))) (/ pi 2.0)))
+ (t (error <font color="#880000">"argument out of range"</font> x))))
+</pre>
+
+<h2>Description</h2>
+
+<p>The 'acos' function returns the <nobr>arc-cosine</nobr> of an integer or
+floating point expression. <nobr>The result</nobr> is a floating point
+number in radians. <nobr>If the</nobr> argument is less <nobr>than -1</nobr>
+or greater <nobr>than +1</nobr>, the <nobr>arc-cosine</nobr> is a complex
+number. Complex numbers are not available <nobr>in XLISP</nobr>. <nobr>In
+this</nobr> case the 'acos' function signals an 'argument out of range'
+error.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(acos 0.0) => 1.5708
+(acos 1.0) => 0.0
+(acos -1.0) => 3.14159
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/addition.htm b/docsrc/xlisp/xlisp-doc/reference/addition.htm new file mode 100644 index 0000000..13e925d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/addition.htm @@ -0,0 +1,87 @@ +<html><head><title>XLISP +</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>+</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(+ <i>expr1</i> ...)</nobr></dt>
+<dd><i>exprN</i> - integer or floating point number/expression<br>
+returns - the result of adding the expressions</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The '+' function adds a list of numbers together and returns the
+result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(+ 1) => 1
+(+ 1 2) => 3
+(+ 1 2 3) => 6
+(+ 1 2 3 4) => 10
+</pre>
+
+<pre class="example">
+> (print (+ 1 2 (* 3.5 (/ 3.9 1.45))))
+12.4138 <font color="#008844">; screen output of PRINT</font>
+12.4138 <font color="#008844">; return value</font>
+</pre>
+
+<p>See <a href="multiplication.htm"> * </a>,
+<a href="division.htm"> / </a>, <a href="print.htm">print</a>.
+XLISP first prints the value on the screen, the second number is the
+return value.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/address-of.htm b/docsrc/xlisp/xlisp-doc/reference/address-of.htm new file mode 100644 index 0000000..07190d2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/address-of.htm @@ -0,0 +1,99 @@ +<html><head><title>XLISP address-of</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>address-of</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>address-of</b> <i>expr</i>)</dt>
+<dd>expr - an expression<br>
+returns - the memory address of the expression as an integer</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'address-of' function returns the internal memory address of the
+XLISP node that corresponds to 'expr'. The value returned is an integer.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq var 0) => 0 <font color="#008844">; set up VAR with 0</font>
+(address-of var) => 123224
+(address-of 'var) => 182638
+(peek (address-of var)) => 83951616
+(peek (1+ (address-of var))) => 16777216
+(peek (+ 2 (address-of var))) => 0 <font color="#008844">; value of VAR</font>
+(setq var 14) => 14 <font color="#008844">; change the value to 14</font>
+(peek (+ 2 (address-of var))) => 14
+(setq var 99) => 99 <font color="#008844">; change the value to 99</font>
+(peek (+ 2 (address-of var))) => 99
+</pre>
+
+<p>See <a href="addition.htm"> + </a>,
+<a href="increment.htm">1+</a>, <a href="peek.htm">peek</a>,
+<a href="setq.htm">setq</a>.</p>
+
+<p><div class="box">
+
+<p><b>Nyquist:</b> The '<nobr>address-of</nobr>' function is internally
+disabled, but the code still exists. Look out for PEEK_AND_POKE in the
+Nyquist source code.</p>
+
+<p><b>Caution:</b> Be careful when modifying the internal state of XLISP.
+<nobr>If you</nobr> have modified it, it would be a good idea to exit XLISP
+and <nobr>re-enter</nobr> before doing any work you really want to
+retain.</p>
+
+</div></p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#system-functions">System Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/alloc.htm b/docsrc/xlisp/xlisp-doc/reference/alloc.htm new file mode 100644 index 0000000..22feb53 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/alloc.htm @@ -0,0 +1,98 @@ +<html><head><title>XLISP alloc</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>alloc</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xldmem.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>alloc</b> <i>size</i>)</nobr></dt>
+<dd><i>size</i> - the number of nodes to allocate as an integer<br>
+returns - the old number of nodes to allocate</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'alloc' function changes the number of memory nodes allocated per
+segment whenever memory is expanded. <nobr>The previous</nobr> number of
+nodes allocated per segment is the value returned as the result. <nobr>The
+power-up</nobr> default is 1000 nodes per segment. <nobr>Note that</nobr>
+'alloc' does not, itself, expand memory. You need to call the
+<a href="expand.htm">expand</a> function to do the expand operation.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+> (room)
+Nodes: 4000
+Free nodes: 1669
+Segments: 4
+Allocate: 1000 <font color="#008844">; default ALLOC value</font>
+Total: 52570
+Collections: 8
+NIL
+
+> (alloc 2000) <font color="#008844">; new ALLOC value</font>
+1000 <font color="#008844">; old ALLOC value</font>
+
+> (room)
+Nodes: 4000
+Free nodes: 1655
+Segments: 4
+Allocate: 2000 <font color="#008844">; new ALLOC value</font>
+Total: 52570
+Collections: 8
+NIL
+</pre>
+
+<p>See <a href="room.htm">room</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#system-functions">System Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/alphanumericp.htm b/docsrc/xlisp/xlisp-doc/reference/alphanumericp.htm new file mode 100644 index 0000000..9067193 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/alphanumericp.htm @@ -0,0 +1,84 @@ +<html><head><title>XLISP alphanumericp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>alphanumericp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>alphanumericp</b> <i>char</i>)</dt>
+<dd>char - a character expression<br>
+returns - <a href="t.htm"> T </a> if the character
+is alphabetic or a digit, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p> The 'alphanumericp' function checks if the 'char' expression is an
+alphabetic or a digit character. <nobr>If 'char'</nobr> is an alphabetic
+[either an upper or lower case] or a digit character,
+<a href="t.htm"> T </a> is returned, otherwise
+<a href="nil.htm">NIL</a> is returned. Note that XLISP is limited to
+<a href="../misc/ascii-table.htm">ASCII</a> characters, so there is no way
+to find out if an Unicode character with a
+<nobr><a href="char-code.htm">char-code</a></nobr> greater than
+<nobr>ASCII 127</nobr> is alphanumeric <nobr>or not</nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(alphanumericp #\A) => T
+(alphanumericp #\a) => T
+(alphanumericp #\1) => T
+(alphanumericp #\[) => NIL
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/and.htm b/docsrc/xlisp/xlisp-doc/reference/and.htm new file mode 100644 index 0000000..1a2c3d9 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/and.htm @@ -0,0 +1,118 @@ +<html><head><title>XLISP and</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>and</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>and</b> [<i>expr1</i> ... ])</nobr></dt>
+<dd><i>exprN</i> - an expression<br>
+returns - <a href="nil.htm">NIL</a> if any expression evaluates
+to <nobr><a href="nil.htm">NIL</a> ,</nobr> otherwise the value
+of the last expression<br>
+<b>Note:</b> evaluation of expressions stops after the first
+expression that evaluates to <a href="nil.htm">NIL</a></dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'and' special form evaluates a sequence of expressions and returns
+the effect of a logical AND on the expressions. <nobr>If, at</nobr> any
+point, an expression is <a href="nil.htm">NIL</a>, then
+<a href="nil.htm">NIL</a> is returned as the result of the 'and'
+function. <nobr>If all</nobr> of the expressions have a
+<nobr>non-<a href="nil.htm">NIL</a></nobr> value, the value of the last
+expression is returned as the result. Evaluation of the expressions will
+stop when an expression evaluates <nobr>to <a href="nil.htm">NIL</a></nobr>,
+none of the subsequent expressions will be evaluated. <nobr>If there</nobr>
+are no expressions, then 'and' returns <a href="t.htm"> T </a>
+as its result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(and t t t) => T</font>
+(and nil t) => NIL</font>
+(and t nil) => NIL</font>
+(and) => T</font>
+</pre>
+
+<p>Some more practical examples:</p>
+
+<pre class="example">
+> (and T "boo" "hiss" T "rah")
+"rah" <font color="#008844">; return value of AND</font>
+
+> (and (princ "hi") NIL (princ "ho"))
+hi <font color="#008844">; prints "hi"</font>
+NIL <font color="#008844">; return value of AND</font>
+</pre>
+
+See <a href="princ.htm">princ</a>.
+
+<pre class="example">
+> (setq a 5 b 6) <font color="#008844">; set up A and B</font>
+6 <font color="#008844">; return value of SETQ</font>
+
+> (if (and (numberp a) <font color="#008844">; if A is a number</font>
+ (numberp b) <font color="#008844">; and B is a number</font>
+ (< a b)) <font color="#008844">; and A < B</font>
+ (print "A is less than B") <font color="#008844">; then do this</font>
+ (print "error")) <font color="#008844">; else do this</font>
+"A is less than B" <font color="#008844">; screen output of PRINT</font>
+"A is less than B" <font color="#008844">; return value of IF</font>
+</pre>
+
+<p>See <a href="number-lessp.htm"> < </a>,
+<a href="if.htm"> if </a>, <a href="print.htm">print</a>,
+<a href="setq.htm">setq</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#control-constructs">Control Constructs</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">XLISP</a> >
+<a href="../manual/xlisp-man-index.htm">XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> -
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/append.htm b/docsrc/xlisp/xlisp-doc/reference/append.htm new file mode 100644 index 0000000..4d7b54a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/append.htm @@ -0,0 +1,90 @@ +<html><head><title>XLISP append</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+
+<h1>append</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>append</b> [<i>expr</i> ... ])</dt>
+<dd><i>expr</i> - a list or list expression<br>
+returns - the new list</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'append' function takes an arbitrary number of lists and splices them
+together into a single list. This single list is returned. <nobr>If
+an</nobr> empty list <a href="nil.htm">NIL</a> is appended, it has no
+effect, it does not appear in the final list. Remember that '(nil) is not an
+empty list. <nobr>If a</nobr> list is appended to an atom, it also has no
+effect and the atom will not appear in the final list.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(append) => NIL
+(append 'a 'b) => B
+(append '(a) '(b)) => (A B)
+(append 'a '(b)) => (B)
+(append '(a) 'b) => (A . B)
+(append '(a) nil) => (A)
+(append (list 'a 'b) (list 'c 'd)) => (A B C D)
+(append '(a (b)) '(c (d))) => (A (B) C (D))
+(append '(a) nil nil nil '(b)) => (A B)
+(append '(a) '(nil) '(b)) => (A NIL B)
+</pre>
+
+<p><b>Note:</b> If a list is appended to an atom, XLISP signals no error,
+the atom just disappears!</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#list-functions">List Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/apply.htm b/docsrc/xlisp/xlisp-doc/reference/apply.htm new file mode 100644 index 0000000..acc5f05 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/apply.htm @@ -0,0 +1,89 @@ +<html><head><title>XLISP apply</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>apply</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>apply</b> <i>function args</i>)</dt>
+<dd><i>function</i> - the function or symbol to be applied to 'args'<br>
+<i>args</i> - a list that contains the arguments to be passed to 'function'<br>
+returns - the result of applying the function to the arguments</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'apply' function causes 'function' to be evaluated with 'args' as the
+parameters, returning the result of 'function'. The 'args' argument must be
+a list.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+> (defun my-add (x y) <font color="#008844">; define MY-ADD function</font>
+ (+ x y))
+MY-ADD
+
+> (my-add 1 2) <font color="#008844">; ordinary function call</font>
+3 <font color="#008844">; returns 3</font>
+
+> (apply #'my-add '(2 4)) <font color="#008844">; symbol-function applied to argument-list</font>
+6 <font color="#008844">; returns 6</font>
+</pre>
+
+<p><b>Note:</b> When using 'apply' to cause the evaluation of a function,
+you can use the <nobr>sharp-quoted</nobr> name of the function like
+#'my-add in the example, or <nobr>(function my-add)</nobr>. <nobr>In
+XLISP</nobr> also <nobr>'my-add</nobr> and <nobr>(quote my-add)</nobr> work,
+but this is no good Lisp style.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#evaluation-functions">Evaluation Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/aref.htm b/docsrc/xlisp/xlisp-doc/reference/aref.htm new file mode 100644 index 0000000..68ad742 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/aref.htm @@ -0,0 +1,105 @@ +<html><head><title>XLISP aref</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>aref</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>aref</b> <i>array element</i>)</dt>
+<dd><i>array</i> - an array expression<br>
+<i>element</i> - an integer expression<br>
+returns - the value of the array element</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'aref' function returns the specified element out of a previously
+created array. Array elements may be any valid lisp data type, including
+lists or arrays. Arrays made by <a href="make-array.htm">make-array</a> and
+accessed by 'aref' are <nobr>base 0</nobr>. This means the first element is
+accessed by element <nobr>number '0'</nobr> and the last element is accessed
+by element <nobr>number 'n-1'</nobr> [where 'n' is the array size]. Array
+elements are initialized to <a href="nil.htm">NIL</a>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq my-array '#(0 1 2 3 4)) => #(0 1 2 3 4)
+(aref my-array 0) => 0
+(aref my-array 4) => 4
+(aref my-array 5) => <font color="#AA0000">error: array index out of bounds - 5</font>
+my-array => #(0 1 2 3 4)
+
+(setq new (make-array 4)) => #(NIL NIL NIL NIL)
+(setf (aref new 0) (make-array 4)) => #(NIL NIL NIL NIL)
+new => #(#(NIL NIL NIL NIL) NIL NIL NIL)
+(setf (aref (aref new 0) 1) 'a) => A
+new => #(#(NIL A NIL NIL) NIL NIL NIL)
+(setf (aref new 2) '(a b c)) => (A B C)
+new => #(#(NIL A NIL NIL) NIL (A B C) NIL)
+</pre>
+
+<p><b>Read macro:</b> There is a built-in read-macro for arrays,
+<nobr>'#(...)'</nobr> <nobr>[the hash</nobr> symbol with the array elements
+in parentheses]. This allows you to create arbitrary arrays with initial
+values without going through a <a href="make-array.htm">make-array</a>
+function. See the <a href="../manual/xlisp.htm#the-readtable">Readtable</a>
+section in the <nobr>XLISP 2.0</nobr> Manual.</p>
+
+<p><b>Note:</b> This function returns the value of an array element.
+However, there is no equivalent direct function to set the value of an array
+element to some value. <nobr>To set</nobr> an element value, you must use
+the <a href="setf.htm">setf</a> function.
+<nobr>The <a href="setf.htm">setf</a></nobr> function is a generalized
+function that allows you to set the value of arbitrary lisp entities.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#array-functions">Array Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/arrayp.htm b/docsrc/xlisp/xlisp-doc/reference/arrayp.htm new file mode 100644 index 0000000..139fc4d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/arrayp.htm @@ -0,0 +1,84 @@ +<html><head><title>XLISP arrayp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>arrayp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>arrayp</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - an arbitrary Lisp expression<br>
+returns - <a href="t.htm"> T </a> if the value is an
+array, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'arrayp' function checks if 'expr' evaluates to an array.
+<a href="t.htm"> T </a> is returned if 'expr' evaluates to an
+array, <a href="nil.htm">NIL</a> is returned otherwise.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(arrayp #(0 1 2)) => T <font color="#008844">; array</font>
+(setq a #(a b c)) => #(A B C))
+(arrayp a) => T <font color="#008844">; evaluates to an array</font>
+(arrayp '(a b c)) => NIL <font color="#008844">; list</font>
+(arrayp 1) => NIL <font color="#008844">; integer</font>
+(arrayp 1.2) => NIL <font color="#008844">; float</font>
+(arrayp 'a) => NIL <font color="#008844">; symbol</font>
+(arrayp #\a) => NIL <font color="#008844">; character</font>
+(arrayp NIL) => NIL <font color="#008844">; NIL</font>
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#predicate-functions">Predicate Functions</a></nobr></li>
+<li><nobr>Contents → <a href="../manual/contents.htm#array-functions">Array Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/asin.htm b/docsrc/xlisp/xlisp-doc/reference/asin.htm new file mode 100644 index 0000000..cd7d7fa --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/asin.htm @@ -0,0 +1,93 @@ +<html><head><title>XLISP asin</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>asin</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp function (closure)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr></nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>asin</b> <i>expr</i>)</nobr></dt>
+<dd><i>expr</i> - floating point number/expression<br>
+returns - the arcsine of the number</dd>
+</dl>
+
+</div></p>
+
+<p><b>Note:</b> The 'asin' function is not imlemented in Nyquist. Here is a
+Lisp implementation of 'asin', using the <a href="atan.htm">atan</a>
+function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">asin</font> (x)
+ (cond ((not (numberp x)) (error <font color="#880000">"bad argument type"</font> x))
+ ((= x 1) (/ pi 2.0))
+ ((= x -1) (/ pi -2.0))
+ ((< -1 x 1) (atan (/ x (sqrt (1+ (* x (- x)))))))
+ (t (error <font color="#880000">"argument out of range"</font> x))))
+</pre>
+
+<h2>Description</h2>
+
+<p>The 'asin' function returns the <nobr>arc sine</nobr> of a floating point
+expression. <nobr>The result</nobr> is a floating point number in radians.
+<nobr>If the</nobr> argument is less <nobr>than -1</nobr> or greater
+<nobr>than +1</nobr>, the <nobr>arc sine</nobr> is a complex number. Complex
+numbers are not available <nobr>in XLISP</nobr>. <nobr>In this</nobr> case
+the 'asin' function signals an 'argument out of range' error.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(asin 0.0) => 0.0
+(asin 1.0) => 1.5708
+(asin -1.0) => -1.5708
+(asin 0) => <font color="#AA0000">error: bad integer operation</font>
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/assoc.htm b/docsrc/xlisp/xlisp-doc/reference/assoc.htm new file mode 100644 index 0000000..ab1344a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/assoc.htm @@ -0,0 +1,121 @@ +<html><head><title>XLISP assoc</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>assoc</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>assoc</b> <i>expr a-list</i> [{:test | :test-not} <i>test</i>])</dt>
+<dd><i>expr</i> - the expression to find as an atom or list<br>
+<i>a-list</i> - the association list to search<br>
+<i>test</i> - optional test function (default is <a href="eql.htm">eql</a>)<br>
+returns - the alist entry or <a href="nil.htm">NIL</a></dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>An association list is a collection of list pairs of the form:</p>
+
+<pre class="example">
+((<font color="#0000CC">key1 item1</font>) (<font color="#0000CC">key2 item2</font>) ... (<font color="#0000CC">keyN itemN</font>))
+</pre>
+
+<p>The 'assoc' function searches through an association list
+'<nobr>a-list</nobr>' looking for the key
+<nobr>[a <a href="car.htm">car</a></nobr> in an association pair] that
+matches the search 'expr'. <nobr>If a</nobr> match is found, that
+association pair is returned as the result. <nobr>If no</nobr> match is
+found, <nobr><a href="nil.htm">NIL</a> is</nobr> returned. <nobr>You
+may</nobr> specify your own test with the ':test' and
+'<nobr>:test-not</nobr>' keywords followed by the 'test' you wish to
+perform.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq mylist '((a . my-a)
+ (b . his-b)
+ (c . her-c)
+ (d . end)))
+
+(assoc 'a mylist) => (A . MY-A)
+(assoc 'b mylist) => (B . HIS-B)
+(assoc 1 mylist) => NIL
+</pre>
+
+<pre class="example">
+(setq agelist '((1 (bill bob))
+ (2 (jane jill))
+ (3 (tim tom))
+ (5 (larry daryl daryl))))
+
+(assoc 1 agelist) => (1 (BILL BOB))
+(assoc 3 agelist :test #'>=) => (1 (BILL BOB))
+(assoc 3 agelist :test #'<) => (5 (LARRY DARYL DARYL))
+(assoc 3 agelist :test #'<=) => (3 (TIM TOM))
+(assoc 3 agelist :test-not #'>=) => (5 (LARRY DARYL DARYL))
+</pre>
+
+<p>Using a list as key, tested with <a href="equal.htm">equal</a>:</p>
+
+<pre class="example">
+> (assoc '(a b) '(((c d) e) ((a b) x)) :test #'equal)
+((A B) X)
+</pre>
+
+<p><b>Note:</b> The 'assoc' function can work with a list or string as the
+'expr'. However, the default <a href="eql.htm">eql</a> test does
+not work with lists or strings, only symbols and numbers.
+<nobr>To make</nobr> this work, you need to use the ':test' keyword along
+with <a href="equal.htm">equal</a> <nobr>for 'test'</nobr>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#list-functions">List Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/atan.htm b/docsrc/xlisp/xlisp-doc/reference/atan.htm new file mode 100644 index 0000000..27d67b5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/atan.htm @@ -0,0 +1,77 @@ +<html><head><title>XLISP atan</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>atan</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>atan</b> <i>expr</i> [<i>expr2</i>])</dt>
+<dd><i>expr</i> - an integer or floating point expression<br>
+<i>expr2</i> - an optional divisor [default value <nobr>is 1.0]</nobr><br>
+returns - the arctangent of the division of <i>expr</i> and <i>expr2</i></dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'atan' function returns the arc tangent of the division of 'expr' and
+'expr2'. <nobr>The result</nobr> is in radians.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(atan 0.0) => 0
+(atan 1.0) => 0.785398
+(atan -1.0) => -0.785398
+(atan 0) => 0
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/atom.htm b/docsrc/xlisp/xlisp-doc/reference/atom.htm new file mode 100644 index 0000000..fed7af5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/atom.htm @@ -0,0 +1,90 @@ +<html><head><title>XLISP atom</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>atom</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>atom</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - an arbitrary Lisp expression<br>
+returns - <a href="t.htm"> T </a> if the value is
+an atom, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'atom' predicate function tests if the 'expr' is an atom.
+<a href="t.htm"> T </a> is returned if 'expr' is an
+atom, <a href="nil.htm">NIL</a> is returned otherwise.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(atom 'a) => T <font color="#008844">; symbol</font>
+(atom #'atom) => T <font color="#008844">; subr - function</font>
+(atom "string") => T <font color="#008844">; string</font>
+(atom 4) => T <font color="#008844">; integer</font>
+(atom 4.5) => T <font color="#008844">; float</font>
+(atom object) => T <font color="#008844">; object</font>
+(atom #(1 2 3)) => T <font color="#008844">; array</font>
+(atom #'quote) => T <font color="#008844">; fsubr</font>
+(atom *standard-output*) => T <font color="#008844">; stream</font>
+(atom '()) => T <font color="#008844">; NIL is an atom</font>
+(atom (lambda (x) (print x))) => T <font color="#008844">; closure</font>
+(atom '(a b c)) => NIL <font color="#008844">; list</font>
+(setq a '(a b)) => (A B)
+(atom a) => NIL <font color="#008844">; value of A is not an atom</font>
+</pre>
+
+<p><b>Note:</b> <a href="nil.htm">NIL</a> or '() is used in many places as a
+list or atom expression. Both 'atom' and <a href="listp.htm">listp</a>, when
+applied to <a href="nil.htm">NIL</a>, return
+<a href="t.htm"> T </a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#predicate-functions">Predicate Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">XLISP</a> >
+<a href="../manual/xlisp-man-index.htm">XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> -
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/backquote.htm b/docsrc/xlisp/xlisp-doc/reference/backquote.htm new file mode 100644 index 0000000..8cb8b59 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/backquote.htm @@ -0,0 +1,170 @@ +<html><head><title>XLISP backquote</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>backquote</h1>
+
+<hr>
+
+<p>backquote:</p>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c, xlread.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>comma, comma-at:</p>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>reader expansion</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c, xlread.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>backquote</b> expr)</dt>
+<dd><i>expr</i> - an expression which is not evaluated except for 'comma' and 'comma-at' portions<br>
+<i>returns</i> - a copy of the template with 'comma' and 'comma-at' expressions expanded</dd>
+</dl>
+
+<dl>
+<dt>(<b>comma</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - an expression which is evaluated within a backquoted expression</dd>
+</dl>
+
+<dl>
+<dt>(<b>comma-at</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - an expression which is evaluated within a backquoted expression</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'backquote' special form returns 'expr' unevaluated, like
+<a href="quote.htm">quote</a>. The difference is that portions of the
+expression may be evaluated when they are preceeded by a 'comma' or
+'<nobr>comma-at</nobr>'.</p>
+
+<ul>
+
+<li><p><b>comma</b> will evaluate the portion of the expression the comma
+preceeds. <nobr>If the</nobr> portion is an atom or a list, it is placed as
+is within the expression.</p></li>
+
+<li><p><nobr><b>comma-at</b></nobr> will evaluate the portion of the
+expression that the <nobr>'comma-at</nobr>' preceeds. <nobr>The
+portion</nobr> needs to be a list. <nobr>The list</nobr> is spliced into the
+expression. <nobr>If the</nobr> portion is not a list,
+'<nobr>comma-at</nobr>' will splice in nothing.</p></li>
+
+</ul>
+
+<p>XLISP supports the following read macros:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button" align="right"><nobr><code>`<font color="#0000CC">expression</font></code></nobr></td>
+ <td><nobr> → </nobr></td>
+ <td class="button" align="right"><nobr><code>(backquote <font color="#0000CC">expression</font>)</code></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button" align="right"><nobr><code>,<font color="#0000CC">expression</font></code></nobr></td>
+ <td><nobr> → </nobr></td>
+ <td class="button" align="right"><nobr><code>(comma <font color="#0000CC">expression</font>)</code></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button" align="right"><nobr><code>,@<font color="#0000CC">expression</font></code></nobr></td>
+ <td><nobr> → </nobr></td>
+ <td class="button" align="right"><nobr><code>(comma-at <font color="#0000CC">expression</font>)</code></nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq box 'stuff-inside) => STUFF-INSIDE <font color="#008844">; BOX contains STUFF-INSIDE</font>
+(print box) => STUFF-INSIDE
+
+'(i have the box) ≡ (quote (i have the box)) => (I HAVE THE BOX)
+`(i have the box) ≡ (backquote (i have the box)) => (I HAVE THE BOX)
+`(i have the ,box) ≡ (backquote (i have the (comma box))) => (I HAVE THE STUFF-INSIDE)
+`(i have the ,@box) ≡ (backquote (I have the (comma-at box))) => (I HAVE THE) <font color="#008844">; STUFF-INSIDE is not a list</font>
+
+(setq automobile '(a van)) => (A VAN) <font color="#008844">; AUTOMOBILE is a VAN</font>
+(print automobile) => (A VAN)
+
+'(I have automobile) ≡ (quote (I have automobile)) => (I HAVE AUTOMOBILE)
+`(I have automobile) ≡ (backquote (I have automobile)) => (I HAVE AUTOMOBILE)
+`(I have ,automobile) ≡ (backquote (I have (comma automobile))) => (I HAVE (A VAN))
+`(I have ,@automobile) ≡ (backquote (I have (comma-at automobile))) => (I HAVE A VAN)
+</pre>
+
+<p>Common errors:</p>
+
+<pre class="example">
+`(,@(i am a list)) => <font color="#AA0000">error: bad function - I</font>
+`(,@'(i am a list)) => (I AM A LIST)
+</pre>
+
+<p><b>Note:</b> 'backquote', 'comma', and 'comma-at' are very useful in
+defining macros via <a href="defmacro.htm">defmacro</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#evaluation-functions">Evaluation Functions</a></nobr></li>
+<li><nobr>XLISP 2.0 Manual → <a href="../manual/xlisp.htm#the-readtable">Readtable</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/baktrace.htm b/docsrc/xlisp/xlisp-doc/reference/baktrace.htm new file mode 100644 index 0000000..1128206 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/baktrace.htm @@ -0,0 +1,117 @@ +<html><head><title>XLISP baktrace</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>baktrace</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xldbug.c, xlsys.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>baktrace</b> [<i>level</i>])</dt>
+<dd><i>level</i> - an optional integer expression<br>
+returns - <a href="nil.htm">NIL</a></dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p> The 'baktrace' function is used to examine the system execution stack
+from within the
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a>.</nobr> It
+shows the nested forms that got the system to the current state. The
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr> can be
+entered by a system error, or by the Nyquist/XLISP
+<a href="error.htm">error</a>, <a href="cerror.htm">cerror</a>, or
+<a href="break.htm">break</a> functions. <nobr>If the</nobr> 'levels'
+parameter is not specified, all the nested forms will be shown back to the
+main loop form that started the execution. <nobr>If 'level'</nobr> is
+specified the most recent 'level' nested forms will be shown.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun out (x)
+ (print x)
+ (mid 99))
+
+(defun mid (x)
+ (print x)
+ (in 999))
+
+(defun in (x)
+ (print x)
+ (break "in" x)) <font color="#008844">; break</font>
+
+> (out 9)
+9
+99
+999
+<font color="#AA0000">break: in - 999</font>
+<font color="#AA0000">if continued: return from BREAK</font>
+
+1> (baktrace) <font color="#008844">; the 1 before the > indicates a break loop</font>
+Function: #<Subr-BAKTRACE: #9af6688>
+Function: #<Subr-BREAK: #9af6778>
+Arguments:
+ "in"
+ 999
+Function: #<Closure-IN: #9b99574>
+Arguments:
+ 999
+Function: #<Closure-MID: #9b99670>
+Arguments:
+ 99
+Function: #<Closure-OUT: #9b99778>
+Arguments:
+ 9
+NIL
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#debugging-and-error-handling">Debugging and Error Handling</a></nobr></li>
+<li><nobr>XLISP 2.0 Manual → <a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/bigendianp.htm b/docsrc/xlisp/xlisp-doc/reference/bigendianp.htm new file mode 100644 index 0000000..38037cb --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/bigendianp.htm @@ -0,0 +1,69 @@ +<html><head><title>XLISP bigendianp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>bigendianp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>bigendiap</b>)</dt>
+<dd>returns - <a href="t.htm"> T </a> with a <nobr>big-endian</nobr>
+architecture, <nobr>otherwise <a href="nil.htm">NIL</a>.</nobr></dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The '<nobr>bigendianp</nobr>' function tests if Nyquist/XLISP runs on a
+bigendian machine, storing the <nobr>high-order</nobr> byte of an integer at
+the lowest byte address of the integer.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#predicate-functions">Predicate Functions</a></nobr></li>
+<li><nobr>Contents → <a href="../manual/contents.htm#file-io-functions">File I/O Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/block.htm b/docsrc/xlisp/xlisp-doc/reference/block.htm new file mode 100644 index 0000000..7d3e21d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/block.htm @@ -0,0 +1,94 @@ +<html><head><title>XLISP block</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>block</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><b>(block</b> <i>name</i> [<i>body</i> ... ])</dt>
+<dd><i>name</i> - an unevaluated symbol for the block name<br>
+<i>body</i> - an arbitrary number of Lisp expressions<br>
+returns - the value of the last expression</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'block' special form specifies a '<nobr>named block</nobr>'
+construct. <nobr>The last</nobr> expression in 'body' will be returned by
+the 'block' construct as its result unless a <a href="return.htm">return</a>
+or <a href="return-from.htm">return-from</a> is executed within 'block'.
+<nobr>The <a href="return.htm">return</a></nobr> exit will exit the nearest
+<nobr>[inner-most]</nobr> 'block'.
+<nobr>The <a href="return-from.htm">return-from</a></nobr> exit will exit
+the specified 'block'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun test ()
+ (block outer <font color="#008844">; outer BLOCK</font>
+ (print "outer")
+ (block inner <font color="#008844">; inner BLOCK</font>
+ (print "inner")
+ (return-from outer "all done")
+ (print "won't get here"))))
+
+> (test)
+"outer" <font color="#008844">; screen output of PRINT</font>
+"inner" <font color="#008844">; screen output of PRINT</font>
+"all done" <font color="#008844">; return value</font>
+</pre>
+
+<p>See <a href="defun.htm">defun</a>, <a href="print.htm">print</a>,
+<nobr><a href="return-from.htm">return-from</a></nobr>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#control-constructs">Control Constructs</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/both-case-p.htm b/docsrc/xlisp/xlisp-doc/reference/both-case-p.htm new file mode 100644 index 0000000..7d3a691 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/both-case-p.htm @@ -0,0 +1,84 @@ +<html><head><title>XLISP both-case-p</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>both-case-p</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>both-case-p</b> <i>char</i>)</dt>
+<dd><i>char</i> - a character expression<br>
+returns - <a href="t.htm"> T </a> if the character
+is alphabetic, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The '<nobr>both-case-p</nobr>' predicate function checks if the 'char'
+expression evaluates to an alphabetic character. <nobr>If 'char'</nobr>
+evaluates to an alphabetic [either an upper or lower case] character
+<a href="t.htm"> T </a> is returned, otherwise
+<a href="nil.htm">NIL</a> is returned. Note that XLISP is limited to <a
+href="../misc/ascii-table.htm">ASCII</a> characters, so there is no way to
+find out if an Unicode character is '<nobr>both-case-p</nobr>' if the
+<nobr><a href="char-code.htm">char-code</a></nobr> is greater <nobr>than
+127</nobr>.</nobr></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(both-case-p #\A) => T
+(both-case-p #\a) => T
+(both-case-p #\1) => NIL
+(both-case-p #\[) => NIL
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/boundp.htm b/docsrc/xlisp/xlisp-doc/reference/boundp.htm new file mode 100644 index 0000000..22bad23 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/boundp.htm @@ -0,0 +1,104 @@ +<html><head><title>XLISP boundp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>boundp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>boundp</b> <i>symbol</i>)</dt>
+<dd><i>symbol</i> - a symbol expression<br>
+returns - <a href="t.htm"> T </a> if a value is
+bound to the symbol, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'boundp' predicate function tests if 'symbol' evaluates to a symbol
+in <nobr>the <a href="global-obarray.htm">*obarray*</a></nobr> with a value
+bound to it. <nobr><a href="t.htm"> T </a> is</nobr> returned if
+'symbol' has a value, <a href="nil.htm">NIL</a> is returned otherwise. Note
+that 'boundp' does not test if local <a href="let.htm">let</a> variables, or
+class or instance variables exist.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq a 1) => 1 <font color="#008844">; create a variable A in the *OBARRAY*</font>
+(boundp 'a) => T <font color="#008844">; variable A has a value 1</font>
+
+(let ((b 'value))
+ (boundp b)) => NIL <font color="#008844">; BOUNDP does NOT test LET bindings</font>
+
+(defun foo (x) <font color="#008844">; create a function FOO in the *OBARRAY*</font>
+ (print x)) => FOO
+
+(boundp 'foo) => NIL <font color="#008844">; FOO is not a variable</font>
+
+(print myvar) => <font color="#AA0000">error: unbound variable - MYVAR</font>
+(boundp 'myvar) => NIL
+
+(setq myvar 'abc) <font color="#008844">; give MYVAR a value</font>
+(boundp 'myvar) => T
+</pre>
+
+<p>Note that 'symbol' is a symbol expression. This means that 'symbol' is
+evaluated and the return value is tested:</p>
+
+<pre class="example">
+(setq myvar 'qq) <font color="#008844">; MYVAR evaluates to QQ</font>
+(boundp myvar) => NIL <font color="#008844">; but QQ has no value yet</font>
+
+(setq qq 'new-value) <font color="#008844">; give QQ a value</font>
+(boundp myvar) => T
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#predicate-functions">Predicate Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/break.htm b/docsrc/xlisp/xlisp-doc/reference/break.htm new file mode 100644 index 0000000..a8a6c58 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/break.htm @@ -0,0 +1,107 @@ +<html><head><title>XLISP break</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>break</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c, xldbug.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>break</b> [<i>err-msg</i> [<i>arg</i>]])</dt>
+<dd><i>err-msg</i> - a string expression for the error message<br>
+<i>arg</i> - an optional argument expression<br>
+returns - <a href="nil.htm">NIL</a> when continued from the
+break loop</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'break' function allows the entry into the
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr> with a
+continuable error. The continuable error generated by 'break' does not
+require any corrective action. The form of the message generated is:</p>
+
+<pre class="example">
+break: <font color="#0000CC">err-msg</font> - <font color="#0000CC">arg</font>
+if continued: return from BREAK
+</pre>
+
+<p> The default for 'err-msg' is:</p>
+
+<pre class="example">
+**BREAK**
+</pre>
+
+<p>From within the
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr>, if a
+<a href="continue.htm">continue</a> form is evaluated then
+<a href="nil.htm">NIL</a> is returned from 'break'. <nobr>If desired</nobr>,
+the <a href="clean-up.htm">clean-up</a> or
+<a href="top-level.htm">top-level</a> functions may be evaluated to abort
+the <nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+> (break)
+break: **BREAK**
+if continued: return from BREAK
+
+> (break "out")
+break: out
+if continued: return from BREAK
+
+> (break "it" "up")
+break: it - "up"
+if continued: return from BREAK
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#debugging-and-error-handling">Debugging and Error Handling</a></nobr></li>
+<li><nobr>XLISP 2.0 Manual → <a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/caaaar.htm b/docsrc/xlisp/xlisp-doc/reference/caaaar.htm new file mode 100644 index 0000000..69ccda4 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/caaaar.htm @@ -0,0 +1,134 @@ +<html><head><title>XLISP caaaar ... cadddr</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>caaaar ... cadddr</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>caaaar</b> <i>expr</i>)<br>
+(<b>caaadr</b> <i>expr</i>)<br>
+(<b>caadar</b> <i>expr</i>)<br>
+(<b>caaddr</b> <i>expr</i>)<br>
+(<b>cadaar</b> <i>expr</i>)<br>
+(<b>cadadr</b> <i>expr</i>)<br>
+(<b>caddar</b> <i>expr</i>)<br>
+(<b>cadddr</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - a list or list expression<br>
+returns - the result of the last <a href="car.htm">car</a>
+function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p> The 'caaaar' ... 'cadddr' functions go through the list expression and
+perform a sequence of <a href="car.htm">car</a> or <a href="cdr.htm">cdr</a>
+operations. <nobr>The sequence</nobr> of operations is performed from right
+to left. <nobr>So 'caaddr'</nobr> does a <a href="cdr.htm">cdr</a> on the
+expression, followed by a <a href="cdr.htm">cdr</a>, followed by a
+<a href="car.htm">car</a>, followed by
+<nobr>another <a href="car.htm">car</a></nobr>. <nobr>If at</nobr> any point
+the list is <a href="nil.htm">NIL</a>, then <a href="nil.htm">NIL</a> is
+returned. <nobr>If at</nobr> any point a <a href="car.htm">car</a> operation
+is performed on an atom <nobr>[as opposed</nobr> to <nobr>a list]</nobr> an
+error is signalled:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument</font>
+</pre>
+
+<p>The 'cadddr' function returns the same result as the
+<a href="fourth.htm">fourth</a> function.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq mylist '((((111A 111B) (112A 112B) (113A 113B)) <font color="#008844">; 1st set</font>
+ ((121A 121B) (122A 122B) (123A 123B))
+ ((131A 131B) (132A 132B) (133A 133B))
+ ((141A 141B) (142A 142B) (143A 143B)))
+ (((211A 211B) (212A 212B) (213A 213B)) <font color="#008844">; 2nd set</font>
+ ((221A 221B) (222A 222B) (223A 223B))
+ ((231A 231B) (232A 232B) (233A 233B))
+ ((241A 241B) (242A 242B) (243A 243B)))
+ (((311A 311B) (312A 312B) (313A 313B)) <font color="#008844">; 3rd set</font>
+ ((321A 321B) (322A 322B) (323A 323B))
+ ((331A 331B) (332A 332B) (333A 333B))
+ ((341A 341B) (342A 342B) (343A 343B)))
+ (((411A 411B) (412A 412B) (413A 413B)) <font color="#008844">; 4th set</font>
+ ((421A 421B) (422A 422B) (423A 423B))
+ ((431A 431B) (432A 432B) (433A 433B))
+ ((441A 441B) (442A 442B) (443A 443B)))
+ (((511A 511B) (512A 512B) (513A 513B)) <font color="#008844">; 5th set</font>
+ ((521A 521B) (522A 522B) (523A 523B))
+ ((531A 531B) (532A 532B) (533A 533B))
+ ((541A 541B) (542A 542B) (543A 543B)))))
+
+(caaaar mylist) => 111A
+(caaadr mylist) => (211A 211B)
+(caadar mylist) => (121A 121B)
+(caaddr mylist) => ((311A 311B) (312A 312B) (313A 313B))
+(cadaar mylist) => (112A 112B)
+(cadadr mylist) => ((221A 221B) (222A 222B) (223A 223B))
+(caddar mylist) => ((131A 131B) (132A 132B) (133A 133B))
+(cadddr mylist) => (((411A 411B) (412A 412B) (413A 413B))
+ ((421A 421B) (422A 422B) (423A 423B))
+ ((431A 431B) (432A 432B) (433A 433B))
+ ((441A 441B) (442A 442B) (443A 443B)))
+</pre>
+
+<p><b>Note:</b> The '<nobr>c...r</nobr>' functions are part of the
+historical Lisp functions. You may find it easier to work with the modern
+lisp functions like <a href="nth.htm">nth</a> and
+<a href="nthcdr.htm">nthcdr</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#list-functions">List Functions</a></nobr></li>
+<li><nobr>Tutorials → Lisp Hints → <a href="../tutorials/lisp-hints.htm#list-accessors">List Accessors</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/caaar.htm b/docsrc/xlisp/xlisp-doc/reference/caaar.htm new file mode 100644 index 0000000..a4b210e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/caaar.htm @@ -0,0 +1,106 @@ +<html><head><title>XLISP caaar ... caddr</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>caaar ... caddr</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>caaar</b> <i>expr</i>)<br>
+(<b>caadr</b> <i>expr</i>)<br>
+(<b>cadar</b> <i>expr</i>)<br>
+(<b>caddr</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - a list expression<br>
+returns - the result of the last <a href="car.htm">car</a> function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p> The 'caaar', 'caadr', 'cadar' and 'caddr' functions go through the list
+expression and perform a sequence of <nobr><a href="car.htm">car</a> or
+<a href="cdr.htm">cdr</a></nobr> operations. <nobr>The sequence</nobr> of
+operations is performed from right to left. <nobr>So 'caddr'</nobr> does a
+<a href="cdr.htm">cdr</a> on the expression, followed by
+a <a href="cdr.htm">cdr</a>, followed by
+<nobr>a <a href="car.htm">car</a></nobr>. <nobr>If at</nobr> any point the
+list is <a href="nil.htm">NIL</a>, then <a href="nil.htm">NIL</a> is
+returned. <nobr>If at</nobr> any point a <a href="car.htm">car</a> operation
+is performed on an atom <nobr>[as opposed</nobr> to <nobr>a list]</nobr> an
+error is signalled:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument</font>
+</pre>
+
+<p>The 'caddr' function returns the same result as the
+<a href="third.htm">third</a> function.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq mylist '(((11A 11B) (12A 12B) (13A 13B))
+ ((21A 21B) (22A 22B) (23A 23B))
+ ((31A 31B) (32A 32B) (33A 33B))
+ ((41A 41B) (42A 42B) (43A 43B))))
+
+(caaar mylist) => 11A
+(caadr mylist) => (21A 21B)
+(cadar mylist) => (12A 12B)
+(caddr mylist) => ((31A 31B) (32A 32B) (33A 33B))
+</pre>
+
+<p><b>Note:</b> The '<nobr>c...r</nobr>' functions are part of the
+historical Lisp functions. You may find it easier to work with the modern
+lisp functions like <a href="nth.htm">nth</a> and
+<a href="nthcdr.htm">nthcdr</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#list-functions">List Functions</a></nobr></li>
+<li><nobr>Tutorials → Lisp Hints → <a href="../tutorials/lisp-hints.htm#list-accessors">List Accessors</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/caar.htm b/docsrc/xlisp/xlisp-doc/reference/caar.htm new file mode 100644 index 0000000..03cee4a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/caar.htm @@ -0,0 +1,101 @@ +<html><head><title>XLISP caar, cadr</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>caar, cadr</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>caar</b> <i>expr</i>)<br>
+(<b>cadr</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - a list expression<br>
+returns - the result of the last <a href="car.htm">car</a> function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'caar' and 'cadr' functions go through the list expression and
+perform a sequence of <a href="car.htm">car</a> or
+<a href="cdr.htm">cdr</a> operations. The sequence of operations is
+performed from right to left. <nobr>So 'cadr'</nobr> does a
+<a href="cdr.htm">cdr</a> on the expression, followed by a
+<a href="car.htm">car</a>. <nobr>If at</nobr> any point the list is
+<a href="nil.htm">NIL</a>, then
+<a href="nil.htm">NIL</a> is returned. <nobr>If at</nobr> any point a
+<a href="car.htm">car</a> operation is performed on an atom
+<nobr>[as opposed</nobr> to <nobr>a list]</nobr> an error is signalled:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument</font>
+</pre>
+
+<p>The 'cadr' function returns the same result as the
+<a href="second.htm">second</a> function.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq mylist '((1A 1B) (2A 2B) (3A 3B)))
+
+(caar mylist) => 1A
+(cadr mylist) => (2A 2B)
+
+(caar 'a) => <font color="#AA0000">error: bad argument</font>
+(caar nil) => NIL
+</pre>
+
+<p><b>Note:</b> The '<nobr>c...r</nobr>' functions are part of the
+historical Lisp functions. You may find it easier to work with the modern
+lisp functions like <a href="nth.htm">nth</a> and
+<a href="nthcdr.htm">nthcdr</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#list-functions">List Functions</a></nobr></li>
+<li><nobr>Tutorials → Lisp Hints → <a href="../tutorials/lisp-hints.htm#list-accessors">List Accessors</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/car.htm b/docsrc/xlisp/xlisp-doc/reference/car.htm new file mode 100644 index 0000000..035d240 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/car.htm @@ -0,0 +1,85 @@ +<html><head><title>XLISP car</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>car</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>car</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - a list or list expression<br>
+returns - the first element of the list</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'car' function returns the <a href="first.htm">first</a> element of
+the expression. <nobr>If the</nobr> <a href="first.htm">first</a> expression
+is itself a list, then the sublist is returned. <nobr>If the</nobr> list is
+<nobr><a href="nil.htm">NIL</a> ,</nobr> <a href="nil.htm">NIL</a> is
+returned.</p>
+
+<p>The 'car' function returns the same result as the
+<a href="first.htm">first</a> function.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(car '(a b c)) => A
+(car '((a b) c d)) => (A B)
+(car NIL) => NIL
+(car 'a) => <font color="#AA0000">error: bad argument type</font>
+(setq bob '(1 2 3)) => (1 2 3)
+(car bob) => 1
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#list-functions">List Functions</a></nobr></li>
+<li><nobr>Tutorials → Lisp Hints → <a href="../tutorials/lisp-hints.htm#list-accessors">List Accessors</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/case.htm b/docsrc/xlisp/xlisp-doc/reference/case.htm new file mode 100644 index 0000000..8cac054 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/case.htm @@ -0,0 +1,171 @@ +<html><head><title>XLISP case</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>case</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>case</b> <i>expr</i> [(<i>value action</i>) ... ])</dt>
+<dd><i>expr</i> - an expression that can be compared via <a href="eql.htm">eql</a><br>
+<i>value</i> - an unevaluated expression or list of unevaluated expressions<br>
+<i>action</i> - one or more expressions<br>
+returns - the value of the last expression of the matching case</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'case' special form first evaluates 'expr', the return value of this
+evaluation is then compared against all the 'value' entries:</p>
+
+<pre class="example">
+(case <font color="#0000CC">expr</font>
+ (<font color="#0000CC">value-</font><font color="#AA0000">1</font> <font color="#0000CC">action-</font><font color="#AA0000">1</font>)
+ (<font color="#0000CC">value-</font><font color="#AA0000">2</font> <font color="#0000CC">action-</font><font color="#AA0000">2</font>)
+ <font color="#008844">...</font>
+ (<font color="#0000CC">value-</font><font color="#AA0000">n</font> <font color="#0000CC">action-</font><font color="#AA0000">n</font>))
+</pre>
+
+<p>If 'value' is a single atom, the atom is compared against 'expr':</p>
+
+<pre class="example">
+> (case 'a
+ ('a "a")
+ ('b "b"))
+"a"
+</pre>
+
+<p>If 'value' is a list, each of the elements of the list are compared
+against 'expr':</p>
+
+<pre class="example">
+> (case 'a
+ ((1 2 3 4) "number")
+ ((a b c d) "alpha"))
+"alpha"
+</pre>
+
+<p>The 'action' associated with the first 'value' that matches 'expr' is
+evaluated and returned as the result of the 'case' special form.</p>
+
+<p>If no 'value' matches, <a href="nil.htm">NIL</a> is returned:</p>
+
+<pre class="example">
+> (case 'c
+ ('a "a")
+ ('b "b"))
+NIL
+</pre>
+
+<p>If the last 'value' is the symbol <a href="t.htm"> T </a> and
+no other 'value' has matched 'expr', then 'case' will evaluate the 'action'
+associated <nobr>with <a href="t.htm"> T </a></nobr>:</p>
+
+<pre class="example">
+> (case 3
+ (1 "one")
+ (2 "two")
+ (t "no match"))
+"no match"
+</pre>
+
+<p>If there are multiple <a href="t.htm"> T </a> entries, the
+first is considered to be the end of the 'case':</p>
+
+<pre class="example">
+> (case 9
+ (1 "one")
+ (t "first t")
+ (t "second t"))
+"first t"
+</pre>
+
+<p><b>Note:</b> The 'case' special form does not work with a list or string
+as the 'expr' because 'case' uses <a href="eql.htm">eql</a> which cannot
+compare lists or strings:</p>
+
+<pre class="example">
+> (case "a" <font color="#AA0000">; doesn't work!</font>
+ ("a" 'a)
+ ("b" 'b))
+NIL
+</pre>
+
+<p>The <a href="cond.htm">cond</a> special form can be used to test Lisp
+expressions that cannot be handled by 'case'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(case) => NIL
+(case 'a) => NIL
+
+(defun c-type (expr)
+ (case (type-of expr)
+ (flonum "float")
+ (fixnum "integer")
+ (string "string")
+ (cons "non-empty list")
+ (nil "empty list")
+ (t "other")))
+
+(c-type 1.2) => "float"
+(c-type 3) => "integer"
+(c-type "ab") => "string"
+(c-type '(a b)) => "non-empty list"
+(c-type '()) => "empty list"
+(c-type 'a) => "other"
+</pre>
+
+<p>See <a href="defun.htm">defun</a>,
+<nobr><a href="type-of.htm">type-of</a></nobr>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#control-constructs">Control Constructs</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/catch.htm b/docsrc/xlisp/xlisp-doc/reference/catch.htm new file mode 100644 index 0000000..28b682a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/catch.htm @@ -0,0 +1,197 @@ +<html><head><title>XLISP catch, throw</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>catch, throw</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c, xljump.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>catch</b> <i>tag-symbol</i> [<i>expr</i> ... ])</dt>
+<dd><i>tag-symbol</i> - an expression that evaluates to a symbol<br>
+<i>expr</i> - an optional series of expressions to be evaluated<br>
+returns - the value of the last expression the
+<a href="throw.htm">throw</a> expression</dd>
+</dl>
+
+<dl>
+<dt>(<b>throw</b> <i>tag-symbol</i> [<i>expr</i>])</dt>
+<dd><i>tag-symbol</i> - an expression that evaluates to a symbol<br>
+<i>expr</i> - an optional expression to be returned<br>
+returns - never returns</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'catch' and 'throw' special forms allow for non-local exits and traps
+without going through the intermediate evaluations and function returns:</p>
+
+<pre class="example">
+(catch <font color="#0000CC">tag-symbol</font>
+ [<font color="#0000CC">expr</font> <font color="#008844">...</font>]
+ (throw <font color="#0000CC">tag-symbol</font> [<font color="#0000CC">expr</font>]))
+</pre>
+
+<p>If there is a 'catch' for a '<nobr>tag-symbol</nobr>' that has no 'throw'
+performed to it, 'catch' returns the value returned from 'expr':</p>
+
+<pre class="example">
+> (catch 'mytag
+ (+ 1 (+ 2 3)))
+6
+</pre>
+
+<p>If there is no 'expr', <nobr><a href="nil.htm">NIL</a> is</nobr>
+returned:</p>
+
+<pre class="example">
+> (catch 'mytag)
+NIL
+</pre>
+
+<p>The 'expr' in 'throw' specifies what value is to be returned by the
+corresponding 'catch':</p>
+
+<pre class="example">
+> (catch 'mytag
+ (+ 1 (throw 'mytag 55)))
+55
+</pre>
+
+<p>If there is no 'expr' in 'throw', <a href="nil.htm">NIL</a> is returned
+to the corresponding 'catch':</p>
+
+<pre class="example">
+> (catch 'mytag
+ (throw 'mytag))
+NIL
+</pre>
+
+<p>If more than one 'catch' is set up for the same
+'<nobr>tag-symbol</nobr>', the most recently evaluated
+'<nobr>tag-symbol</nobr>' will be the one that does the actual catching:</p>
+
+<pre class="example">
+> (catch 'mytag
+ (catch 'mytag
+ (throw 'mytag))
+ (print 'hello))
+HELLO
+</pre>
+
+<p>If a 'throw' is evaluated with no corresponding 'catch', an error is
+signalled:</p>
+
+<pre class="example">
+> (catch 'mytag
+ (throw 'foo))
+<font color="#AA0000">error: no target for THROW</font>
+</pre>
+
+<p></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun in (x)
+ (if (numberp x) <font color="#008844">; if X is a number</font>
+ (+ x x) <font color="#008844">; then double X</font>
+ (throw 'math 42))) <font color="#008844">; else throw 42</font>
+
+(defun out (x)
+ (princ "<")
+ (princ (* (in x) 2)) <font color="#008844">; double via multiply</font>
+ (princ ">")
+ "there")
+
+(defun main (x)
+ (catch 'math (out x))) <font color="#008844">; catch the throw from IN</font>
+
+> (in 5)
+10 <font color="#008844">; return value</font>
+
+> (out 5)
+<20> <font color="#008844">; screen output of PRINC</font>
+"there" <font color="#008844">; return value</font>
+
+> (main 5)
+<20> <font color="#008844">; screen output of PRINC</font>
+"there" <font color="#008844">; return value</font>
+
+> (main 'a)
+< <font color="#008844">; screen output of PRINC</font>
+42 <font color="#008844">; return value</font>
+</pre>
+
+<p>See <nobr><a href="addition.htm"> + </a></nobr>,
+<nobr><a href="multiplication.htm"> * </a></nobr>,
+<a href="defun.htm">defun</a>,
+<nobr><a href="if.htm"> if </a></nobr>,
+<a href="numberp.htm">numberp</a>,
+<a href="princ.htm">princ</a>.</p>
+
+<p><div class="box">
+
+<p><b>Note:</b> 'catch' and 'throw' accept not only symbols as
+'<nobr>tag-symbol</nobr>', but if a '<nobr>tag-symbol</nobr>' cannot be
+compared via <a href="eql.htm">eql</a>, an error is signalled:</p>
+
+<pre class="example">
+> (catch "mytag"
+ (throw "mytag"))
+<font color="#AA0000">error: no target for THROW</font>
+</pre>
+
+<p>This was reproduced with <nobr>Nyquist 3.03</nobr> in <nobr>December
+2010</nobr>.</p>
+
+</div></p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#control-constructs">Control Constructs</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/cddddr.htm b/docsrc/xlisp/xlisp-doc/reference/cddddr.htm new file mode 100644 index 0000000..68b688a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/cddddr.htm @@ -0,0 +1,135 @@ +<html><head><title>XLISP cdaaar ... cddddr</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cdaaar ... cddddr</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>cdaaar</b> <i>expr</i>)<br>
+(<b>cdaadr</b> <i>expr</i>)<br>
+(<b>cdadar</b> <i>expr</i>)<br>
+(<b>cdaddr</b> <i>expr</i>)<br>
+(<b>cddaar</b> <i>expr</i>)<br>
+(<b>cddadr</b> <i>expr</i>)<br>
+(<b>cdddar</b> <i>expr</i>)<br>
+(<b>cddddr</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - a list or list expression<br>
+returns - the result of the last <a href="cdr.htm">cdr</a>
+function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p> The 'cdaaar' ... 'cddddr' functions go through the list expression and
+perform a sequence of <a href="car.htm">car</a> or
+<a href="cdr.htm">cdr</a> operations. <nobr>The sequence</nobr> of
+operations is performed from right to left. <nobr>So 'cddaar'</nobr> does a
+<a href="car.htm">car</a> on the expression, followed by
+<nobr>a <a href="car.htm">car</a></nobr>, followed by
+<nobr>a <a href="cdr.htm">cdr</a></nobr>, followed by <nobr>another
+<a href="cdr.htm">cdr</a></nobr>. <nobr>If at</nobr> any point the list
+<nobr>is <a href="nil.htm">NIL</a></nobr>, then
+<a href="nil.htm">NIL</a> is returned. <nobr>If at</nobr> anypoint a
+<a href="car.htm">car</a> operation is performed on an atom [as
+opposed to a list] an error is signalled:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument</font>
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq mylist '((((111A 111B) (112A 112B) (113A 113B)) <font color="#008844">; 1st set</font>
+ ((121A 121B) (122A 122B) (123A 123B))
+ ((131A 131B) (132A 132B) (133A 133B))
+ ((141A 141B) (142A 142B) (143A 143B)))
+ (((211A 211B) (212A 212B) (213A 213B)) <font color="#008844">; 2nd set</font>
+ ((221A 221B) (222A 222B) (223A 223B))
+ ((231A 231B) (232A 232B) (233A 233B))
+ ((241A 241B) (242A 242B) (243A 243B)))
+ (((311A 311B) (312A 312B) (313A 313B)) <font color="#008844">; 3rd set</font>
+ ((321A 321B) (322A 322B) (323A 323B))
+ ((331A 331B) (332A 332B) (333A 333B))
+ ((341A 341B) (342A 342B) (343A 343B)))
+ (((411A 411B) (412A 412B) (413A 413B)) <font color="#008844">; 4th set</font>
+ ((421A 421B) (422A 422B) (423A 423B))
+ ((431A 431B) (432A 432B) (433A 433B))
+ ((441A 441B) (442A 442B) (443A 443B)))
+ (((511A 511B) (512A 512B) (513A 513B)) <font color="#008844">; 5th set</font>
+ ((521A 521B) (522A 522B) (523A 523B))
+ ((531A 531B) (532A 532B) (533A 533B))
+ ((541A 541B) (542A 542B) (543A 543B)))))
+
+(cdaaar mylist) => (111B)
+(cdaadr mylist) => ((212A 212B) (213A 213B))
+(cdadar mylist) => ((122A 122B) (123A 123B))
+(cdaddr mylist) => (((321A 321B) (322A 322B) (323A 323B))
+ ((331A 331B) (332A 332B) (333A 333B))
+ ((341A 341B) (342A 342B) (343A 343B)))
+(cddaar mylist) => ((113A 113B))
+(cddadr mylist) (((231A 231B) (232A 232B) (233A 233B))
+ ((241A 241B) (242A 242B) (243A 243B)))
+(cdddar mylist) => (((141A 141B) (142A 142B) (143A 143B)))
+(cddddr mylist) => ((((511A 511B) (512A 512B) (513A 513B))
+ ((521A 521B) (522A 522B) (523A 523B))
+ ((531A 531B) (532A 532B) (533A 533B))
+ ((541A 541B) (542A 542B) (543A 543B))))
+</pre>
+
+<p><b>Note:</b> The '<nobr>c...r</nobr>' functions are part of the
+historical Lisp functions. You may find it easier to work with the modern
+lisp functions like <a href="nth.htm">nth</a> and
+<a href="nthcdr.htm">nthcdr</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#list-functions">List Functions</a></nobr></li>
+<li><nobr>Tutorials → Lisp Hints → <a href="../tutorials/lisp-hints.htm#list-accessors">List Accessors</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/cdddr.htm b/docsrc/xlisp/xlisp-doc/reference/cdddr.htm new file mode 100644 index 0000000..ce35fa5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/cdddr.htm @@ -0,0 +1,104 @@ +<html><head><title>XLISP cdaar ... cdddr</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cdaar ... cdddr</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>cdaar</b> <i>expr</i>)<br>
+(<b>cdadr</b> <i>expr</i>)<br>
+(<b>cddar</b> <i>expr</i>)<br>
+(<b>cdddr</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - a list or list expression<br>
+returns - the result of the last <a href="cdr.htm">cdr</a>
+function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'cdaar', 'cdadr', 'cddar' and 'cdddr' functions go through the list
+expression and perform a sequence of <nobr><a href="car.htm">car</a> or
+<a href="cdr.htm">cdr</a></nobr> operations. <nobr>The sequence</nobr> of
+operations is performed from right to left. So 'cddar' does a
+<a href="car.htm">car</a> on the expression, followed by a
+<nobr> a<a href="cdr.htm">cdr</a></nobr>, followed by <nobr>another
+<a href="cdr.htm">cdr</a></nobr>. <nobr>If at</nobr> any point the list
+<nobr>is <a href="nil.htm">NIL</a></nobr>, then
+<a href="nil.htm">NIL</a> is returned. <nobr>If at</nobr> any point a
+<a href="car.htm">car</a> operation is performed on an atom [as
+opposed to a list] an error is signalled:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument</font>
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq mylist '(((11A 11B) (12A 12B) (13A 13B))
+ ((21A 21B) (22A 22B) (23A 23B))
+ ((31A 31B) (32A 32B) (33A 33B))
+ ((41A 41B) (42A 42B) (43A 43B))))
+
+(cdaar mylist) => (11B)
+(cdadr mylist) => ((22A 22B) (23A 23B))
+(cddar mylist) => ((13A 13B))
+(cdddr mylist) => (((41A 41B) (42A 42B) (43A 43B)))
+</pre>
+
+<p><b>Note:</b> The '<nobr>c...r</nobr>' functions are part of the
+historical Lisp functions. You may find it easier to work with the modern
+lisp functions like <a href="nth.htm">nth</a> and
+<a href="nthcdr.htm">nthcdr</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#list-functions">List Functions</a></nobr></li>
+<li><nobr>Tutorials → Lisp Hints → <a href="../tutorials/lisp-hints.htm#list-accessors">List Accessors</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/cddr.htm b/docsrc/xlisp/xlisp-doc/reference/cddr.htm new file mode 100644 index 0000000..a69d2f3 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/cddr.htm @@ -0,0 +1,101 @@ +<html><head><title>XLISP cdar, cddr</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cdar, cddr</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>cdar</b> <i>expr</i>)<br>
+(<b>cddr</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - a list or list expression<br>
+returns - the result of the last <a href="cdr.htm">cdr</a>
+function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'cdar' and 'cddr' functions go through the list expression and perform a
+sequence of <a href="car.htm">car</a> or
+<a href="cdr.htm">cdr</a> operations. <nobr>The sequence</nobr> of
+operations is performed from right to left. So 'cdar' does a
+<a href="car.htm">car</a> on the expression, followed by <nobr>a
+<a href="cdr.htm">cdr</a></nobr>. <nobr>If at</nobr> any point the list is
+<a href="nil.htm">NIL</a>, then <a href="nil.htm">NIL</a> is returned.
+<nobr>If at</nobr> any point a <a href="car.htm">car</a> operation is
+performed on an atom [as opposed to a list] an error is signalled:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument</font>
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq mylist '((1A 1B) (2A 2B) (3A 3B)))
+
+(caar mylist) => 1A
+(cadr mylist) => (2A 2B)
+
+(cdar mylist) => (1B)
+(cddr mylist) => ((3A 3B))
+
+(cdar 'a) => <font color="#AA0000">error: bad argument</font>
+(cdar nil) => NIL
+</pre>
+
+<p><b>Note:</b> The '<nobr>c...r</nobr>' functions are part of the
+historical Lisp functions. You may find it easier to work with the modern
+lisp functions like <a href="nth.htm">nth</a> and
+<a href="nthcdr.htm">nthcdr</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#list-functions">List Functions</a></nobr></li>
+<li><nobr>Tutorials → Lisp Hints → <a href="../tutorials/lisp-hints.htm#list-accessors">List Accessors</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/cdr.htm b/docsrc/xlisp/xlisp-doc/reference/cdr.htm new file mode 100644 index 0000000..d9845f5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/cdr.htm @@ -0,0 +1,85 @@ +<html><head><title>XLISP cdr</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cdr</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>cdr</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - a list expression<br>
+returns - <i>expr</i> with the first element removed</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'cdr' function returns the <a href="rest.htm">rest</a> of a
+list expression after the first element of the list is removed. <nobr>If
+the</nobr> list <nobr>is <a href="nil.htm">NIL</a></nobr>, then
+<a href="nil.htm">NIL</a> is returned.</p>
+
+<p>The 'cdr' function returns the same result as the
+<a href="rest.htm">rest</a> function.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(cdr '(a b c)) => (B C)
+(cdr '((a b) c d)) => (C D)
+(cdr nil) => NIL
+(cdr 'a) => <font color="#AA0000">error: bad argument type</font>
+(cdr '(a)) => NIL
+(setq ben '(a b c)) =>
+(cdr ben) => (B C)
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#list-functions">List Functions</a></nobr></li>
+<li><nobr>Tutorials → Lisp Hints → <a href="../tutorials/lisp-hints.htm#list-accessors">List Accessors</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/cerror.htm b/docsrc/xlisp/xlisp-doc/reference/cerror.htm new file mode 100644 index 0000000..116f9f3 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/cerror.htm @@ -0,0 +1,23 @@ +<html><head><title>XLISP cerror</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cerror</h1>
+
+<hr>
+
+<p>See <a href="error.htm">error</a>.</p>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-code.htm b/docsrc/xlisp/xlisp-doc/reference/char-code.htm new file mode 100644 index 0000000..eafd74b --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-code.htm @@ -0,0 +1,86 @@ +<html><head><title>XLISP char-code</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char-code</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char-code</b> <i>char</i>)</dt>
+<dd><i>char</i> - a character expression<br>
+returns - the decimal <a href="../misc/ascii-table.htm">ASCII</a>
+value as an integer</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'char-code' function returns the decimal
+<a href="../misc/ascii-table.htm">ASCII</a> value of the 'char'
+expression.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char-code #\0) => 48
+(char-code #\A) => 65
+(char-code #\a) => 97
+(char-code #\[) => 91
+(char-code #\newline) => 10
+(char-code (code-char 127)) => 127
+(char-code (int-char 255)) => 255
+</pre>
+
+<p><b>Note:</b> In <nobr>Nyquist/XLISP</nobr>, '<nobr>char-code</nobr>' and
+<a href="char-int.htm">char-int</a> are two different functions, but behave
+exactly the same <nobr>[Nyquist 3.03</nobr>, <nobr>December
+2010</nobr>].</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-downcase.htm b/docsrc/xlisp/xlisp-doc/reference/char-downcase.htm new file mode 100644 index 0000000..bcf5829 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-downcase.htm @@ -0,0 +1,79 @@ +<html><head><title>XLISP char-downcase</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char-downcase</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char-downcase</b> <i>char</i>)</dt>
+<dd><i>char</i> - a character expression<br>
+returns - the lower case character</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The '<nobr>char-downcase</nobr>' function converts the 'char' expression
+to lower case. The lower case equivalent of 'char' is returned. <nobr>If
+'char'</nobr> is not alphabetic <nobr>[a-z or A-Z],</nobr> then the
+character is returned unchanged.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char-downcase #\0) => #\0
+(char-downcase #\A) => #\a
+(char-downcase #\a) => #\a
+(char-downcase #\[) => #\[
+(char-downcase #\+) => #\+
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-equal-i.htm b/docsrc/xlisp/xlisp-doc/reference/char-equal-i.htm new file mode 100644 index 0000000..a4a53b4 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-equal-i.htm @@ -0,0 +1,89 @@ +<html><head><title>XLISP char-equal</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char-equal</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char-equal</b> <i>char1 charN</i> ... )</dt>
+<dd><i>char1</i> - a character expression<br>
+<i>charN</i> - character expression[s] to compare<br>
+returns - <a href="t.htm"> T </a> if all characters
+are equal, <a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is not significant with this function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'char-equal' function tests if all the character arguments are
+equivalent. <a href="t.htm"> T </a> is returned if the arguments
+are of the same <a href="../misc/ascii-table.htm">ASCII</a> value,
+<a href="nil.htm">NIL</a> otherwise. <nobr>In the</nobr> case of two
+arguments, this has the effect of testing if 'char1' is equal to 'char2'.
+This test is case insensitive, the character '#\a' is considered to be the
+same <a href="../misc/ascii-table.htm">ASCII</a> value as the
+<nobr>character '#\A'.</nobr></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char-equal #\a #\b) => NIL
+(char-equal #\b #\a) => NIL
+(char-equal #\a #\b #\c) => NIL
+(char-equal #\a #\a) => T
+(char-equal #\a #\a #\a) => T
+(char-equal #\a #\a #\b) => NIL
+(char-equal #\A #\a) => T
+(char-equal #\a #\A) => T
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-equal-s.htm b/docsrc/xlisp/xlisp-doc/reference/char-equal-s.htm new file mode 100644 index 0000000..04e268f --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-equal-s.htm @@ -0,0 +1,91 @@ +<html><head><title>XLISP char=</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char=</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char=</b> <i>char1 charN</i> ... )</dt>
+<dd><i>char1</i> - a character expression<br>
+<i>charN</i> - character expression[s] to compare<br>
+returns - <a href="t.htm"> T </a>
+if the characters are of the same
+<a href="../misc/ascii-table.htm">ASCII</a> value,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is significant with this function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'char=' function tests if all the character arguments are equivalent.
+<nobr><a href="t.htm"> T </a> is</nobr> returned if the arguments
+are of the same <a href="../misc/ascii-table.htm">ASCII</a> value,
+<a href="nil.htm">NIL</a> otherwise. <nobr>In the</nobr> case of two
+arguments, this has the effect of testing if 'char1' is equal to 'char2'.
+This test is case sensitive, the character '#\a' is different and of greater
+<a href="../misc/ascii-table.htm">ASCII</a> value than the <nobr>character
+'#\A'</nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char= #\a #\b) => NIL
+(char= #\b #\a) => NIL
+(char= #\a #\b #\c) => NIL
+(char= #\a #\a) => T
+(char= #\a #\a #\a) => T
+(char= #\a #\a #\b) => NIL
+(char= #\A #\a) => NIL
+(char= #\a #\A) => NIL
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-greaterp-i.htm b/docsrc/xlisp/xlisp-doc/reference/char-greaterp-i.htm new file mode 100644 index 0000000..7188588 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-greaterp-i.htm @@ -0,0 +1,91 @@ +<html><head><title>XLISP char-greaterp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char-greaterp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char-greaterp</b> <i>char1 charN</i> ... )</dt>
+<dd><i>char1</i> - a character expression<br>
+<i>charN</i> - character expression(s) to compare<br>
+returns - <a href="t.htm"> T </a>
+if the characters are of monotonically decreasing
+<a href="../misc/ascii-table.htm">ASCII</a> value,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is not significant with this function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The '<nobr>char-greaterp</nobr>' function tests if all the character
+arguments are monotonically decreasing.
+<nobr><a href="t.htm"> T </a> is</nobr> returned if the arguments
+are of monotonically decreasing <a href="../misc/ascii-table.htm">ASCII</a>
+value, <a href="nil.htm">NIL</a> otherwise. <nobr>In the</nobr> case of two
+arguments, this has the effect of testing if 'char1' is greater than
+'char2'. This test is case insensitive, the character '#\a' is considered to
+be the same <a href="../misc/ascii-table.htm">ASCII</a> value as the
+<nobr>character '#\A'.</nobr></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char-greaterp #\a #\b) => NIL
+(char-greaterp #\b #\a) => T
+(char-greaterp #\c #\b #\a) => T
+(char-greaterp #\a #\a) => NIL
+(char-greaterp #\c #\a #\b) => NIL
+(char-greaterp #\A #\a) => NIL
+(char-greaterp #\a #\A) => NIL
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-greaterp-s.htm b/docsrc/xlisp/xlisp-doc/reference/char-greaterp-s.htm new file mode 100644 index 0000000..95c3258 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-greaterp-s.htm @@ -0,0 +1,91 @@ +<html><head><title>XLISP char></title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char></h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char></b> <i>char1 charN</i> ... )</dt>
+<dd><i>char1</i> - a character expression<br>
+<i>charN</i> - character expression[s] to compare<br>
+returns - <a href="t.htm"> T </a>
+if the characters are of monotonically decreasing
+<a href="../misc/ascii-table.htm">ASCII</a> value,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is significant with this function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'char>' function tests if all the character arguments are
+monotonically decreasing. <nobr><a href="t.htm"> T </a> is</nobr>
+returned if the arguments are of monotonically decreasing
+<a href="../misc/ascii-table.htm">ASCII</a> value, <a href="nil.htm">NIL</a>
+otherwise. <nobr>In the</nobr> case of two arguments, this has the effect of
+testing if 'char1' is greater than 'char2'. This test is case sensitive, the
+character '#\a' is different and of greater <a
+href="../misc/ascii-table.htm">ASCII</a> value than the
+<nobr>character '#\A'</nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char> #\a #\b) => NIL
+(char> #\b #\a) => T
+(char> #\c #\b #\a) => T
+(char> #\a #\a) => NIL
+(char> #\c #\a #\b) => NIL
+(char> #\A #\a) => NIL
+(char> #\a #\A) => T
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-int.htm b/docsrc/xlisp/xlisp-doc/reference/char-int.htm new file mode 100644 index 0000000..dbb279c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-int.htm @@ -0,0 +1,86 @@ +<html><head><title>XLISP char-int</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char-int</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char-int</b> <i>char</i>)</dt>
+<dd><i>char</i> - a character expression<br>
+returns - the decimal <a href="../misc/ascii-table.htm">ASCII</a>
+value as an integer</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The '<nobr>char-int</nobr>' function returns the decimal
+<a href="../misc/ascii-table.htm">ASCII</a> value of the 'char'
+expression.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char-int #\0) => 48</font>
+(char-int #\A) => 65</font>
+(char-int #\a) => 97</font>
+(char-int #\[) => 91</font>
+(char-int #\newline) => 10</font>
+(char-int (code-char 127)) => 127</font>
+(char-int (int-char 255)) => 255</font>
+</pre>
+
+<p><b>Note:</b> In <nobr>Nyquist/XLISP</nobr>,
+<a href="char-code.htm">char-code</a> and '<nobr>char-int</nobr>' are two
+different functions, but behave exactly the same <nobr>[Nyquist 3.03</nobr>,
+<nobr>December 2010</nobr>].</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-lessp-i.htm b/docsrc/xlisp/xlisp-doc/reference/char-lessp-i.htm new file mode 100644 index 0000000..6b662ab --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-lessp-i.htm @@ -0,0 +1,91 @@ +<html><head><title>XLISP char-lessp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char-lessp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char-lessp</b> <i>char1 charN</i> ... )</dt>
+<dd><i>char1</i> - a character expression<br>
+<i>charN</i> - character expression[s] to compare<br>
+returns - <a href="t.htm"> T </a>
+if the characters are of monotonically increasing
+<a href="../misc/ascii-table.htm">ASCII</a> value,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is not significant with this function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The '<nobr>char-lessp</nobr>' function tests if all the character
+arguments are monotonically increasing.
+<nobr><a href="t.htm"> T </a> is</nobr> returned if the arguments
+are of increasing <a href="../misc/ascii-table.htm">ASCII</a> value,
+<a href="nil.htm">NIL</a> otherwise. <nobr>In the</nobr> case of two
+arguments, this has the effect of testing if 'char1' is less than 'char2'.
+This test is case insensitive, the <nobr>character '#\a'</nobr> is
+considered to be the same <a href="../misc/ascii-table.htm">ASCII</a> value
+as the <nobr>character '#\A'.</nobr></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char-lessp #\a #\b) => T
+(char-lessp #\b #\a) => NIL
+(char-lessp #\a #\b #\c) => T
+(char-lessp #\a #\a) => NIL
+(char-lessp #\a #\b #\b) => NIL
+(char-lessp #\A #\a) => NIL
+(char-lessp #\a #\A) => NIL
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-lessp-s.htm b/docsrc/xlisp/xlisp-doc/reference/char-lessp-s.htm new file mode 100644 index 0000000..5bee3dd --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-lessp-s.htm @@ -0,0 +1,92 @@ +<html><head><title>XLISP char<</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+
+<h1>char<</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char<</b> <i>char1 charN</i> ... )</dt>
+<dd><i>char1</i> - a character expression<br>
+<i>charN</i> - character expression[s] to compare<br>
+returns - <a href="t.htm"> T </a>
+if the characters are of monotonically increasing
+<a href="../misc/ascii-table.htm">ASCII</a> value,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is significant with this function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p> The 'char<' function tests if all the character arguments are
+monotonically increasing. <a href="t.htm"> T </a> is returned if
+the arguments are of monotonically increasing
+<a href="../misc/ascii-table.htm">ASCII</a> value, <a href="nil.htm">NIL</a>
+otherwise. <nobr>In the</nobr> case of two arguments, this has the effect of
+testing if 'char1' is less than 'char2'. This test is case sensitive, the
+character '#\a' is different and of greater
+<a href="../misc/ascii-table.htm">ASCII</a> value than the <nobr>character
+'#\A'</nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char< #\a #\b) => T
+(char< #\b #\a) => NIL
+(char< #\a #\b #\c) => T
+(char< #\a #\a) => NIL
+(char< #\a #\b #\b) => NIL
+(char< #\A #\a) => T
+(char< #\a #\A) => NIL
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-not-equal-i.htm b/docsrc/xlisp/xlisp-doc/reference/char-not-equal-i.htm new file mode 100644 index 0000000..5d649b5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-not-equal-i.htm @@ -0,0 +1,90 @@ +<html><head><title>XLISP char-not-equal</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char-not-equal</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char-not-equal</b> <i>char1 charN</i> ... )</dt>
+<dd><i>char1</i> - a character expression<br>
+<i>charN</i> - character expression(s) to compare<br>
+returns - <a href="t.htm"> T </a>
+if the characters are of different
+<a href="../misc/ascii-table.htm">ASCII</a> value,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is not significant with this function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The '<nobr>char-not-equal</nobr>' function tests if all the character
+arguments are different values. <nobr><a href="t.htm"> T </a>
+is</nobr> returned if the arguments are of different
+<a href="../misc/ascii-table.htm">ASCII</a> value, <a href="nil.htm">NIL</a>
+otherwise. <nobr>In the</nobr> case of two arguments, this has the effect of
+testing if 'char1' is not equal to 'char2'. This test is case insensitive,
+the <nobr>character '#\a'</nobr> is considered to be the same
+<a href="../misc/ascii-table.htm">ASCII</a> value as the <nobr>character
+'#\A'.</nobr></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char-not-equal #\a #\b) => T
+(char-not-equal #\a #\b #\c) => T
+(char-not-equal #\a #\a) => NIL
+(char-not-equal #\a #\b #\b) => NIL
+(char-not-equal #\A #\a) => NIL
+(char-not-equal #\a #\A) => NIL
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-not-equal-s.htm b/docsrc/xlisp/xlisp-doc/reference/char-not-equal-s.htm new file mode 100644 index 0000000..d8876ff --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-not-equal-s.htm @@ -0,0 +1,98 @@ +<html><head><title>XLISP char/=</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char/=</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char/=</b> <i>char1 charN</i> ... )</dt>
+<dd>char1 - a character expression<br>
+charN - character expression[s] to compare<br>
+returns - <a href="t.htm"> T </a>
+if the characters are not equal,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is significant with this function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'char/=' function tests if all character arguments are different
+values. <nobr><a href="t.htm"> T </a> is</nobr> returned if the
+arguments are of different <a href="../misc/ascii-table.htm">ASCII</a>
+value, <a href="nil.htm">NIL</a> otherwise. <nobr>In the</nobr> case of two
+arguments, this has the effect of testing if 'char1' is not equal to
+'char2'. This test is case sensitive, the character '#\a' is different and
+of greater <a href="../misc/ascii-table.htm">ASCII</a> value than the
+<nobr>character '#\A'</nobr>.</nobr></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char/= #\a #\b) => T
+(char/= #\a #\b #\c) => T
+(char/= #\a #\a) => NIL
+(char/= #\a #\b #\b) => NIL
+(char/= #\A #\a) => T
+(char/= #\a #\A) => T
+</pre>
+
+<p><div class="box">
+
+<p><b>Caution:</b> If you type 'char\=' [with a backslash] instead of
+'string/=' by mistake, no error will be signalled because backslash is the
+single escape character and the XLISP reader will evaluate 'char\=' as
+<a href="char-equal-s.htm">char=</a>, but the meaning of the test is
+exactly reversed.</p>
+
+</div></p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-not-greaterp-i.htm b/docsrc/xlisp/xlisp-doc/reference/char-not-greaterp-i.htm new file mode 100644 index 0000000..010bad1 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-not-greaterp-i.htm @@ -0,0 +1,92 @@ +<html><head><title>XLISP char-not-greaterp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char-not-greaterp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char-not-greaterp</b> <i>char1 charN</i> ... )</dt>
+<dd><i>char1</i> - a character expression<br>
+<i>charN</i> - character expression[s] to compare<br>
+returns - <a href="t.htm"> T </a>
+if the characters are of monotonically <nobr>non-decreasing</nobr>
+<a href="../misc/ascii-table.htm">ASCII</a> value,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is not significant with this function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The '<nobr>char-not-greaterp</nobr>' function tests if all character
+arguments are monotonically <nobr>non-decreasing</nobr>.
+<nobr><a href="t.htm"> T </a> is</nobr> returned if the arguments
+are of monotonically non-decreasing
+<a href="../misc/ascii-table.htm">ASCII</a> value, <a href="nil.htm">NIL</a>
+otherwise. <nobr>In the</nobr> case of two arguments, this has the effect of
+testing if 'char1' is less than or equal to 'char2'. This test is case
+insensitive, the <nobr>character '#\a'</nobr> is considered to be the same
+<a href="../misc/ascii-table.htm">ASCII</a> value as the <nobr>character
+'#\A'.</nobr></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char-not-greaterp #\a #\b) => T
+(char-not-greaterp #\b #\a) => NIL
+(char-not-greaterp #\a #\b #\c) => T
+(char-not-greaterp #\a #\a) => T
+(char-not-greaterp #\a #\b #\b) => T
+(char-not-greaterp #\A #\a) => T
+(char-not-greaterp #\a #\A) => T
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-not-greaterp-s.htm b/docsrc/xlisp/xlisp-doc/reference/char-not-greaterp-s.htm new file mode 100644 index 0000000..ba1d599 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-not-greaterp-s.htm @@ -0,0 +1,92 @@ +<html><head><title>XLISP char<=</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char<=</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char<=</b> <i>char1 charN</i> ... )</dt>
+<dd><i>char1</i> - a character expression<br>
+<i>charN</i> - character expression[s] to compare<br>
+returns - <a href="t.htm"> T </a>
+if the characters are of monotonically <nobr>non-decreasing</nobr>
+<a href="../misc/ascii-table.htm">ASCII</a> value,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is significant with this function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p> The 'char<=' function tests if all character arguments are
+monotonically <nobr>non-decreasing</nobr>.
+<nobr><a href="t.htm"> T </a> is</nobr> returned if the arguments
+are of monotonically <nobr>non-decreasing</nobr>
+<a href="../misc/ascii-table.htm">ASCII</a> value, <a href="nil.htm">NIL</a>
+otherwise. <nobr>In the</nobr> case of two arguments, this has the effect of
+testing if 'char1' is less than or equal to 'char2'. This test is case
+sensitive, the character '#\a' is different and of greater
+<a href="../misc/ascii-table.htm">ASCII</a> value than the <nobr>character
+'#\A'</nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char<= #\a #\b) => T
+(char<= #\b #\a) => NIL
+(char<= #\a #\b #\c) => T
+(char<= #\a #\a) => T
+(char<= #\a #\b #\b) => T
+(char<= #\A #\a) => T
+(char<= #\a #\A) => NIL
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-not-lessp-i.htm b/docsrc/xlisp/xlisp-doc/reference/char-not-lessp-i.htm new file mode 100644 index 0000000..c991f04 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-not-lessp-i.htm @@ -0,0 +1,92 @@ +<html><head><title>XLISP char-not-lessp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char-not-lessp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char-not-lessp</b> <i>char1 charN</i> ... )</dt>
+<dd><i>char1</i> - a character expression<br>
+<i>charN</i> - character expression[s] to compare<br>
+returns - <a href="t.htm"> T </a>
+if the characters are of monotonically non-increasing
+<a href="../misc/ascii-table.htm">ASCII</a> value,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is not significant with this function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The '<nobr>char-not-lessp</nobr>' function tests if all character
+arguments are monotonically <nobr>non-increasing</nobr>.
+<nobr><a href="t.htm"> T </a> is</nobr> returned if the arguments
+are of monotonically <nobr>non-increasing</nobr>
+<a href="../misc/ascii-table.htm">ASCII</a> value, <a href="nil.htm">NIL</a>
+otherwise. <nobr>In the</nobr> case of two arguments, this has the effect of
+testing if 'char1' is greater than or equal to 'char2'. This test is case
+insensitive, the <nobr>character '#\a'</nobr> is considered to be the same
+<a href="../misc/ascii-table.htm">ASCII</a> value as the <nobr>character
+'#\A'.</nobr></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char-not-lessp #\a #\b) => NIL
+(char-not-lessp #\b #\a) => T
+(char-not-lessp #\c #\b #\a) => T
+(char-not-lessp #\a #\a) => T
+(char-not-lessp #\c #\a #\b) => NIL
+(char-not-lessp #\A #\a) => T
+(char-not-lessp #\a #\A) => T
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-not-lessp-s.htm b/docsrc/xlisp/xlisp-doc/reference/char-not-lessp-s.htm new file mode 100644 index 0000000..3f85269 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-not-lessp-s.htm @@ -0,0 +1,92 @@ +<html><head><title>XLISP char>=</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char>=</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char>=</b> <i>char1 charN</i> ... )</dt>
+<dd><i>char1</i> - a character expression<br>
+<i>charN</i> - character expression[s] to compare<br>
+returns - <a href="t.htm"> T </a>
+if the characters are of monotonically non-increasing
+<a href="../misc/ascii-table.htm">ASCII</a> value,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is significant with this function</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'char>=' function tests if all character arguments are
+monotonically <nobr>non-increasing</nobr>.
+<nobr><a href="t.htm"> T </a> is</nobr> returned if the arguments
+are of monotonically <nobr>non-increasing</nobr>
+<a href="../misc/ascii-table.htm">ASCII</a> value, <a href="nil.htm">NIL</a>
+otherwise. <nobr>In the</nobr> case of two arguments, this has the effect of
+testing if 'char1' is greater than or equal to 'char2'. This test is case
+sensitive, the character '#\a' is different and of greater
+<a href="../misc/ascii-table.htm">ASCII</a> value than the <nobr>characrer
+'#\A'</nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char>= #\a #\b) => NIL
+(char>= #\b #\a) => T
+(char>= #\c #\b #\a) => T
+(char>= #\a #\a) => T
+(char>= #\c #\a #\b) => NIL
+(char>= #\A #\a) => NIL
+(char>= #\a #\A) => T
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char-upcase.htm b/docsrc/xlisp/xlisp-doc/reference/char-upcase.htm new file mode 100644 index 0000000..6d13de0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char-upcase.htm @@ -0,0 +1,79 @@ +<html><head><title>XLISP char-upcase</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char-upcase</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char-upcase</b> <i>char</i>)</dt>
+<dd><i>char</i> - a character expression<br>
+returns - the upper case character</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The '<nobr>char-upcase</nobr>' function converts the 'char' expression to
+upper case. The upper case equivalent of 'char' is returned. <nobr>If
+the</nobr> 'char' is not alphabetic <nobr>[a-z or A-Z],</nobr> the
+character is returned unchanged.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char-upcase #\0) => #\0
+(char-upcase #\A) => #\A
+(char-upcase #\a) => #\A
+(char-upcase #\[) => #\[
+(char-upcase #\+) => #\+
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/char.htm b/docsrc/xlisp/xlisp-doc/reference/char.htm new file mode 100644 index 0000000..39d0a88 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/char.htm @@ -0,0 +1,80 @@ +<html><head><title>XLISP char</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>char</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>char</b> <i>string position</i>)</dt>
+<dd><i>string</i> - a string expression<br>
+<i>position</i> - an integer expression<br>
+returns - the <a href="../misc/ascii-table.htm">ASCII</a> code of
+the character</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'char' function returns the
+<a href="../misc/ascii-table.htm">ASCII</a> numeric value of the character
+at the specified 'position' in the 'string'. <nobr>A position</nobr> of '0'
+is the first character in the string.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(char "12345" 0) => #\1
+(char "12 45" 2) => #\Space
+(string (char "1234" 3)) => "4"
+(char "1234" 9) => <font color="#AA0000">error: index out of range</font>
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/characterp.htm b/docsrc/xlisp/xlisp-doc/reference/characterp.htm new file mode 100644 index 0000000..d5f1d4d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/characterp.htm @@ -0,0 +1,86 @@ +<html><head><title>XLISP characterp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>characterp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>characterp</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - the expression to check<br>
+returns - <a href="t.htm"> T </a> if the value is a
+character, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'characterp' predicate function tests if 'expr' evaluates to a
+character. <nobr><a href="t.htm"> T </a> is</nobr> returned if
+'expr' evaluates to a character, <a href="nil.htm">NIL</a> is returned
+otherwise.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(characterp #\a) => T <font color="#008844">; character</font>
+(setq a #\b) => #\b
+(characterp a) => T <font color="#008844">; evaluates to a character</font>
+(characterp "a") => NIL <font color="#008844">; string</font>
+(characterp '(a b c)) => NIL <font color="#008844">; list</font>
+(characterp 1) => NIL <font color="#008844">; integer</font>
+(characterp 1.2) => NIL <font color="#008844">; float</font>
+(characterp 'a) => NIL <font color="#008844">; symbol</font>
+(characterp #(0 1 2)) => NIL <font color="#008844">; array</font>
+(characterp nil) => NIL <font color="#008844">; NIL</font>
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#predicate-functions">Predicate Functions</a></nobr></li>
+<li><nobr>Contents → <a href="../manual/contents.htm#character-functions">Character Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/class.htm b/docsrc/xlisp/xlisp-doc/reference/class.htm new file mode 100644 index 0000000..af76573 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/class.htm @@ -0,0 +1,113 @@ +<html><head><title>XLISP class</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>class</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>object</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlobj.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> class</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>'class' is the built-in object class that is used to build other classes.
+Classes are, essentially, the template for defining
+<a href="object.htm">object</a> instances.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq myclass (send class :new '(var))) <font color="#008844">; create MYCLASS with VAR</font>
+
+(send myclass :answer :isnew '() <font color="#008844">; set up initialization</font>
+ '((setq var nil) self))
+
+(send myclass :answer :set-it '(value) <font color="#008844">; create :SET-IT message</font>
+ '((setq var value)))
+
+(setq my-obj (send myclass :new)) <font color="#008844">; create MY-OBJ of MYCLASS</font>
+(send my-obj :set-it 5) <font color="#008844">; VAR is set to 5</font>
+</pre>
+
+<p><b>Class definition:</b> The internal definition of the 'class' object
+instance looks like:</p>
+
+<pre class="example">
+Object is #<Object: #23fe2>, Class is #<Object: #23fe2>
+ MESSAGES = ((:ANSWER . #<Subr-: #23e48>)
+ (:ISNEW . #<Subr-: #23e84>)
+ (:NEW . #<Subr-: #23ea2>))
+ IVARS = (MESSAGES IVARS CVARS CVALS SUPERCLASS IVARCNT IVARTOTAL)
+ CVARS = NIL
+ CVALS = NIL
+ SUPERCLASS = #<Object: #23fd8>
+ IVARCNT = 7
+ IVARTOTAL = 7
+#<Object: #23fe2>
+</pre>
+
+<p>The class of 'class' is 'class', itself. The superclass of 'class' is
+<a href="object.htm">object</a>. Remember that the location
+information [like #23fe2] varies from system to system, yours will probably
+look different.</p>
+
+<p><b>Built-in methods:</b> The built in methods in XLISP include:</p>
+
+<ul>
+<li><nobr><a href="keyword-answer.htm">:answer</a> - add a method to an <a href="object.htm">object</a></nobr></li>
+<li><nobr><a href="keyword-class.htm">:class</a> - return the <a href="object.htm">object</a>'s class</nobr></li>
+<li><nobr><a href="keyword-isnew.htm">:isnew</a> - run initialization code on <a href="object.htm">object</a></nobr></li>
+<li><nobr><a href="keyword-new.htm">:new</a> - create a new <a href="object.htm">object</a> [instance or class]</nobr></li>
+<li><nobr><a href="keyword-show.htm">:show</a> - show the internal state of the <a href="object.htm">object</a></nobr></li>
+</ul>
+
+<p><b>Message Structure:</b> The normal XLISP convention for a 'message' is
+to have a valid symbol preceeded by a colon like
+<a href="keyword-isnew.htm">:isnew</a> or ':my-message'. However, it
+is possible to define a 'message' that is a symbol without a colon, but
+this makes the code less readable.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-010.htm#class">class</a>
+object in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/clean-up.htm b/docsrc/xlisp/xlisp-doc/reference/clean-up.htm new file mode 100644 index 0000000..98faa09 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/clean-up.htm @@ -0,0 +1,90 @@ +<html><head><title>XLISP clean-up</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>clean-up</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c, xldbug.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(clean-up)</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'clean-up' function aborts one level of the
+<nobr><a href="../manual/xlisp-man-004.htm">break loop</a>.</nobr> This
+is valid for <nobr><a href="break.htm">break</a>s ,</nobr>
+<a href="error.htm">error</a>s and
+<a href="cerror.htm">cerror</a>s [continuable errors].
+If 'clean-up' is evaluated while not in a
+<nobr><a href="../manual/xlisp-man-004.htm">break loop</a> ,</nobr>
+an error is generated:
+
+<pre class="example">
+<font color="#AA0000">error: not in a break loop</font>
+</pre>
+
+<p>This error does not cause XLISP to go into a
+<nobr><a href="../manual/xlisp-man-004.htm">break loop</a>.</nobr>
+'clean-up' never actually returns a value.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(clean-up) <font color="#008844">; [back to previous break level]</font>
+(break "out") <font color="#008844">; break: out</font>
+(clean-up) <font color="#008844">; to exit out of break loop</font>
+</pre>
+
+<p><b>Note:</b> With Nyquist, no error is generated if 'clean-up' is
+invoked when not in a
+<nobr><a href="../manual/xlisp-man-004.htm">break loop</a>.</nobr></p>
+
+<p><b>Keystroke equivalent:</b> In the IBM PC and MS-DOS versions of XLISP,
+a 'Ctrl-g' key sequence has the same effect as doing a (clean-up). On a
+Macintosh, this can be accomplished by a pull-down menu or a
+'Command-g'. <nobr>[I haven't</nobr> tested this with Nyquist].</p>
+
+<p>See the
+<a href="../manual/xlisp-man-022.htm#clean-up">clean-up</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/close.htm b/docsrc/xlisp/xlisp-doc/reference/close.htm new file mode 100644 index 0000000..1efb3cd --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/close.htm @@ -0,0 +1,85 @@ +<html><head><title>XLISP close</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>close</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(close <i>file-ptr</i>)</dt>
+<dd><i>file-ptr</i> - a file pointer expression<br>
+returns - <a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'close' function closes the file specified through 'file-ptr'. If
+the file close was successful, then a
+<a href="nil.htm">NIL</a> is returned as the result. For the
+file close to be successful, the 'file-ptr' has to point to a valid file.
+If the file close was not successful, an error is generated:</p>
+
+<pre class="example">
+<font color="#AA0000">error: file not open</font>
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(close (open 'f :direction :output)) <font color="#008844">; returns NIL</font>
+(setq myfile (open 'mine :direction :output)) <font color="#008844">; create MYFILE</font>
+(print "hi" myfile) <font color="#008844">; returns "hi"</font>
+(close myfile) <font color="#008844">; returns NIL</font>
+ <font color="#008844">; file contains <hi> <NEWLINE></font>
+(setq myfile (open 'mine :direction :input)) <font color="#008844">; open MYFILE for input</font>
+(read myfile) <font color="#008844">; returns "hi"</font>
+(close myfile) <font color="#008844">; returns NIL</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common LISP has an XLISP compatible 'close' function.
+Common LISP does support an ':abort' keyword, which is not supported in
+XLISP.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-029.htm#close">close</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/code-char.htm b/docsrc/xlisp/xlisp-doc/reference/code-char.htm new file mode 100644 index 0000000..6497114 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/code-char.htm @@ -0,0 +1,92 @@ +<html><head><title>XLISP code-char</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>code-char</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(code-char <i>code</i>)</dt>
+<dd><i>code</i> - a numeric expression representing the
+<a href="../misc/ascii-table.htm">ASCII</a> code as an integer<br>
+returns - the character with that code or <a href="nil.htm">NIL</a> </dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'code-char' function returns a character which is the result of
+turning 'code' expression into a character. If a 'code' cannot be made into
+a character, <a href="nil.htm">NIL</a> is returned. The range
+that 'code' produces a valid character is <nobr>0 through 127.</nobr></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(code-char 48) <font color="#008844">; returns #\0</font>
+(code-char 65) <font color="#008844">; returns #\A</font>
+(code-char 97) <font color="#008844">; returns #\a</font>
+(code-char 91) <font color="#008844">; returns #\[</font>
+(code-char 10) <font color="#008844">; returns #\Newline</font>
+(code-char 128) <font color="#008844">; returns NIL</font>
+(code-char 999) <font color="#008844">; returns NIL</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp allows for some optional arguments in
+'code-char' because it supports the concept of a complex character that
+includes not only the ASCII code value, but also fonts and bits. The bits
+allow for more than <nobr>8 bits</nobr> per character <nobr>[16 bits</nobr>
+is especially useful in oriental languages]. The fonts allow for up to 128
+different fonts. XLISP does not support fonts and bits or the optional
+parameters associated with them.</p>
+
+<p><b>Note:</b> Unlike the <a href="char-code.htm">char-code</a> and
+<a href="char-int.htm">char-int</a> functions, 'code-char' and
+<a href="int-char.htm">int-char</a> are not identical in use.
+'code-char' accepts 0..127 for its range and then produces
+<a href="nil.htm">NIL</a> results.
+<a href="int-char.htm">int-char</a> accepts 0..255 for its range and
+then produces errors.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-026.htm#code-char">code-char</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/cond.htm b/docsrc/xlisp/xlisp-doc/reference/cond.htm new file mode 100644 index 0000000..a86d487 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/cond.htm @@ -0,0 +1,95 @@ +<html><head><title>XLISP cond</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cond</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(cond [(<i>pred1 expr1</i>) [(<i>pred2 expr2</i>) ... ]])</dt>
+<dd><i>predN</i> - a predicate <nobr>(<a href="nil.htm">NIL</a> /
+non-<a href="nil.htm">NIL</a>)</nobr> expression<br>
+<i>exprN</i> - an expression<br>
+returns - the value of the first expression whose predicate is
+non-<a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'cond' special form evaluates a series of <nobr>predicate /</nobr>
+expression pairs. 'cond' will evaluate each predicate in sequential order
+until it finds one that returns a non-<a href="nil.htm">NIL</a>
+value. The expression that is associated with the
+non-<a href="nil.htm">NIL</a> value is evaluated. The resulting
+value of the evaluated expression is returned by 'cond'. If there are no
+predicates that return a non-<a href="nil.htm">NIL</a> value,
+<a href="nil.htm">NIL</a> is returned by 'cond'. Only one
+expression is evaluated, the first one with a
+non-<a href="nil.htm">NIL</a> predicate. Note that the predicate
+can be a symbol or expression.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(cond <font color="#008844">; sample CONDitional</font>
+ ((not T) (print "this won't print"))
+ ( NIL (print "neither will this"))
+ ( T (print "this will print"))
+ ( T (print "won't get here"))) <font color="#008844">; prints "this will print"</font>
+
+(defun print-what (parm)
+ (cond <font color="#008844">; start of COND</font>
+ ((numberp parm) (print "numeric")) <font color="#008844">; check for number</font>
+ ((consp parm) (print "list")) <font color="#008844">; check for list</font>
+ ((null parm) (print "nil")) <font color="#008844">; check for NIL</font>
+ (T (print "something")))) <font color="#008844">; catch-all</font>
+
+(print-what 'a) <font color="#008844">; prints "something"</font>
+(print-what 12) <font color="#008844">; prints "numeric"</font>
+(print-what NIL) <font color="#008844">; prints "nil"</font>
+(print-what '(a b)) <font color="#008844">; prints "list"</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-019.htm#cond">cond</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/cons.htm b/docsrc/xlisp/xlisp-doc/reference/cons.htm new file mode 100644 index 0000000..08edf55 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/cons.htm @@ -0,0 +1,74 @@ +<html><head><title>XLISP cons</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cons</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(cons <i>expr-car expr-cdr</i>)</dt>
+<dd><i>expr-car</i> - an expression<br>
+<i>expr-cdr</i> - an expression<br>
+returns - the new list</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'cons' function takes two expressions and constructs a new list from
+them. If the 'expr-cdr' is not a list, then the result will be a
+'dotted-pair'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(cons 'a 'b) <font color="#008844">; returns (A . B)</font>
+(cons 'a nil) <font color="#008844">; returns (A)</font>
+(cons 'a '(b)) <font color="#008844">; returns (A B)</font>
+(cons '(a b) '(c d)) <font color="#008844">; returns ((A B) C D)</font>
+(cons '(a b) 'c) <font color="#008844">; returns ((A B) . C)</font>
+(cons (- 4 3) '(2 3)) <font color="#008844">; returns (1 2 3)</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#cons">cons</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/consp.htm b/docsrc/xlisp/xlisp-doc/reference/consp.htm new file mode 100644 index 0000000..9c2a8ef --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/consp.htm @@ -0,0 +1,95 @@ +<html><head><title>XLISP consp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>consp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(consp <i>expr</i>)</dt>
+<dd><i>expr</i> - the expression to check<br>
+returns - <a href="t.htm"> T </a> if the value is a
+cons, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p> The 'consp' predicate checks if the 'expr' is a non-empty list.
+<a href="t.htm"> T </a> is returned if 'expr' is a
+list, <a href="nil.htm">NIL</a> is returned otherwise. Note that
+if the 'expr' is <nobr><a href="nil.htm">NIL</a> ,</nobr>
+<a href="nil.htm">NIL</a> is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(consp '(a b)) <font color="#008844">; returns T - list</font>
+(consp '(a . b)) <font color="#008844">; returns T - dotted pair list</font>
+(consp #'defvar) <font color="#008844">; returns NIL - closure - macro</font>
+(consp (lambda (x) (print x))) <font color="#008844">; returns NIL - closure - lambda</font>
+(consp NIL) <font color="#008844">; returns NIL - NIL</font>
+(consp #(1 2 3)) <font color="#008844">; returns NIL - array</font>
+(consp *standard-output*) <font color="#008844">; returns NIL - stream</font>
+(consp 1.2) <font color="#008844">; returns NIL - float</font>
+(consp #'quote) <font color="#008844">; returns NIL - fsubr</font>
+(consp 1) <font color="#008844">; returns NIL - integer</font>
+(consp object) <font color="#008844">; returns NIL - object</font>
+(consp "str") <font color="#008844">; returns NIL - string</font>
+(consp #'car) <font color="#008844">; returns NIL - subr</font>
+(consp 'a) <font color="#008844">; returns NIL - symbol</font>
+</pre>
+
+<p><b>Note:</b> When applied to 'consp',
+<nobr><a href="nil.htm">NIL</a> ,</nobr> the empty list, returns
+a <a href="nil.htm">NIL</a>. <a href="global-obarray.html">NIL</a>
+or '() is used in many places as a list-class or atom-class expression. Both
+<a href="atom.htm">atom</a>
+and <nobr><a href="listp.htm">listp</a> ,</nobr> when applied to
+<nobr><a href="nil.htm">NIL</a> ,</nobr> return
+<a href="t.htm"> T </a>. If you wish to check for a
+list where an empty list is still considered a valid list, use the
+<a href="listp.htm">listp</a> predicate.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#consp">consp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/continue.htm b/docsrc/xlisp/xlisp-doc/reference/continue.htm new file mode 100644 index 0000000..44c620e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/continue.htm @@ -0,0 +1,90 @@ +<html><head><title>XLISP continue</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>continue</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c, xldbug.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(continue)</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p> The 'continue' function attempts to continue from the
+<nobr><a href="../manual/xlisp-man-004.htm">break loop</a>.</nobr>
+This is valid only for <a href="cerror.htm">cerror</a>s [continuable
+errors]. If 'continue' is evaluated while not in a
+<nobr><a href="../manual/xlisp-man-004.htm">break loop</a> ,</nobr> an
+error is generated:</p>
+
+<pre class="example">
+<font color="#AA0000">error: not in a break loop</font>
+</pre>
+
+<p>In Nyquist, the error is:</p>
+
+<pre class="example">
+<font color="#AA0000">error: this error can't be continued</font>
+</pre>
+
+<p>This error does not cause XLISP to go into a break loop. 'continue' never
+actually returns a value.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(continue) <font color="#008844">; error: not in a break loop</font>
+(break "out") <font color="#008844">; break: out</font>
+(continue) <font color="#008844">; to continue from break loop</font>
+ <font color="#008844">; BREAK returns NIL</font>
+</pre>
+
+<p><b>Keystroke equivalent:</b> In the IBM PC and MS-DOS versions of XLISP,
+a 'Ctrl-p' key sequence has the same effect as doing a (continue). On a
+Macintosh, this can be accomplished by a pull-down menu or a 'Command-p'.
+<nobr>[I haven't</nobr> tested this with Nyquist.]</p>
+
+<p>See the
+<a href="../manual/xlisp-man-022.htm#continue">continue</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/cos.htm b/docsrc/xlisp/xlisp-doc/reference/cos.htm new file mode 100644 index 0000000..26bd1f3 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/cos.htm @@ -0,0 +1,71 @@ +<html><head><title>XLISP cos</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cos</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(cos <i>expr</i>)</dt>
+<dd><i>expr</i> - floating point number/expression<br>
+returns - the cosine of the number</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'cos' function returns the cosine of the 'expr'. The 'expr' is
+in radians.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(cos 0.0) <font color="#008844">; returns 1</font>
+(cos (/ 3.14159 2)) <font color="#008844">; returns 1.32679e-06 (almost 0)</font>
+(cos .5) <font color="#008844">; returns 0.877583</font>
+(cos 0) <font color="#008844">; error: bad integer operation</font>
+(cos 1.) <font color="#008844">; error: bad integer operation</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-023.htm#cos">cos</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/decf.htm b/docsrc/xlisp/xlisp-doc/reference/decf.htm new file mode 100644 index 0000000..1714e3f --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/decf.htm @@ -0,0 +1,88 @@ +<html><head><title>XLISP decf</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>decf</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp macro (closure)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>misc.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>decf</b> <i>symbol</i>)</nobr></dt>
+<dd><i>symbol</i> - a symbol with numerical value bound to it<br>
+returns - the new value of the symbol</dd>
+</dl>
+
+</div></p>
+
+<p>In Nyquist, 'decf' is implemented as a Lisp macro:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">decf</font> (symbol)
+ `(setf ,symbol (1- ,symbol)))
+</pre>
+
+<h2>Description</h2>
+
+<p>The 'decf' macro is used for decrementing a numerical value of a variable.
+<nobr>1 is</nobr> substracted to the number and the result is stored in the
+variable. <nobr>An error</nobr> is signalled if the variable doesn't hold a
+number.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq n 3) => 3
+(decf n) => 2
+n => 2
+(decf n) => 1
+
+(setq n 1.8) => 1.8
+(decf n) => 0.8
+(decf n) => -0.2
+(decf n) => -1.2
+n => -1.2
+
+(setq n #\a) => #\a
+(decf a) => <font color="#AA0000">error: bad argument type - #\a</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/decrement.htm b/docsrc/xlisp/xlisp-doc/reference/decrement.htm new file mode 100644 index 0000000..e41a3bd --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/decrement.htm @@ -0,0 +1,75 @@ +<html><head><title>XLISP 1-</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>1−</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(1- <i>expr</i>)</nobr></dt>
+<dd><i>expr</i> - integer or floating point number/expression<br>
+returns - the number minus one</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The <nobr>'1-' [decrement]</nobr> function subtracts one from a number
+and returns the result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(1- 1) => 0
+(1- 99.6) => 98.6
+(1- 1 2) => <font color="#AA0000">error: too many arguments</font>
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/defmacro.htm b/docsrc/xlisp/xlisp-doc/reference/defmacro.htm new file mode 100644 index 0000000..c1dc67d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/defmacro.htm @@ -0,0 +1,142 @@ +<html><head><title>XLISP defmacro</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>defmacro</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(defmacro <i>symbol arg-list body</i>)</dt>
+<dd><i>symbol</i> - the name of the macro being defined<br>
+<i>arg-list</i> - a list of the formal arguments to the macro of the form:<br>
+<dl>
+<dd>([<i>arg1</i> ... ]<br>
+ [<a href="lambda-keyword-optional.htm">&optional</a> <i>oarg1</i> ... ]<br>
+ [<a href="lambda-keyword-rest.htm">&rest</a> <i>rarg</i>]<br>
+ [<a href="lambda-keyword-key.htm">&key</a> ... ]<br>
+ [<a href="lambda-keyword-aux.htm">&aux</a> <i>aux1</i> ... ])<br></dd>
+</dl>
+<i>body</i> - a series of LISP forms (expressions) that are executed in order.<br>
+returns - the macro <i>symbol</i></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>'defmacro' defines a macro expansion. When the 'symbol' name of the macro
+expansion is encountered [similar to a function invocation], the 'body' of
+code that was defined in the 'defmacro' is expanded and replaces the macro
+invocation.</p>
+
+<p>All of the 'argN' formal arguments that are defined are required to
+appear in the invocation of the macro expansion.</p>
+
+<p>If there are any
+<a href="lambda-keyword-optional.htm">&optional</a> arguments defined, they will
+be filled in order.</p>
+
+<p>If there is a <a href="lambda-keyword-rest.htm">&rest</a>
+argument defined, and all the required formal arguments and
+<a href="lambda-keyword-optional.htm">&optional</a> arguments are filled, any and
+all further parameters will be passed into the function via the 'rarg'
+argument. <b>Note</b> that there can be only one 'rarg' argument for
+<a href="lambda-keyword-rest.htm">&rest</a>.</p>
+
+<p>If there are insufficient parameters for any of the
+<a href="lambda-keyword-optional.htm">&optional</a> or
+<a href="lambda-keyword-rest.htm">&rest</a> arguments, they will contain
+<a href="nil.htm">NIL</a>.</p>
+
+<p>The <a href="lambda-keyword-aux.htm">&aux</a> variables are a mechanism
+for you to define variables local to the 'defmacro' execution. At the end of
+the function execution, these local symbols and their values are are
+removed.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defmacro plus (num1 num2) <font color="#008844">; define PLUS macro</font>
+ `(+ ,num1 ,num2)) <font color="#008844">; which is a 2 number add</font>
+
+(plus 1 2) <font color="#008844">; returns 3</font>
+(setq x 10) <font color="#008844">; set x to 10</font>
+(setq y 20) <font color="#008844">; set y to 20</font>
+(plus x y) <font color="#008844">; returns 30</font>
+
+(defmacro betterplus (num &rest nlist) <font color="#008844">; define a BETTERPLUS macro</font>
+ `(+ ,num ,@nlist)) <font color="#008844">; which can take many numbers</font>
+
+(betterplus 1) <font color="#008844">; returns 1</font>
+(betterplus 1 2 3) <font color="#008844">; returns 6</font>
+(betterplus 1 2 3 4 5) <font color="#008844">; returns 15</font>
+
+(defmacro atest (x &optional y &rest z) <font color="#008844">; define ATEST macro</font>
+ (princ " x: ") (princ x) <font color="#008844">; \</font>
+ (princ " y: ") (princ y) <font color="#008844">; print out the parameters</font>
+ (princ " z: ") (princ z) (terpri) <font color="#008844">; / (un-evaluated)</font>
+ `(print (+ ,x ,y ,@z))) <font color="#008844">; add them together (eval'ed)</font>
+
+(atest 1) <font color="#008844">; prints - x: 1 y: NIL z: NIL</font>
+ <font color="#008844">; error: bad argument type</font>
+ <font color="#008844">; because (+ 1 NIL) isn't valid</font>
+(atest 1 2) <font color="#008844">; prints - x: 1 y: 2 z: NIL</font>
+ <font color="#008844">; returns 3</font>
+(atest 1 2 3) <font color="#008844">; prints - x: 1 y: 2 z: (3)</font>
+ <font color="#008844">; returns 6</font>
+(atest 1 2 3 4 5) <font color="#008844">; prints - x: 1 y: 2 z: (3 4 5)</font>
+ <font color="#008844">; returns 15</font>
+(setq a 99) <font color="#008844">; set A to 99</font>
+(setq b 101) <font color="#008844">; set B to 101</font>
+(atest a b) <font color="#008844">; prints - x: A y: B z: NIL</font>
+ <font color="#008844">; returns 200</font>
+(atest a b 9 10 11) <font color="#008844">; prints - x: A y: B z: (9 10 11)</font>
+ <font color="#008844">; returns 230</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp supports an optional documentation
+string as the first form in the 'body' of a 'defmacro' or
+<a href="defun.htm">defun</a>. XLISP will accept this string
+as a valid form, but it will not do anything special with it.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-013.htm#defmacro">defmacro</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/defun.htm b/docsrc/xlisp/xlisp-doc/reference/defun.htm new file mode 100644 index 0000000..aaa97c1 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/defun.htm @@ -0,0 +1,134 @@ +<html><head><title>XLISP defun</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>defun</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(defun <i>symbol arg-list body</i>)</dt>
+<dd><i>symbol</i> - the name of the function being defined<br>
+<i>arg-list</i> - a list of the formal arguments to the function of the form:<br>
+<dl>
+<dd>([<i>arg1</i> ... ]<br>
+ [<a href="lambda-keyword-optional.htm">&optional</a> <i>oarg1</i> ... ]<br>
+ [<a href="lambda-keyword-rest.htm">&rest</a> <i>rarg</i>]<br>
+ [<a href="lambda-keyword-key.htm">&key</a> ... ]<br>
+ [<a href="lambda-keyword-aux.htm">&aux</a> <i>aux1</i> ... ])<br></dd>
+</dl>
+<i>body</i> - a series of LISP forms (expressions) that are executed in order.<br>
+returns - the function <i>symbol</i></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'defun' special form defines a new function or re-defines an
+exisiting function. The last form in 'body' that is evaluated is the value
+that is returned when the function is executed.</p>
+
+<p>All of the 'argN' formal arguments that are defined are required to
+appear in a call to the defined function.</p>
+
+<p>If there are any <a href="lambda-keyword-optional.htm">&optional</a>
+arguments defined, they will be filled in order.</p>
+
+<p>If there is a <a href="lambda-keyword-rest.htm">&rest</a> argument
+defined, and all the required formal arguments and
+<a href="lambda-keyword-optional.htm">&optional</a> arguments are filled, any
+and all further parameters will be passed into the function via the 'rarg'
+argument. <b>Note</b> that there can be only one 'rarg' argument for
+<a href="lambda-keyword-rest.htm">&rest</a>.</p>
+
+<p>If there are insufficient parameters for any of the
+<a href="lambda-keyword-optional.htm">&optional</a> or
+<a href="lambda-keyword-rest.htm">&rest</a> arguments, they will contain
+<a href="nil.htm">NIL</a>.</p>
+
+<p>The <a href="lambda-keyword-aux.htm">&aux</a> variables are a mechanism
+for you to define variables local to the function definition. At the end of
+the function execution, these local symbols and their values are are
+removed.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun my-add <font color="#008844">; define function MY-ADD</font>
+ (num1 num2) <font color="#008844">; with 2 formal parameters</font>
+ (+ num1 num2)) <font color="#008844">; that adds the two paramters</font>
+
+(my-add 1 2) <font color="#008844">; returns 3</font>
+
+(defun foo <font color="#008844">; define function FOO</font>
+ (a b &optional c d &rest e) <font color="#008844">; with some of each argument</font>
+ (print a) (print b)
+ (print c) (print d) <font color="#008844">; print out each</font>
+ (print e))
+
+(foo) <font color="#008844">; error: too few arguments</font>
+(foo 1) <font color="#008844">; error: too few arguments</font>
+(foo 1 2) <font color="#008844">; prints 1 2 NIL NIL NIL</font>
+(foo 1 2 3) <font color="#008844">; prints 1 2 3 NIL NIL</font>
+(foo 1 2 3 4) <font color="#008844">; prints 1 2 3 4 NIL</font>
+(foo 1 2 3 4 5) <font color="#008844">; prints 1 2 3 4 (5)</font>
+(foo 1 2 3 4 5 6 7 8 9) <font color="#008844">; prints 1 2 3 4 (5 6 7 8 9)</font>
+
+(defun my-add <font color="#008844">; define function MY-ADD</font>
+ (num1 &rest num-list &aux sum) <font color="#008844">; with 1 arg, rest, 1 aux var</font>
+ (setq sum num1) <font color="#008844">; clear SUM</font>
+ (dotimes (i (length num-list) ) <font color="#008844">; loop through rest list</font>
+ (setq sum (+ sum (car num-list))) <font color="#008844">; add the number to sum</font>
+ (setq num-list (cdr num-list))) <font color="#008844">; and remove num from list</font>
+ sum) <font color="#008844">; return sum when finished</font>
+
+(my-add 1 2 3 4) <font color="#008844">; returns 10</font>
+(my-add 5 5 5 5 5) <font color="#008844">; returns 25</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp supports an optional documentation
+string as the first form in the 'body' of a
+<a href="defmacro.htm">defmacro</a> or 'defun'. XLISP will accept this
+string as a valid form, but it will not do anything special with it.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-013.htm#defun">defun</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/delete-if-not.htm b/docsrc/xlisp/xlisp-doc/reference/delete-if-not.htm new file mode 100644 index 0000000..7aed3a8 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/delete-if-not.htm @@ -0,0 +1,107 @@ +<html><head><title>XLISP delete-if-not</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>delete-if-not</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(delete-if-not <i>test list</i>)</dt>
+<dd><i>test</i> - the test function to be performed<br>
+<i>list</i> - the list to delete from<br>
+returns - the list with non-matching elements deleted</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'delete-if-not' function destructively modifies the 'list' by
+removing the elements of the list that fail the 'test'. The destructive
+aspect of this operation means that the actual symbol value is used in the
+list-modifying operations, not a copy.</p>
+
+<p>'list' must evaluate to a valid list. An atom for 'list' will result in
+an error:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument type</font>
+</pre>
+
+<p>Having <a href="nil.htm">NIL</a> for 'list' will return a
+<a href="nil.htm">NIL</a> as the result.</p>
+
+<h2>Examples</h2>
+
+<p><b>Caution:</b> there's a bug:</p>
+
+<pre class="example">
+(setq mylist '(1 2 3 4 5 6 7 8)) <font color="#008844">; set up a list of numbers</font>
+(delete-if-not 'evenp mylist) <font color="#008844">; returns (2 4 6 8)</font>
+(print mylist) <font color="#008844">; prints (1 2 4 6 8)</font> <font color="#AA0000"><-BUG!</font>
+
+(setq mylist '(1 2 3 4 5 6 7 8)) <font color="#008844">; set up the same list again</font>
+(setq mylist (delete-if-not 'evenp mylist)) <font color="#008844">; returns (3 5 7)</font>
+(print mylist) <font color="#008844">; prints (3 5 7)</font> <font color="#009900"><-OK</font>
+
+(setq mylist '(1 2 3 4 5 6 7 8)) <font color="#008844">; ... again ...</font>
+(delete-if-not 'oddp mylist) <font color="#008844">; returns (1 3 5 7)</font>
+(print mylist) <font color="#008844">; prints (1 3 5 7)</font> <font color="#009900"><-OK</font>
+
+(setq mylist '(1 2 3 4 5 6 7 8)) <font color="#008844">; ... and again ...</font>
+(setq mylist (delete-if-not 'oddp mylist)) <font color="#008844">; returns (1 3 5 7)</font>
+(print mylist) <font color="#008844">; prints (1 3 5 7)</font> <font color="#009900"><-OK</font>
+</pre>
+
+<p><b>Bug:</b> 'delete-if-not' will return the proper value, but it does not
+always properly modify the symbol containing the value. This seems to be
+true if the first element of the 'list' fails the test [and should be
+deleted]. It's always better to use 'delete-if-not' together with
+<a href="setq.htm">setq</a> or
+<a href="setf.htm">setf</a> as shown in <nobr>example 2</nobr>
+<nobr>and 4.</nobr></p>
+
+<p><b>Common Lisp:</b> XLISP does not support the ':from-end', ':start',
+':end', ':count' and ':key' keywords which Common Lisp does.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-017.htm#delete-if-not">delete-if-not</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/delete-if.htm b/docsrc/xlisp/xlisp-doc/reference/delete-if.htm new file mode 100644 index 0000000..f0d0a1d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/delete-if.htm @@ -0,0 +1,110 @@ +<html><head><title>XLISP delete-if</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>delete-if</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(delete-if <i>test list</i>)</dt>
+<dd><i>test</i> - the test function to be performed<br>
+<i>list</i> - the list to delete from<br>
+returns - the list with matching elements deleted</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'delete-if' function destructively modifies the 'list' by removing
+the elements of the list that pass the 'test'. The destructive aspect of
+this operation means that the actual symbol value is used in the
+list-modifying operations, not a copy.</p>
+
+<p>'list' must evaluate to a valid list. An atom for 'list' will result in
+an error:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument type</font>
+</pre>
+
+<p>Having <a href="nil.htm">NIL</a> for 'list' will return a
+<a href="nil.htm">NIL</a> as the result.</p>
+
+<h2>Examples</h2>
+
+<p><b>Caution:</b> there's a bug:</p>
+
+<pre class="example">
+(setq mylist '(1 2 3 4 5 6 7 8)) <font color="#008844">; set up a list starting of numbers</font>
+(delete-if 'oddp mylist) <font color="#008844">; returns (2 4 6)</font>
+(print mylist) <font color="#008844">; prints (1 2 4 6)</font> <font color="#AA0000"><-BUG!</font>
+
+(setq mylist '(1 2 3 4 5 6 7 8)) <font color="#008844">; set up the same list again</font>
+(setq mylist (delete-if 'oddp mylist)) <font color="#008844">; returns (2 4 6)</font>
+(print mylist) <font color="#008844">; prints (2 4 6)</font> <font color="#009900"><-OK</font>
+
+(setq mylist '(1 2 3 4 5 6 7 8)) <font color="#008844">; ... again ...</font>
+(delete-if 'evenp mylist) <font color="#008844">; returns (1 3 5 7)</font>
+(print mylist) <font color="#008844">; prints (1 3 5 7)</font> <font color="#009900"><-OK</font>
+
+(setq mylist '(1 2 3 4 5 6 7 8)) <font color="#008844">; ... and again ...</font>
+(setq mylist (delete-if 'evenp mylist)) <font color="#008844">; returns (1 3 5 7)</font>
+(print mylist) <font color="#008844">; prints (1 3 5 7)</font> <font color="#009900"><-OK</font>
+</pre>
+
+<p><b>Bug:</b> 'delete-if' will return the proper value, but it does not
+always properly modify the symbol containing the value. This seems to be
+true if the first element of the 'list' passes the test [and should be
+deleted]. It's always better to use 'delete-if' together with
+<a href="setq.htm">setq</a> or
+<a href="setf.htm">setf</a> as shown in <nobr>example 2</nobr>
+<nobr>and 4.</nobr></p>
+
+<p><b>Note:</b> This bug can be reproduced with Nyquist 2.36 [in June 2007],
+so please take care.</p>
+
+<p><b>Common Lisp:</b> XLISP does not support the ':from-end', ':start',
+':end', ':count' and ':key' keywords which Common LISP does.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-017.htm#delete-if">delete-if</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/delete.htm b/docsrc/xlisp/xlisp-doc/reference/delete.htm new file mode 100644 index 0000000..71baf5d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/delete.htm @@ -0,0 +1,99 @@ +<html><head><title>XLISP delete</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>delete</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(delete <i>expr list</i> [{:test | :test-not} <i>test</i>])</dt>
+<dd><i>expr</i> - the expression to delete from <i>list</i><br>
+<i>list</i> - the list to destructively modify<br>
+<i>test</i> - optional test function (default is <a href="eql.htm">eql</a>)<br>
+returns - the list with the matching expressions deleted</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'delete' function destructively modifies the 'list' by removing the
+'expr'. The destructive aspect of this operation means that the actual
+symbol value is used in the list-modifying operations, not a copy. If 'expr'
+appears multiple times in the 'list', all occurances will be removed.</p>
+
+<p>'list' must evaluate to a valid list. An atom for 'list' will result in
+an error:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument type</font>
+</pre>
+
+<p>Having <a href="nil.htm">NIL</a> for 'list' will return a
+<a href="nil.htm">NIL</a> as the result. You may specify your own
+test with the ':test' and ':test-not' keywords.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(delete 'b NIL) <font color="#008844">; returns NIL</font>
+(delete 'b '(a b b c b)) <font color="#008844">; returns (A C)</font>
+(setq a '(1 2 3)) (setq b a) <font color="#008844">; set up A and B</font>
+(delete '2 a) <font color="#008844">; returns (1 3)</font>
+(print a) <font color="#008844">; prints (1 3) A IS MODIFIED!</font>
+(print b) <font color="#008844">; prints (1 3) B IS MODIFIED!</font>
+(delete '(b) '((a)(b)(c))) <font color="#008844">; returns ((A) (B) (C))</font>
+ <font color="#008844">; EQL doesn't work on lists</font>
+(delete '(b) '((a)(b)(c)) :test 'equal) <font color="#008844">; returns ((A) (C))</font>
+</pre>
+
+<p><b>Note:</b> The 'delete' function can work with a list or string as the
+'expr'. However, the default <a href="eql.htm">eql</a> test does
+not work with lists or strings, only symbols and numbers. To make this work,
+you need to use the ':test' keyword along with
+<a href="equal.htm">equal</a> for 'test'.</p>
+
+<p><b>Common Lisp:</b> XLISP does not support the ':from-end', ':start',
+':end', ':count' and ':key' keywords which Common Lisp does.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-017.htm#delete">delete</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/digit-char-p.htm b/docsrc/xlisp/xlisp-doc/reference/digit-char-p.htm new file mode 100644 index 0000000..99930d2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/digit-char-p.htm @@ -0,0 +1,87 @@ +<html><head><title>XLISP digit-char-p</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>digit-char-p</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(digit-char-p <i>char</i>)</dt>
+<dd><i>char</i> - a character expression<br>
+returns - the digit weight if character is a digit,
+<a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'digit-char-p' predicate function checks if the 'char' expression is
+a numeric digit. If 'char' is numeric digit, the equivalent integer value
+is returned, otherwise a <a href="nil.htm">NIL</a> is
+returned. Decimal digits are '0' [ASCII decimal <nobr>value 48]</nobr>
+through '9' [ASCII decimal <nobr>value 57].</nobr></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(digit-char-p #\0) <font color="#008844">; returns 0</font>
+(digit-char-p #\9) <font color="#008844">; returns 9</font>
+(digit-char-p #\A) <font color="#008844">; returns NIL</font>
+(digit-char-p #\a) <font color="#008844">; returns NIL</font>
+(digit-char-p #\.) <font color="#008844">; returns NIL</font>
+(digit-char-p #\-) <font color="#008844">; returns NIL</font>
+(digit-char-p #\+) <font color="#008844">; returns NIL</font>
+</pre>
+
+<p><b>Note:</b> Other non-digit characters used in numbers are NOT included:
+plus [+], minus [-], exponent <nobr>[e or E]</nobr> and decimal point
+[.].</p>
+
+<p><b>Common Lisp:</b> Common Lisp supports the use of an optional radix
+parameter. This option specifies numeric base. This allows the
+'digit-char-p' to function properly for hexadecimal digits [for example].
+Common LISP supports up to base 36 radix systems. XLISP does not support
+this radix parameter.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-026.htm#digit-char-p">digit-char-p</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/digit-char.htm b/docsrc/xlisp/xlisp-doc/reference/digit-char.htm new file mode 100644 index 0000000..5d40c74 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/digit-char.htm @@ -0,0 +1,79 @@ +<html><head><title>XLISP digit-char</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>digit-char</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(digit-char <i>int</i>)</dt>
+<dd><i>int</i> - an integer expression<br>
+returns - the digit character or <a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'digit-char' function takes an integer expression 'int' and converts
+it into a decimal digit character. So, an integer value of '0' produces the
+character '#\0'. An integer value of '1' produces the character '#\1' and so
+on. If a valid character can be produce it is returned, otherwise a
+<a href="nil.htm">NIL</a> is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(digit-char 0) <font color="#008844">; returns #\0</font>
+(digit-char 9) <font color="#008844">; returns #\9</font>
+(digit-char 10) <font color="#008844">; returns NIL</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp supports the use of an optional radix
+parameter. This option specifies numeric base. This allows the 'digit-char'
+to function properly for hexadecimal digits [for example]. Common Lisp
+supports up to <nobr>base 36</nobr> radix systems. XLISP does not support
+this radix parameter. Common Lisp also supports a font parameter which XLISP
+does not.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-026.htm#digit-char">digit-char</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/division.htm b/docsrc/xlisp/xlisp-doc/reference/division.htm new file mode 100644 index 0000000..2fae40c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/division.htm @@ -0,0 +1,101 @@ +<html><head><title>XLISP /</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>/</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(/ <i>expr1</i> ...)</nobr></dt>
+<dd><i>exprN</i> - integer or floating point number/expression<br>
+returns - the result of the division</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The '/' function divides the first number given by the rest of the
+numbers and returns the result. If all the expressions are integers, the
+division is integer division. If any expression is a floating point number,
+then the division will be floating point division.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(/ 1) => 1
+(/ 1 2) => 0 <font color="#008844">; integer division</font>
+(float (/ 1 2)) => 0 <font color="#008844">; integer division</font>
+(/ (float 1) 2) => 0.5 <font color="#008844">; type contagion</font>
+(/ 1 1.0 2) => 0.5 <font color="#008844">; type contagion</font>
+(/ (float 1) 2 3) => 0.166667 <font color="#008844">; type contagion</font>
+(/ 1 1.0 2 3 4) => 0.0416667 <font color="#008844">; type contagion</font>
+</pre>
+
+<pre class="example">
+> (print (+ 1 2 (* 3.5 (/ 3.9 1.45))))
+12.4138
+12.4138
+</pre>
+
+<p>See <a href="addition.htm"> + </a>,
+<a href="multiplication.htm"> * </a>,
+<a href="float.htm">float</a>, <a href="print.htm">print</a>.
+XLISP first prints the value on the screen, the second number is the
+return value.</p>
+
+<p>In XLISP, the type contagion depends on the order of
+occurrence:</p>
+
+<pre class="example">
+(/ 1 2 1.0) => 0 <font color="#008844">; because (/ 1 2) => 0 and (/ 0 1.0) => 0.0</font>
+(/ 1.0 2 1) => 0.5 <font color="#008844">; because (/ 1.0 2) => 0.5 and (/ 0.5 1) => 0.5</font>
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/do-star.htm b/docsrc/xlisp/xlisp-doc/reference/do-star.htm new file mode 100644 index 0000000..7ff4415 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/do-star.htm @@ -0,0 +1,144 @@ +<html><head><title>XLISP do*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>do*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(do* ([<i>binding</i> ... ]) (<i>test-expr</i> [<i>result</i>]) [<i>expr</i> ... ])</dt>
+<dd><i>binding</i> - a variable binding which is can take one of the following forms:<br>
+<dl><dd><i>symbol</i><br>
+(<i>symbol init-expr</i> [<i>step-expr</i>])
+<dl><dd><i>symbol</i> - a symbol<br>
+<i>init-expr</i> - an initialization expression for <i>symbol</i><br>
+<i>step-expr</i> - an expression with that <i>symbol</i> is updated
+at the end of each loop</dd></dl></dd></dl>
+<i>test-expr</i> - iteration ends when this expression returns a
+non-<a href="nil.htm">NIL</a> value<br>
+<i>result</i> - an optional expression for the returned result<br>
+<i>expr</i> - expressions comprising the body of the loop which may
+contain <a href="return.htm">return</a>s,
+<a href="go.htm">go</a>s or tags for
+<a href="go.htm">go</a><br>
+returns - the value of the last result expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p> The 'do*' special form is basically a 'while' looping construct that
+contains symbols [with optional initializations and updates], a loop test
+[with an optional return value] and a block of code [expressions] to
+evaluate. The 'do*' form evaluates its initializations and updates in
+sequential order [as opposed to <a href="do.htm">do</a> which
+doesn't]. The sequence of these events is:</p>
+
+<pre>
+ <i>init-expr</i> execution
+ while <i>test-expr</i> do
+ loop code execution
+ <i>step-expr</i> execution
+ end-while
+ return <i>result</i>
+</pre>
+
+<p>The first form after the 'do*' is the 'binding' form. It contains a
+series of 'symbols' or 'bindings'. The 'binding' is a 'symbol' followed by
+an initialization expression 'init-expr' and an optional 'step-expr'. If
+there is no 'init-expr', the 'symbol' will be initialized to
+<a href="nil.htm">NIL</a>. There is no specification as to the
+order of execution of the bindings or the step expressions, except that they
+happen all together.</p>
+
+<p> The 'do*' form will go through and create and initialize the symbols.
+This is followed by evaluating the 'test-expr'. If 'test-expr' returns a
+non-<a href="nil.htm">NIL</a> value, the loop will terminate. If
+'test-expr' returns a <a href="nil.htm">NIL</a> value then the
+'do*' will sequentially execute the 'exprs'. After execution of the loop
+'exprs', the 'symbols' are set to the step-exprs' [if the 'step-exprs'
+exist]. Then, the 'test-expr' is re-evaluated, and so on. The value of the
+'result' expression is evaluated and returned. If no 'result' is specified,
+<a href="nil.htm">NIL</a> is returned. When the 'do*' is finished
+execution, the 'symbols' that were defined will no longer exist or retain
+their values.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(do <font color="#008844">; DO example - won't work</font>
+ ((i 0) <font color="#008844">; var I=0</font>
+ (j i)) <font color="#008844">; var J=I (won't work)</font>
+ ((eql i j) "done") <font color="#008844">; test and result</font>
+ (print "looping")) <font color="#008844">; error: unbound variable - I</font>
+
+(do* <font color="#008844">; DO* example - will work</font>
+ ((i 0) <font color="#008844">; var I=0</font>
+ (j i)) <font color="#008844">; var J=I (proper exec. order)</font>
+ ((eql i j) "done") <font color="#008844">; test and result</font>
+ (print "looping")) <font color="#008844">; returns "done"</font>
+
+(do* (i) <font color="#008844">; DO* loop with var I</font>
+ ((eql i 0) "done") <font color="#008844">; test and result</font>
+ (print i) (setq i 0) (print i)) <font color="#008844">; prints NIL 0</font>
+ <font color="#008844">; returns "done"</font>
+
+(do* (i) <font color="#008844">; DO* loop with var I</font>
+ ((eql i 0)) <font color="#008844">; test but no result</font>
+ (print i) (setq i 0) (print i)) <font color="#008844">; prints NIL 0</font>
+ <font color="#008844">; returns NIL</font>
+
+(do* <font color="#008844">; DO* loop</font>
+ ((i 0 (setq i (1+ i))) <font color="#008844">; var I=0 increment by 1</font>
+ (j 10 (setq j (1- j)))) <font color="#008844">; var J=10 decrement by 1</font>
+ ((eql i j) "met in the middle") <font color="#008844">; test and result</font>
+ (princ i) (princ " ") <font color="#008844">; prints 0 10</font>
+ (princ j) (terpri)) <font color="#008844">; 1 9</font>
+ <font color="#008844">; 2 8</font>
+ <font color="#008844">; 3 7</font>
+ <font color="#008844">; 4 6</font>
+ <font color="#008844">; returns "met in the middle"</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-020.htm#do*">do*</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/do.htm b/docsrc/xlisp/xlisp-doc/reference/do.htm new file mode 100644 index 0000000..7b1258b --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/do.htm @@ -0,0 +1,133 @@ +<html><head><title>XLISP do</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>do</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(do ([<i>binding</i> ... ]) (<i>test-expr</i> [<i>result</i>]) [<i>expr</i> ... ])</dt>
+<dd><i>binding</i> - a variable binding which is can take one of the following forms:<br>
+<dl><dd><i>symbol</i><br>
+(<i>symbol init-expr</i> [<i>step-expr</i>])
+<dl><dd><i>symbol</i> - a symbol<br>
+<i>init-expr</i> - an initialization expression for <i>symbol</i><br>
+<i>step-expr</i> - an expression with that <i>symbol</i> is updated
+at the end of each loop</dd></dl></dd></dl>
+<i>test-expr</i> - iteration ends when this expression returns a
+non-<a href="nil.htm">NIL</a> value<br>
+<i>result</i> - an optional expression for the returned result<br>
+<i>expr</i> - expressions comprising the body of the loop which may
+contain <a href="return.htm">return</a>s,
+<a href="go.htm">go</a>s or tags for
+<a href="go.htm">go</a><br>
+returns - the value of the last result expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'do' special form is basically a 'while' looping construct that
+contains symbols [with optional initializations and updates], a loop test
+[with an optional return value] and a block of code [expressions] to
+evaluate. The 'do' form evaluates its initializations and updates in no
+specified order [as opposed to <a href="do-star.htm">do*</a> which
+does it in sequential order]. The sequence of these events is:</p>
+
+<pre>
+ <i>init-expr</i> execution
+ while not <i>test-expr</i> do
+ loop code execution
+ <i>step-expr</i> execution
+ end-while
+ return <i>result</i>
+</pre>
+
+
+<p> The first form after the 'do' is the 'binding' form. It contains a
+series of 'symbols' or 'bindings'. The 'binding' is a 'symbol' followed by
+an initialization expression 'init-expr' and an optional 'step-expr'. If
+there is no 'init-expr', the 'symbol' will be initialized to
+<a href="nil.htm">NIL</a>. There is no specification as to the
+order of execution of the bindings or the step expressions, except that
+they happen all together.</p>
+
+<p>The 'do' form will go through and create and initialize the symbols.
+This is followed by evaluating the 'test-expr'. If 'test-expr' returns a
+non-<a href="nil.htm">NIL</a> value, the loop will terminate.
+If 'test-expr' returns a <a href="nil.htm">NIL</a> value then
+the 'do' will sequentially execute the 'exprs'. After execution of the loop
+'exprs', the 'symbols' are set to the 'step-exprs' [if the 'step-exprs'
+exist]. Then, the 'test-expr' is re-evaluated, and so on. The value of the
+'result' expression is evaluated and returned. If no 'result' is specified,
+<a href="nil.htm">NIL</a> is returned. When the 'do' is finished
+execution, the 'symbol's that were defined will no longer exist or retain
+their values.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(do (i) <font color="#008844">; DO loop with var I</font>
+ ((eql i 0) "done") <font color="#008844">; test and result</font>
+ (print i) (setq i 0) (print i)) <font color="#008844">; prints NIL 0</font>
+ <font color="#008844">; returns "done"</font>
+
+(do (i) <font color="#008844">; DO loop with var I</font>
+ ((eql i 0)) <font color="#008844">; test but no result</font>
+ (print i) (setq i 0) (print i)) <font color="#008844">; prints NIL 0</font>
+ <font color="#008844">; returns NIL</font>
+
+(do <font color="#008844">; DO loop</font>
+ ((i 0 (setq i (1+ i))) <font color="#008844">; var I=0 increment by 1</font>
+ (j 10 (setq j (1- j)))) <font color="#008844">; var J=10 decrement by 1</font>
+ ((eql i j) "met in the middle") <font color="#008844">; test and result</font>
+ (princ i) (princ " ") <font color="#008844">; prints 0 10</font>
+ (princ j) (terpri)) <font color="#008844">; 1 9</font>
+ <font color="#008844">; 2 8</font>
+ <font color="#008844">; 3 7</font>
+ <font color="#008844">; 4 6</font>
+ <font color="#008844">; returns "met in the middle"</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-020.htm#do">do</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/dolist.htm b/docsrc/xlisp/xlisp-doc/reference/dolist.htm new file mode 100644 index 0000000..ab6c637 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/dolist.htm @@ -0,0 +1,111 @@ +<html><head><title>XLISP dolist</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>dolist</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(dolist (<i>symbol list-expr</i> [<i>result</i>]) [<i>expr</i> ... ])</dt>
+<dd><i>symbol</i> - a symbol<br>
+<i>list-expr</i> - a list expression<br>
+<i>result</i> - an optional expression for the returned result<br>
+<i>expr</i> - expressions comprising the body of the loop which may
+contain <a href="return.htm">return</a>s,
+<a href="go.htm">go</a>s or tags for
+<a href="go.htm">go</a><br>
+returns - the return value of the result expression or
+<a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p> The 'dolist' special form is basically a list-oriented 'for' looping
+construct that contains a loop 'symbol', a 'list-expr' to draw values from,
+an optional 'return' value and a block of code [expressions] to evaluate.
+The sequence of execution is:</p>
+
+<pre>
+ <i>symbol</i> := CAR of <i>list-expr</i>
+ temp-list := CDR of <i>list-expr</i>
+ while temp-list is not empty
+ loop code execution
+ <i>symbol</i> := CAR of temp-list
+ temp-list := CDR of temp-list
+ end-while
+ return <i>result</i>
+</pre>
+
+<p>The main loop 'symbol' will take on successive values from 'list-expr'.
+The 'dolist' form will go through and create and initialize the 'symbol'.
+After execution of the loop 'exprs', the 'symbol' is set to the next value
+in the 'list-expr'. This continues until the 'list-expr' has been exhausted.
+The value of the 'result' expression is evaluated and returned. If no
+'result' is specified, <a href="nil.htm">NIL</a> is returned.
+When the 'dolist' is finished execution, the 'symbol' that was defined will
+no longer exist or retain its value. If the 'list-expr' is an empty list,
+then no loop execution takes place and the 'result' is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+ (dolist (i () "done") <font color="#008844">; DOLIST with I loop variable</font>
+ (print "here")) <font color="#008844">; an empty list</font>
+ <font color="#008844">; and a return value</font>
+ <font color="#008844">; returns "done"</font>
+
+ (dolist (x '(a b c) "fini") <font color="#008844">; DOLIST with X loop variable</font>
+ (princ x)) <font color="#008844">; a list with (A B C)</font>
+ <font color="#008844">; and a return value</font>
+ <font color="#008844">; prints ABC returns "fini"</font>
+
+ (dolist (y '(1 2 3)) <font color="#008844">; DOLIST with Y loop variable</font>
+ (princ (* y y))) <font color="#008844">; a list with (1 2 3)</font>
+ <font color="#008844">; and no return value</font>
+ <font color="#008844">; prints 149 returns NIL</font>
+ <font color="#008844">; returns "met in the middle"</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-020.htm#dolist">dolist</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/dotimes.htm b/docsrc/xlisp/xlisp-doc/reference/dotimes.htm new file mode 100644 index 0000000..bcbaf82 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/dotimes.htm @@ -0,0 +1,101 @@ +<html><head><title>XLISP dotimes</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>dotimes</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(dotimes (<i>symbol end-expr</i> [<i>result</i>]) [<i>expr</i> ... ])</dt>
+<dd><i>symbol</i> - a symbol<br>
+<i>end-expr</i> - an integer expression<br>
+<i>result</i> - an optional expression for the returned result<br>
+<i>expr</i> - expressions comprising the body of the loop which may
+contain <a href="return.htm">return</a>s,
+<a href="go.htm">go</a>s or tags for
+<a href="go.htm">go</a><br>
+returns - the return value of the result expression or
+<a href="nil.htm">NIL</a> </dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'dotimes' special form is basically a 'for' looping construct that
+contains a loop 'symbol', an 'end-expr' to specify the final value for
+'symbol', an optional 'return' value and a block of code [expressions] to
+evaluate. The sequence of execution is:</p>
+
+
+<pre>
+ <i>symbol</i> := 0
+ while <i>symbol</i> value is not equal to <i>end-expr</i> value
+ loop code execution
+ <i>symbol</i> := <i>symbol</i> + 1
+ end-while
+ return <i>result</i>
+</pre>
+
+<p>The main loop 'symbol' will take on successive values from zero to
+<nobr>('end-expr' - 1).</nobr> The 'dotimes' form will go through and create
+and initialize the 'symbol' to zero. After execution of the loop 'exprs',
+the 'symbol' value is incremented. This continues until the 'symbol' value
+is equal to 'end-expr'. The value of the 'result' expression is evaluated
+and returned. If no 'result' is specified,
+<a href="nil.htm">NIL</a> is returned. When the 'dotimes' is
+finished execution, the 'symbol' that was defined will no longer exist or
+retain its value. If the 'end-expr' is zero or less, then there will be no
+execution of the loop body's code.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(dotimes (i 4 "done") (princ i)) <font color="#008844">; prints 0123 returns "done"</font>
+(dotimes (i 4) (princ i)) <font color="#008844">; prints 0123 returns NIL</font>
+(dotimes (i 1) (princ i)) <font color="#008844">; prints 0 returns NIL</font>
+(dotimes (i 0) (princ i)) <font color="#008844">; returns NIL</font>
+(dotimes (i -9) (princ i)) <font color="#008844">; returns NIL</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-020.htm#dotimes">dotimes</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/dribble.htm b/docsrc/xlisp/xlisp-doc/reference/dribble.htm new file mode 100644 index 0000000..4fd0252 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/dribble.htm @@ -0,0 +1,82 @@ +<html><head><title>XLISP dribble</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>dribble</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlisp.c, xlsys.c, msstuff.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(dribble [<i>file-str</i>])</dt>
+<dd><i>file-str</i> - a string expression for a file name<br>
+returns - <a href="t.htm"> T </a> if the transcript
+is opened, <a href="nil.htm">NIL</a> if it is closed</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'dribble' function, when called with a 'file-str' argument, opens the
+specified file and records a transcript of the XLISP session. When 'dribble'
+is called with no 'file-str' argument, it closes the current transcript file
+[if any]. 'dribble' will return
+<a href="t.htm"> T </a> if the specified 'file-str'
+was successfully opened. It will return a
+<a href="nil.htm">NIL</a> if the 'file-str' was not opened
+successfully or if 'dribble' was evaluated to close a transcript.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(dribble "my-trans-file") <font color="#008844">; open file "my-trans-file"</font>
+ <font color="#008844">; for a session transcript</font>
+(+ 2 2)
+(dribble) <font color="#008844">; close the transcript</font>
+</pre>
+
+<p><b>Note:</b> It is also possible to start a transcript when invoking
+XLISP. To start XLISP with a transcript file of 'myfile' type in
+<nobr>'xlisp -tmyfile'.</nobr> <nobr>[I haven't</nobr> tested this with
+Nyquist.]</p>
+
+<p>See the
+<a href="../manual/xlisp-man-031.htm#dribble">dribble</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/echoenabled.htm b/docsrc/xlisp/xlisp-doc/reference/echoenabled.htm new file mode 100644 index 0000000..08fa47e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/echoenabled.htm @@ -0,0 +1,68 @@ +<html><head><title>XLISP echoenabled</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>echoenabled</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>sys/unix/osstuff.c, sys/win/wingui/winguistuff.c, sys/win/msvc/winstuff.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(echoenabled <i>flag</i>)</dt>
+<dd><i>flag</i> - <a href="t.htm"> T </a> to enable echo, <a href="nil.htm">NIL</a> to disable<br>
+returns - <a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'echoenabled' function turns console input echoing on or off.</p>
+
+<p><b>Note:</b> The 'echoenabled' function is only implemented under Linux
+and <nobr>Mac OS X.</nobr> <nobr>If Nyquist</nobr> I/O is redirected through
+pipes, the Windows version does not echo the input, but the Linux and Mac
+<nobr>versions do</nobr>. <nobr>You can</nobr> turn off echoing with this
+function. Under windows it is defined to do nothing.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/endp.htm b/docsrc/xlisp/xlisp-doc/reference/endp.htm new file mode 100644 index 0000000..dd7587f --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/endp.htm @@ -0,0 +1,86 @@ +<html><head><title>XLISP endp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>endp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(endp <i>list</i>)</dt>
+<dd><i>list</i> - the list to check<br>
+returns - <a href="t.htm"> T </a> if the list is
+empty, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'endp' predicate function checks to see if 'list' is an empty list.
+<a href="t.htm"> T </a> is returned if the list is
+empty, <a href="nil.htm">NIL</a> is returned if the list is
+not empty. The 'list' has to be a valid list. An error is returned if it
+is not a list:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument type</font>
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(endp '()) <font color="#008844">; returns T - empty list</font>
+(endp ()) <font color="#008844">; returns T - still empty</font>
+(endp '(a b c)) <font color="#008844">; returns NIL</font>
+(setq a NIL) <font color="#008844">; set up a variable</font>
+(endp a) <font color="#008844">; returns T - value = empty list</font>
+(endp "a") <font color="#008844">; error: bad argument type - "a"</font>
+(endp 'a) <font color="#008844">; error: bad argument type - A</font>
+</pre>
+
+<p><b>Note:</b> The 'endp' predicate is different from the
+<a href="null.htm">null</a> and
+<a href="not.htm">not</a> predicates in that it requires a
+valid list.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#endp">endp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/eq.htm b/docsrc/xlisp/xlisp-doc/reference/eq.htm new file mode 100644 index 0000000..48253ea --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/eq.htm @@ -0,0 +1,93 @@ +<html><head><title>XLISP eq</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>eq</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c, xlsubr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>eq</b> <i>expr1 expr2</i>)</dt>
+<dd><i>exprN</i> - arbitrary Lisp expressions<br>
+returns - <a href="t.htm"> T </a> if the expressions
+eveluate to the same internal value, <a href="nil.htm">NIL</a>
+otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>Two expressions are 'eq' if the expressions are identical. <nobr>The 'eq'
+function</nobr> tests if the results of the evaluated expressions point to
+the same memory location. <a href="t.htm"> T </a> is returned if
+both expressions evaluate to exactly the same internal value,
+<a href="nil.htm">NIL</a> is returned otherwise.</p>
+
+<p>Integer numbers being <a href="number-equal.htm"> = </a> are
+'eq' as long as not stored in a CPU register, so the
+<a href="eql.htm">eql</a> function is recommended for testing integers. Also
+note that arrays, <nobr>floating-point</nobr> numbers, lists, and strings
+are only 'eq' if they are bound as variable values to the same symbol.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(eq 'a 'a) => T
+(eq 1 1) => T or NIL
+(eq 1 1.0) => NIL
+(eq 1.0 1.0) => NIL
+(eq "a" "a") => NIL
+(eq '(a b) '(a b)) => NIL
+(eq 'a 34) => NIL
+
+(setq a '(a b)) <font color="#008844">; set value of A to (A B)</font>
+(setq b a) <font color="#008844">; set B to point to A's value</font>
+(setq c '(a b)) <font color="#008844">; set value of C to different (A B)</font>
+(eq a b) => T
+(eq a c) => NIL
+</pre>
+
+<p>See also <a href="eql.htm">eql</a>, <a href="equal.htm">equal</a>,
+<nobr><a href="../examples/common-lisp/equalp.htm">cl:equalp</a></nobr>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/eql.htm b/docsrc/xlisp/xlisp-doc/reference/eql.htm new file mode 100644 index 0000000..8be4067 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/eql.htm @@ -0,0 +1,99 @@ +<html><head><title>XLISP eql</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>eql</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c, xlsubr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(eql expr1 expr2)</dt>
+<dd><i>expr1</i> - the first expression to compare<br>
+<i>expr2</i> - the second expression to compare<br>
+returns - <a href="t.htm"> T </a> if the expressions have the
+same symbolic or numerical value, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>Two expressions are 'eql':</p>
+
+<ul>
+
+<li><p>If the expressions <nobr>are <a href="eq.htm">eq</a></nobr>.</p></li>
+
+<li><p>If two numbers of the same type
+<nobr>are <a href="number-equal.htm"> = </a></nobr>.</p></li>
+
+<li><p>If two characters
+<nobr>are <a href="char-equal-s.htm">char=</a></nobr>.</p></li>
+
+</ul>
+
+<p>In all other cases 'eql' <nobr>returns <a href="nil.htm">NIL</a></nobr>.
+Note that arrays, lists, and strings are only 'eql' if they
+<nobr>are <a href="eq.htm">eq</a></nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(eql 'a 'a) => T
+(eql 1 1) => T
+(eql 1 1.0) => NIL
+(eql 1.0 1.0) => T
+(eql "a" "a") => NIL
+(eql '(a b) '(a b)) => NIL
+(eql 'a 34) => NIL
+
+(setq a '(a b)) <font color="#008844">; set value of A to (A B)</font>
+(setq b a) <font color="#008844">; set B to point to A's value</font>
+(setq c '(a b)) <font color="#008844">; set value of C to different (A B)</font>
+(eql a b) => T
+(eql a c) => NIL
+</pre>
+
+<p>See also <a href="eq.htm">eq</a>, <a href="equal.htm">equal</a>,
+<nobr><a href="../examples/common-lisp/equalp.htm">cl:equalp</a></nobr>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/equal.htm b/docsrc/xlisp/xlisp-doc/reference/equal.htm new file mode 100644 index 0000000..8eceaad --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/equal.htm @@ -0,0 +1,111 @@ +<html><head><title>XLISP equal</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>equal</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c, xlsubr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>equal</b> <i>expr1 expr2</i>)</dt>
+<dd><i>exprN</i> - arbitrary Lisp expressions<br>
+returns - <a href="t.htm"> T </a> if the expressions
+are structurally equivalent, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>Two expressions <nobr>are 'equal'</nobr>:</p>
+
+<ul>
+
+<li><p>If the expressions
+<nobr>are <a href="eql.htm">eql</a></nobr>.</p></li>
+
+<li><p>If two strings
+<nobr>are <a href="string-equal-s.htm.htm">string=</a></nobr>.</p></li>
+
+<li><p>If the two <a href="../reference/car.htm">car</a>s in conses are
+'equal' and the two <a href="../reference/cdr.htm">cdr</a>s in
+conses <nobr>are 'equal'</nobr>.</p></li>
+
+</ul>
+
+<p>In all other cases 'equal'
+<nobr>returns <a href="nil.htm">NIL</a></nobr>. Note that arrays are only
+'equal' if they <nobr>are <a href="eq.htm">eq</a></nobr>.</p>
+
+<p>A way to view 'equal' is that if 'expr1' and 'expr2' were printed
+<nobr>[via <a href="print.htm">print</a></nobr> <nobr>or
+<a href="princ.htm">princ</a>]</nobr> <nobr>and they</nobr> look the same,
+then 'equal' will <nobr>return <a href="t.htm"> T </a></nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(equal 'a 'a) => T
+(equal 1 1) => T
+(equal 1 1.0) => NIL <font color="#008844">; different number types</font>
+(equal 1.0 1.0) => T
+(equal "a" "a") => T
+(equal '(a b) '(a b)) => T
+(equal 'a 34) => NIL
+
+(setq a '(a b)) <font color="#008844">; set value of A to (A B)</font>
+(setq b a) <font color="#008844">; set B to point to A's value</font>
+(setq c '(a b)) <font color="#008844">; set value of C to different (A B)</font>
+(equal a b) => T
+(equal a c) => T
+
+(equal '(a b) '(A B)) => T
+(equal '(a b) '(c d)) => NIL
+
+(equal "a" "A") => NIL
+(equal "abc" "abcD") => NIL
+</pre>
+
+<p>See also <a href="eq.htm">eq</a>, <a href="eql.htm">eql</a>,
+<nobr><a href="../examples/common-lisp/equalp.htm">cl:equalp</a></nobr>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/error.htm b/docsrc/xlisp/xlisp-doc/reference/error.htm new file mode 100644 index 0000000..c96b663 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/error.htm @@ -0,0 +1,161 @@ +<html><head><title>XLISP error</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>error, cerror</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c, xldbug.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>error</b> <i>err-msg</i> [<i>arg</i>])</dt>
+<dd><i>err-msg</i> - a string expression for the error message<br>
+<i>arg</i> - an optional argument expression, printed after the error message<br>
+returns - never returns</dd>
+</dl>
+
+<dl>
+<dt>(<b>cerror</b> <i>cont-msg err-msg</i> [<i>arg</i>])</dt>
+<dd><i>cont-msg</i> - a string expression for the <a href="continue.htm">continue</a> message<br>
+<i>err-msg</i> - a string expression for the error message<br>
+<i>arg</i> - an optional argument expression, printed after the error message<br>
+returns - <a href="nil.htm">NIL</a> when continued from the
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr></dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'error' function allows the generation of a
+<nobr>non-correctable</nobr> error. <nobr>A non-correctable</nobr> error
+requires evaluation of a <nobr><a href="clean-up.htm">clean-up</a></nobr> or
+<nobr><a href="top-level.htm">top-level</a></nobr> function from within the
+XLISP <nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr>
+to return to normal execution. <nobr>The form</nobr> of the message
+generated is:</p>
+
+<pre class="example">
+<font color="#AA0000">error:</font> <font color="#0000CC">err-msg</font> <font color="#AA0000">-</font> <font color="#0000CC">arg</font>
+</pre>
+
+<p>If a <a href="continue.htm">continue</a> function is evaluated within the
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr>, then a
+an error message is generated:</p>
+
+<pre class="example">
+<font color="#AA0000">error: this error can't be continued</font>
+</pre>
+
+<p>There is no return from the 'error' function.</p>
+
+<p>The 'cerror' function allows the generation of a correctable error.
+<nobr>A correctable</nobr> error can be corrected by some action
+within the XLISP <nobr><a href="../manual/xlisp.htm#break-loop">Break
+Loop</a></nobr>. <nobr>The form</nobr> of the message generated is:</p>
+
+<pre class="example">
+<font color="#AA0000">error:</font> <font color="#0000CC">err-msg</font> <font color="#AA0000">-</font> <font color="#0000CC">arg</font>
+<font color="#AA0000">if continued:</font> <font color="#0000CC">cont-msg</font>
+</pre>
+
+<p>In the
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr>,
+forms can be evaluated to correct the error. <nobr>If a</nobr>
+<a href="continue.htm">continue</a> function is evaluated within the
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr>, then
+<a href="nil.htm">NIL</a> is returned from 'cerror'. <nobr>If desired</nobr>, the
+<nobr><a href="clean-up.htm">clean-up</a></nobr> and
+<nobr><a href="top-level.htm">top-level</a></nobr> forms may be evaluated
+to abort out of the
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr>.</p>
+
+<p><div class="box">
+
+<p><b>Note:</b> The <a href="global-breakenable.htm">*breakenable*</a>
+variable needs to be <nobr>non-<a href="nil.htm">NIL</a></nobr> for 'error',
+'cerror' and system errors to be caught by the Nyquist/XLISP
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr>.</p>
+
+</div></p>
+
+<h2>Examples</h2>
+
+<p>Example of a <nobr>non-correctable</nobr> error:</p>
+
+<pre class="example">
+> (error "invalid argument" "arg")
+<font color="#AA0000">error: invalid argument - "arg"</font>
+
+1> (continue) <font color="#008844">; the 1 before the > indicates a break loop</font>
+<font color="#AA0000">error: this error can't be continued</font>
+
+1> (clean-up)
+[ back to previous break level ]
+
+> <font color="#008844">; no break loop any longer</font>
+</pre>
+
+<p>Example of system generated correctable error:</p>
+
+<pre class="example">
+> (symbol-value 'f)
+<font color="#AA0000">error: unbound variable - F</font>
+<font color="#AA0000">if continued: try evaluating symbol again</font>
+
+1> (setq f 123) <font color="#008844">; the 1 before the > indicates a break loop</font>
+123 <font color="#008844">; return value of (setq f 123)</font>
+
+1> (continue)
+123 <font color="#008844">; return value of (symbol-value 'f)</font>
+
+> <font color="#008844">; no break loop any longer</font>
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#debugging-and-error-handling">Debugging and Error Handling</a></nobr></li>
+<li><nobr>XLISP 2.0 Manual → <a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr></li>
+<li><nobr>Tutorials → Nyquist → <a href="../tutorials/nyquist.htm#debugger-shortcuts">Debugger Shortcuts</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/errset.htm b/docsrc/xlisp/xlisp-doc/reference/errset.htm new file mode 100644 index 0000000..b2094c8 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/errset.htm @@ -0,0 +1,117 @@ +<html><head><title>XLISP errset</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>errset</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(errset <i>expr</i> [<i>print-flag</i>])</dt>
+<dd><i>expr</i> - an expression to be evaluated<br>
+<i>print-flag</i> - an optional expression
+[<a href="nil.htm">NIL</a> or
+non-<a href="nil.htm">NIL</a>]<br>
+returns - the value of the last expression
+<a href="cons.htm">cons</a>ed with
+<nobr><a href="nil.htm">NIL</a> ,</nobr> or
+<a href="nil.htm">NIL</a> on error</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'errset' special form is a mechanism that allows the trapping of
+errors within the execution of 'expr'.
+<a href="global-breakenable.htm">*breakenable*</a> must be set to
+<a href="nil.htm">NIL</a> for the 'errset' form to function. If
+<a href="global-breakenable.htm">*breakenable*</a> is
+<nobr>non-<a href="nil.htm">NIL</a> ,</nobr> the normal break
+loop will handle the error. For 'errset', if no error occurs within 'expr',
+the value of the last expression is <a href="cons.htm">cons</a>ed
+with <a href="nil.htm">NIL</a>. If an error occurs within 'expr',
+the error is caught by 'errset' and a <a href="nil.htm">NIL</a>
+is returned from 'errset'. If 'print-flag' is
+<nobr><a href="nil.htm">NIL</a> ,</nobr> the error message
+normally generated by 'expr' will not be printed. If 'print-flag' is
+non-<a href="nil.htm">NIL</a> or not present in the 'errset'
+form, the error message will be printed.</p>
+
+<p>Errors from <a href="error.htm">error</a> and
+<a href="cerror.htm">cerror</a> and system errors
+will be handled by 'errset'. Note that the
+<a href="cerror.htm">cerror</a> message will only include
+the error message portion, not the
+<a href="continue.htm">continue</a> message portion.
+<a href="break.htm">break</a> is not intercepted by 'errset'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq *breakenable* nil) <font color="#008844">; do not enter the break-loop on errors</font>
+(errset (error "hi" "ho")) <font color="#008844">; prints error: hi - "ho" returns NIL</font>
+(errset (cerror "hi" "ho" "he")) <font color="#008844">; prints error: ho - "he" returns NIL</font>
+(errset (error "hey" "ho") NIL) <font color="#008844">; returns NIL</font>
+(errset (break "hey")) <font color="#008844">; break: hey - if continued: return from BREAK</font>
+(continue) <font color="#008844">; [ continue from break loop ]</font>
+(errset (+ 1 5)) <font color="#008844">; returns (6)</font>
+(errset (+ 1 "a") NIL) <font color="#008844">; returns NIL</font>
+(setq *breakenable* t) <font color="#008844">; re-enable the break-loop on errors</font>
+</pre>
+
+<p>How to keep XLISP from signalling an error:</p>
+
+<pre class="example">
+(setq *breakenable* nil)
+(errset <font color="#0000CC">expression-causing-an-error</font> t) <font color="#008844">; print the error message</font>
+(errset <font color="#0000CC">expression-causing-an-error</font>) <font color="#008844">; do NOT print the error message</font>
+</pre>
+
+<p><b>Note:</b> Be sure to set
+<a href="global-breakenable.htm">*breakenable*</a> to
+<a href="nil.htm">NIL</a> before using 'errset' and to
+non-<a href="nil.htm">NIL</a> after using 'errset'. <nobr>If you</nobr> don't
+reset <nobr><a href="global-breakenable.htm">*breakenable*</a> ,</nobr> no
+errors will be reported.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-022.htm#errset">errset</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/eval.htm b/docsrc/xlisp/xlisp-doc/reference/eval.htm new file mode 100644 index 0000000..9a5c69f --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/eval.htm @@ -0,0 +1,79 @@ +<html><head><title>XLISP eval</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>eval</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c, xleval.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(eval <i>expression</i>)</dt>
+<dd><i>expression</i> - an arbitrary expression<br>
+returns - the result of evaluating the expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'eval' function evaluates the 'expression' and returns the resulting
+value.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(eval '(+ 2 2)) <font color="#008844">; returns 4</font>
+(eval (cons '+ '(2 2 2))) <font color="#008844">; returns 6</font>
+(eval (list '+ '2 '3 )) <font color="#008844">; returns 5</font>
+
+(setq a 10) <font color="#008844">; set up A with value 10</font>
+(setq b 220) <font color="#008844">; set up B with value 220</font>
+
+(eval (list '+ a b )) <font color="#008844">; returns 230 because</font>
+ <font color="#008844">; (list '+ a b) => '(+ 10 220)</font>
+
+(eval (list '+ 'a b)) <font color="#008844">; returns 230 because</font>
+ <font color="#008844">; (list '+ 'a b) => '(+ A 220)</font>
+ <font color="#008844">; and A has the value 10</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-012.htm#eval">eval</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/evalhook.htm b/docsrc/xlisp/xlisp-doc/reference/evalhook.htm new file mode 100644 index 0000000..86588d0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/evalhook.htm @@ -0,0 +1,142 @@ +<html><head><title>XLISP evalhook</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>evalhook</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c, xleval.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(evalhook<i> expr eval-expr apply-expr</i> [<i>env</i>])</dt>
+<dd><i>expr</i> - an expression to evaluate<br>
+<i>eval-expr</i> - an expression for the evaluation routine<br>
+<i>apply-expr</i> - an expression for
+<a href="apply.htm">apply</a> [not used]<br>
+<i>env</i> - an environment expression, default is
+<a href="nil.htm">NIL</a><br>
+returns - the result of evaluating the expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'evalhook' function is a function that performs evaluation.
+The routine specified by 'eval-expr' is called with the 'expr' and 'env'
+parameters. If 'eval-expr' is
+<nobr><a href="nil.htm">NIL</a> ,</nobr> then the normal system
+evaluator is called. The 'apply-hook' is a dummy parameter that is not used
+in the current XLISP system. The 'expr' contains the expression to be
+evaluated. If the 'env' argument to 'evalhook' is not specified,
+<a href="nil.htm">NIL</a> is used, which specifies to use the
+current global environment. The 'env', if specified, is a structure composed
+of dotted pairs constructed of the symbol and its value which have the
+form:</p>
+
+<pre class="example">
+(((<font color="#008844"><i>sym1</i></font> . <font color="#008844"><i>val1</i></font>) (<font color="#008844"><i>sym2</i></font> . <font color="#008844"><i>val2</i></font>) ... )))
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq a 100) <font color="#008844">; set up global values</font>
+(setq b 200)
+
+(evalhook '(+ a b) NIL NIL) <font color="#008844">; returns 300 - no 'env' was given</font>
+
+(evalhook '(+ a b) NIL NIL <font color="#008844">; eval with a=1 and b=2</font>
+ '((((a . 1)(b . 2))))) <font color="#008844">; returns 3</font>
+
+(defun myeval (exp env) <font color="#008844">; define MYEVAL routine</font>
+ (princ "exp: ") (print exp)
+ (princ "env: ") (print env)
+ (evalhook exp #'myeval NIL env))
+
+(defun foo (a) (+ a a)) <font color="#008844">; create simple function</font>
+(setq *evalhook* #'myeval) <font color="#008844">; and install MYEVAL as hook</font>
+
+(foo 1) <font color="#008844">; prints exp: (FOO 1) env:NIL</font>
+ <font color="#008844">; exp: 1 env:NIL</font>
+ <font color="#008844">; exp: (+ A A) env:((((A . 1))))</font>
+ <font color="#008844">; exp: A env:((((A . 1))))</font>
+ <font color="#008844">; exp: A env:((((A . 1))))</font>
+ <font color="#008844">; returns 2</font>
+
+(top-level) <font color="#008844">; to clean up *evalhook*</font>
+</pre>
+
+<p><b>Note:</b> The 'evalhook' function and
+<a href="global-evalhook.htm">*evalhook*</a> system variable are very useful
+in the construction of debugging facilities within XLISP. The
+<a href="trace.htm">trace</a> and
+<a href="untrace.htm">untrace</a> functions use 'evalhook' and
+<a href="global-evalhook.htm">*evalhook*</a> to implement their
+functionality. The other useful aspect of 'evalhook' and
+<a href="global-evalhook.htm">*evalhook*</a> is to help in understanding
+how XLISP works to see the expressions, their environment and how they
+are evaluated.</p>
+
+<p><b>Caution:</b> Be careful when using
+<a href="global-evalhook.htm">*evalhook*</a> and 'evalhook'.
+If you put in a bad definition into
+<nobr><a href="global-evalhook.htm">*evalhook*</a> ,</nobr> you might not
+be able to do anything and will need to exit XLISP.</p>
+
+<p><b>Unusual behaviour:</b> The 'evalhook' function and
+<a href="global-evalhook.htm">*evalhook*</a> system variable, by their
+nature, cause some unusual things to happen. After you have set
+<a href="global-evalhook.htm">*evalhook*</a> to some
+non-<a href="nil.htm">NIL</a> value, your function will be
+called. However, when you are all done and set
+<a href="global-evalhook.htm">*evalhook*</a> to
+<a href="nil.htm">NIL</a> or some other new routine, it will
+never be set. This is because the 'xevalhook' function [in the 'xlbfun.c'
+source file] saves the old value of
+<a href="global-evalhook.htm">*evalhook*</a> before calling your routine,
+and then restores it after the evaluation. The mechanism to reset
+<a href="global-evalhook.htm">*evalhook*</a> is to execute the
+<a href="top-level.htm">top-level</a> function, which sets
+<a href="global-evalhook.htm">*evalhook*</a> to
+<a href="nil.htm">NIL</a>.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-022.htm#evalhook">evalhook</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/evenp.htm b/docsrc/xlisp/xlisp-doc/reference/evenp.htm new file mode 100644 index 0000000..3f85fd7 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/evenp.htm @@ -0,0 +1,92 @@ +<html><head><title>XLISP evenp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>evenp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(evenp <i>expr</i>)</dt>
+<dd><i>expr</i> - the integer numeric expression to check<br>
+returns - <a href="t.htm"> T </a> if the integer
+is even, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'evenp' predicate function checks to see if the number 'expr' is
+even. <a href="t.htm"> T </a> is returned if the
+number is even, <a href="nil.htm">NIL</a> is returned
+otherwise.</p>
+
+<p>An error is generated if the 'expr' is not a numeric expression:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument type</font>
+</pre>
+
+<p>An error is generated if the 'expr' is a floating point number:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad floating point operation</font>
+</pre>
+
+<p>Zero is an even number.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(evenp 0) <font color="#008844">; returns T</font>
+(evenp 1) <font color="#008844">; returns NIL</font>
+(evenp 2) <font color="#008844">; returns T</font>
+(evenp -1) <font color="#008844">; returns NIL</font>
+(evenp -2) <font color="#008844">; returns T</font>
+(evenp 14.0) <font color="#008844">; error: bad floating point operation</font>
+(evenp 'a) <font color="#008844">; error: bad argument type</font>
+(setq a 2) <font color="#008844">; set value of A to 2</font>
+(evenp a) <font color="#008844">; returns T</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#evenp">evenp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/exit.htm b/docsrc/xlisp/xlisp-doc/reference/exit.htm new file mode 100644 index 0000000..a6a4124 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/exit.htm @@ -0,0 +1,69 @@ +<html><head><title>XLISP exit</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>exit</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlsys.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(exit)</dt>
+<dd>returns - never returns</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'exit' function causes the current XLISP session to be terminated.
+<nobr>It never</nobr> returns.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(exit) <font color="#008844">; never returns</font>
+</pre>
+
+<p><b>Note:</b> When XLISP is exited, any
+<a href="dribble.htm">dribble</a> transcript file is automatically
+closed. However, other open files are not closed, and so may lose some
+information.</p>
+
+<p>See also <a href="quit.htm">quit</a>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/exp.htm b/docsrc/xlisp/xlisp-doc/reference/exp.htm new file mode 100644 index 0000000..8a56f40 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/exp.htm @@ -0,0 +1,76 @@ +<html><head><title>XLISP exp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>exp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(exp <i>power</i>)</dt>
+<dd><i>power</i> - floating point number/expression<br>
+returns - e to the x power</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p> The 'exp' function calculates e [2.7128] raised to the specified
+'power' and returns the result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(exp 0.0) <font color="#008844">; returns 1</font>
+(exp 1.0) <font color="#008844">; returns 2.71828 - e</font>
+(exp 2.0) <font color="#008844">; returns 7.38906</font>
+(exp 10.0) <font color="#008844">; returns 22026.5</font>
+(exp 0) <font color="#008844">; error: bad integer operation</font>
+</pre>
+
+<p><b>Note:</b> 'exp' with a large 'power' like 1000.0 causes an incorrect
+value to be generated, with no error. The returned value will be a very
+large floating point number near the computer's limit [something like
+1.79000e+308].</p>
+
+<p>See the
+<a href="../manual/xlisp-man-023.htm#exp">exp</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/expand.htm b/docsrc/xlisp/xlisp-doc/reference/expand.htm new file mode 100644 index 0000000..5ed5a28 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/expand.htm @@ -0,0 +1,91 @@ +<html><head><title>XLISP expand</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>expand</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlsys.c, xldmem.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(expand <i>segments</i>)</dt>
+<dd><i>segments</i> - the number of segments to add as an integer expression<br>
+returns - the number of segments added</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'expand' function expands memory by the specified number of
+'segments'. The number of 'segments' added is returned as the result. The
+power up default is 1000 nodes per segment. Note that
+<a href="alloc.htm">alloc</a> allows you to change the number of
+nodes per segment.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(room) <font color="#008844">; prints Nodes: 8000</font>
+ <font color="#008844">; Free nodes: 5622</font>
+ <font color="#008844">; Segments: 6</font>
+ <font color="#008844">; Allocate: 1000</font>
+ <font color="#008844">; Total: 92586</font>
+ <font color="#008844">; Collections: 8</font>
+ <font color="#008844">; returns NIL</font>
+
+(expand 2) <font color="#008844">; add more nodes</font>
+
+(room) <font color="#008844">; prints Nodes: 10000</font>
+ <font color="#008844">; Free nodes: 7608</font>
+ <font color="#008844">; Segments: 8</font>
+ <font color="#008844">; Allocate: 1000</font>
+ <font color="#008844">; Total: 112602</font>
+ <font color="#008844">; Collections: 8</font>
+ <font color="#008844">; returns NIL</font>
+</pre>
+
+<p><b>Note:</b> When <a href="gc.htm">gc</a> is called or an
+automatic garbage collection occurs, if the amount of free memory is still
+low after the garbage collection, the system attempts to add more segments
+[an automatic 'expand'].</p>
+
+<p>See the
+<a href="../manual/xlisp-man-031.htm#expand">expand</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/expt.htm b/docsrc/xlisp/xlisp-doc/reference/expt.htm new file mode 100644 index 0000000..7b9a4f6 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/expt.htm @@ -0,0 +1,79 @@ +<html><head><title>XLISP expt</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>expt</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(expt <i>expr</i> [<i>power</i> ... ])</dt>
+<dd><i>expr</i> - floating point number/expression<br>
+<i>power</i> - integer or floating point number/expression<br>
+returns - x to the y power</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'expt' function raises the 'expr' to the specified 'power' and
+returns the result. If there is no 'power' specified, the 'expr' is
+returned. If there are multiple 'powers', they will be applied sequentially
+to 'expr'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(expt 2.0 2) <font color="#008844">; returns 4</font>
+(expt 2.0 10) <font color="#008844">; returns 1024</font>
+(expt 2 2) <font color="#008844">; error: bad integer operation</font>
+(expt 99.9) <font color="#008844">; returns 99.9</font>
+(expt 2.0 2.0 2.0) <font color="#008844">; returns 16</font>
+</pre>
+
+<p><b>Note:</b> 'expt' with a large values like (expt 999.9 999.9) causes an
+incorrect value to be generated, with no error. The returned value will be a
+very large floating point number near the computer's limit [something like
+1.79000e+308].</p>
+
+<p>See the
+<a href="../manual/xlisp-man-023.htm#expt">expt</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/fboundp.htm b/docsrc/xlisp/xlisp-doc/reference/fboundp.htm new file mode 100644 index 0000000..cc014f8 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/fboundp.htm @@ -0,0 +1,84 @@ +<html><head><title>XLISP fboundp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>fboundp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(fboundp <i>symbol</i>)</dt>
+<dd><i>symbol</i> - the symbol expression to check for a value<br>
+returns - <a href="t.htm"> T </a> if a functional
+value is bound to the symbol, <a href="nil.htm">NIL</a>
+otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'fboundp' predicate function checks to see if 'symbol' is a symbol
+with a function definition bound to it.
+<a href="t.htm"> T </a> is returned if 'symbol' has a
+function value, <a href="nil.htm">NIL</a> is returned otherwise.
+Note that 'symbol' is a symbol expression, it is evaluated and the resulting
+expression is the one that is checked.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun foo (x) (print x)) <font color="#008844">; set up function FOO</font>
+(fboundp 'foo) <font color="#008844">; returns T - FOO is closure</font>
+(fboundp 'car) <font color="#008844">; returns T - CAR is subr</font>
+
+(setq myvar 'goo) <font color="#008844">; set up MYVAR to have value GOO</font>
+(fboundp myvar) <font color="#008844">; returns NIL - because GOO has no value yet</font>
+(defmacro goo () (print "hi")) <font color="#008844">; define GOO macro</font>
+(fboundp myvar) <font color="#008844">; returns T</font>
+
+(fboundp 'a) <font color="#008844">; returns NIL</font>
+(fboundp '1) <font color="#008844">; error: bad argument type - 1</font>
+(fboundp "hi") <font color="#008844">; error: bad argument type - "hi"</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#fboundp">fboundp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/filep.htm b/docsrc/xlisp/xlisp-doc/reference/filep.htm new file mode 100644 index 0000000..6db78bf --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/filep.htm @@ -0,0 +1,75 @@ +<html><head><title>XLISP filep</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>filep</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp function (closure)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>filep</b> <i>expr</i>)</nobr></dt>
+<dd><i>expr</i> - an Lisp expression<br>
+returns - <a href="t.htm"> T </a> if <i>expr</i> is of type FPTR,
+<a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<p>In Nyquist, 'filep' is implemented as a Lisp function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">filep</font> (x)
+ (eq (type-of x) 'FPTR))
+</pre>
+
+<h2>Description</h2>
+
+<p>The 'filep' function returns <a href="t.htm"> T </a> if
+'expr' is of type FPTR, <a href="nil.htm">NIL</a> otherwise</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/find-in-xlisp-path.htm b/docsrc/xlisp/xlisp-doc/reference/find-in-xlisp-path.htm new file mode 100644 index 0000000..ee671d1 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/find-in-xlisp-path.htm @@ -0,0 +1,66 @@ +<html><head><title>XLISP find-in-xlisp-path</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>find-in-xlisp-path</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>path.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(find-in-xlisp-path <i>filename</i>)</dt>
+<dd><i>filename</i> - the name of the file to search for as string<br>
+returns - a full path name to the first occurrence found</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The '<nobr>find-in-xlisp-path</nobr>' function searches the XLISP search
+path <nobr>[e.g. XLISPPATH</nobr> from the environment] for 'filename'.
+<nobr>If 'filename'</nobr> is not found as is, and there is no file
+extension, '.lsp' is appended to filename and searched again. <nobr>The
+current</nobr> directory is not searched.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/first.htm b/docsrc/xlisp/xlisp-doc/reference/first.htm new file mode 100644 index 0000000..054167a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/first.htm @@ -0,0 +1,74 @@ +<html><head><title>XLISP first</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>first</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(first <i>expr</i>)</dt>
+<dd><i>expr</i> - a list or list expression<br>
+returns - the first element of the expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'first' function returns the first element of the expression.
+If the first expression is itself a list, then the sublist is returned.
+If the list is <nobr><a href="nil.htm">NIL</a> ,</nobr>
+<a href="nil.htm">NIL</a> is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(first '(a b c)) <font color="#008844">; returns A</font>
+(first '((a b) c d)) <font color="#008844">; returns (A B)</font>
+(first NIL) <font color="#008844">; returns NIL</font>
+(first 'a) <font color="#008844">; error: bad argument type</font>
+(setq children '(amanda ben)) <font color="#008844">; set up variable CHILDREN</font>
+(first children) <font color="#008844">; returns AMANDA</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#first">first</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/flatc.htm b/docsrc/xlisp/xlisp-doc/reference/flatc.htm new file mode 100644 index 0000000..0bf8f87 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/flatc.htm @@ -0,0 +1,74 @@ +<html><head><title>XLISP flatc</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>flatc</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c, xlprin.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(flatc <i>expr</i>)</dt>
+<dd><i>expr</i> - an expression<br>
+returns - the length</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'flatc' function determines the character length that would be
+printed if the 'expr' were printed using
+<a href="princ.htm">princ</a>. This means that the 'expr' would be
+printed without a new-line. If 'expr' is a string, it would not be printed
+with quotes around the string. The print character length is returned as the
+result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(flatc 1234) <font color="#008844">; returns 4</font>
+(flatc '(a b c)) <font color="#008844">; returns 7</font>
+(flatc "abcd") <font color="#008844">; returns 4</font>
+(flatc 'mybigsymbol) <font color="#008844">; returns 11</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-027.htm#flatc">flatc</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/flatsize.htm b/docsrc/xlisp/xlisp-doc/reference/flatsize.htm new file mode 100644 index 0000000..57da49c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/flatsize.htm @@ -0,0 +1,74 @@ +<html><head><title>XLISP flatsize</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>flatsize</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c, xlprin.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(flatsize <i>expr</i>)</dt>
+<dd><i>expr</i> - an expression<br>
+returns - the length</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'flatsize' function determines the character length that would be
+printed if the 'expr' were printed using <a
+href="prin1.htm">prin1</a>. This means that the 'expr' would be
+printed without a new-line. If 'expr' is a string, it would be printed with
+quotes around the string. The print character length is returned as the
+result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(flatsize 1234) <font color="#008844">; returns 4</font>
+(flatsize '(a b c)) <font color="#008844">; returns 7</font>
+(flatsize "abcd") <font color="#008844">; returns 6</font>
+(flatsize 'mybigsymbol) <font color="#008844">; returns 11</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-027.htm#flatsize">flatsize</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/flet.htm b/docsrc/xlisp/xlisp-doc/reference/flet.htm new file mode 100644 index 0000000..aa5cc5d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/flet.htm @@ -0,0 +1,87 @@ +<html><head><title>XLISP flet</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>flet</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(flet ([<i>function</i> ... ]) <i>expr</i> ... )</dt>
+<dd><i>function</i> - a function definition binding which is of the form:
+<dl><dd>(<i>symbol arg-list body</i>)
+<dl><dd><i>symbol</i> - the symbol specifying the function name<br>
+<i>arg-list</i> - the argument list for the function <br>
+<i>body</i> - the body of the function</dd></dl></dd></dl>
+<i>expr</i> - an expression<br>
+returns - the value of the last expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'flet' special form is basically a local block construct that allows
+local 'function' definitions followed by a block of code to evaluate. The
+first form after the 'flet' is the 'binding' form. It contains a series of
+'functions'. The 'flet' form will go through and define the 'symbols' of the
+'functions' and then sequentially execute the 'exprs'. The value of the last
+'expr' evaluated is returned. When the 'flet' is finished execution, the
+'symbols' that were defined will no longer exist.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(flet ((fuzz (x) (+ x x))) <font color="#008844">; an FLET with FUZZ local function</font>
+ (fuzz 2)) <font color="#008844">; returns 4</font>
+ <font color="#008844">; FUZZ no longer exists</font>
+
+(fuzz 2) <font color="#008844">; error: unbound function - FUZZ</font>
+
+ <font color="#008844">; an empty flet</font>
+(flet () (print 'a)) <font color="#008844">; prints A</font>
+</pre>
+
+<p><b>Note:</b> 'flet' does not allow recursive definitions of functions.
+The <a href="labels.htm">labels</a> special form does allow this.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-019.htm#flet">flet</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/float.htm b/docsrc/xlisp/xlisp-doc/reference/float.htm new file mode 100644 index 0000000..b20c35d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/float.htm @@ -0,0 +1,71 @@ +<html><head><title>XLISP float</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>float</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(float <i>expr</i>)</dt>
+<dd><i>expr</i> - integer or floating point number/expression<br>
+returns - the result as a floating point number</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'float' function takes a numeric expression and returns the result
+as a floating point number.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(/ 1 2) <font color="#008844">; returns 0 (integer division)</font>
+(/ (float 1) 2) <font color="#008844">; returns 0.5</font>
+(float (/ 1 2)) <font color="#008844">; returns 0 (integer division)</font>
+(/ 1 2 3) <font color="#008844">; returns 0 (integer division)</font>
+(/ (float 1) 2 3) <font color="#008844">; returns 0.166667</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-023.htm#float">float</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/floatp.htm b/docsrc/xlisp/xlisp-doc/reference/floatp.htm new file mode 100644 index 0000000..ea4c1b8 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/floatp.htm @@ -0,0 +1,81 @@ +<html><head><title>XLISP floatp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>floatp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(floatp <i>expr</i>)</dt>
+<dd><i>expr</i> - the expression to check<br>
+returns - <a href="t.htm"> T </a> if the value is a
+floating point number, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'floatp' predicate function checks if an 'expr' is a floating point
+number. <a href="t.htm"> T </a> is returned if 'expr'
+is a floating point number, <a href="nil.htm">NIL</a> is returned
+otherwise.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(floatp 1.2) <font color="#008844">; returns T - float</font>
+(floatp '1.2) <font color="#008844">; returns T - still a float</font>
+(setq a 1.234)
+(floatp a) <font color="#008844">; returns T - evaluates to float</font>
+(floatp 0.0) <font color="#008844">; returns T - float zero</font>
+(floatp 0) <font color="#008844">; returns NIL - integer zero</font>
+(floatp 1) <font color="#008844">; returns NIL - integer</font>
+(floatp #x034) <font color="#008844">; returns NIL - integer readmacro</font>
+(floatp 'a) <font color="#008844">; returns NIL - symbol</font>
+(floatp #\a) <font color="#008844">; returns NIL - character</font>
+(floatp NIL) <font color="#008844">; returns NIL - NIL</font>
+(floatp #(0 1 2)) <font color="#008844">; returns NIL - array</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#floatp">floatp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/format.htm b/docsrc/xlisp/xlisp-doc/reference/format.htm new file mode 100644 index 0000000..8a8bdca --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/format.htm @@ -0,0 +1,161 @@ +<html><head><title>XLISP format</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>format</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(format destination format [expr1 ... ])</dt>
+<dd><i>destination</i> - a required destination [see below]<br>
+<i>format</i> - a format string<br>
+<i>exprN</i> - an expression<br>
+returns - output string if stream is
+<nobr><a href="nil.htm">NIL</a> ,</nobr>
+<a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<p>The 'destination' must be a file pointer, a stream,
+<a href="nil.htm">NIL</a> [to create a string] or
+<a href="t.htm"> T </a> [to print to
+<a href="global-standard-output.htm">*standard-output*</a>].</p>
+
+<h2>Description</h2>
+
+<p>The 'format' function prints the specified expressions [if any] to the
+specified 'destination' using the 'format' string to control the print
+format. If the 'destination' is
+<nobr><a href="nil.htm">NIL</a> ,</nobr> a string is created and
+returned with the contents of the 'format'. If the 'destination' is
+<nobr><a href="t.htm"> T </a> ,</nobr> the printing
+occurs to <a href="global-standard-output.htm">*standard-output*</a>. The 'format'
+function returns <nobr><a href="nil.htm">NIL</a> ,</nobr> if
+the 'destination' was non-<a href="nil.htm">NIL</a>. The 'format'
+string is a string [surrounded by double-quote characters]. This string
+contains ASCII text to be printed along with formatting directives
+[identified by a preceeding tilde '~' character]. The character following
+the tilde character is not case sensitive ['~a' and '~A' will function
+equivalently].</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(format T "Now is the time for") <font color="#008844">; prints Now is the time for</font>
+(format T "all ~A ~S to" 'good 'men) <font color="#008844">; prints all GOOD MEN to</font>
+(format T "come to the") <font color="#008844">; prints come to the</font>
+(format T "~A of their ~S" <font color="#008844">; prints aid of their "party"</font>
+ "aid" "party")
+(format *standard-ouput* "Hello there") <font color="#008844">; prints Hello there</font>
+(format nil "ho ho ~S" 'ho) <font color="#008844">; returns "ho ho HO"</font>
+(format T "this is ~%a break") <font color="#008844">; prints this is</font>
+ <font color="#008844">; a break</font>
+(format T "this is a long ~
+ string") <font color="#008844">; prints this is a long string</font>
+</pre>
+
+<p><b>Supported format directives:</b> The 'format' string in XLISP supports
+the following format directives:</p>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr><code>~A</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">ASCII, prints the 'expr'. If it is a string print it
+ without quotes. This is like the <a href="princ.htm">princ</a>
+ function.</td>
+</tr>
+<tr>
+ <td><nobr><font size="-2"> </font></nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code>~S</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">s-expr, prints the 'expr'. If it is a string print it
+ with quotes. This is like the <a href="prin1.htm">prin1</a>
+ function.</td>
+</tr>
+<tr>
+ <td><nobr><font size="-2"> </font></nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code>~%</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">prints a 'newline' control character.</td>
+</tr>
+<tr>
+ <td><nobr><font size="-2"> </font></nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code>~~</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">prints a single tilde '~' character.</td>
+</tr>
+<tr>
+ <td><nobr><font size="-2"> </font></nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code>~<newline></code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%">continue the 'format' string on the next line. This
+ signals a line break in the format. The 'format' function will ignore
+ all white-space [blanks, tabs, newlines]. This is useful when the
+ 'format' string is longer than a program line. Note that the 'newline'
+ character must immediately follow the tilde character.</td>
+</tr>
+</tbody></table></p>
+
+<p><b>Common Lisp:</b> The 'format' function in Common Lisp is quite
+impressive. It includes 26 different formatting directives. XLISP, as shown
+above, does not include most of these. The more difficult ones that you
+might encounter are the decimal, octal, hexidecimal, fixed-format
+floating-point and exponential floating-point. It is possible to print in
+octal and hexadecimal notation by setting
+<a href="global-integer-format.htm">*integer-format*</a>. It is possible to print
+in fixed format and exponential by setting
+<a href="global-float-format.htm">*float-format*</a>. However, neither of these
+system variables are supported in Common Lisp and neither gives control over
+field size.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-028.htm#format">format</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/fourth.htm b/docsrc/xlisp/xlisp-doc/reference/fourth.htm new file mode 100644 index 0000000..9cf0fbb --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/fourth.htm @@ -0,0 +1,79 @@ +<html><head><title>XLISP fourth</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>fourth</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(fourth <i>expr</i>)</dt>
+<dd><i>expr</i> - a list or list expression<br>
+returns - the fourth element of the list</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'fourth' function returns the fourth element of a list or list
+expression. If the list is
+<nobr><a href="nil.htm">NIL</a> ,</nobr>
+<a href="nil.htm">NIL</a> is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(fourth '(1 2 3 4 5)) <font color="#008844">; returns 4</font>
+(fourth NIL) <font color="#008844">; returns NIL</font>
+(setq kids '(junie vickie cindy chris)) <font color="#008844">; set up variable KIDS</font>
+(first kids) <font color="#008844">; returns JUNIE</font>
+(second kids) <font color="#008844">; returns VICKIE</font>
+(third kids) <font color="#008844">; returns CINDY</font>
+(fourth kids) <font color="#008844">; returns CHRIS</font>
+(rest kids) <font color="#008844">; returns (VICKIE CINDY CHRIS)</font>
+</pre>
+
+<p><b>Note:</b> This function is set to the same code as
+<a href="caaaar.htm">cadddr</a>.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#fourth">fourth</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/funcall.htm b/docsrc/xlisp/xlisp-doc/reference/funcall.htm new file mode 100644 index 0000000..6deefa3 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/funcall.htm @@ -0,0 +1,102 @@ +<html><head><title>XLISP funcall</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>funcall</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(funcall <i>function</i> [<i>arg1</i> ... ])</dt>
+<dd><i>function</i> - the function or symbol to be called<br>
+<i>argN</i> - an argument to be passed to <i>function</i><br>
+returns - the result of calling the function with the arguments</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'funcall' function calls a function with a series of arguments.
+It returns the result from calling the function with the arguments.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(funcall '+ 1 2 3 4) <font color="#008844">; returns 10</font>
+(funcall #'+ 1 2 3 4) <font color="#008844">; returns 10</font>
+(funcall '+ '1 '2 '3) <font color="#008844">; returns 6</font>
+
+(setq sys-add (function +)) <font color="#008844">; returns #<Subr-+: #22c32></font>
+(setq a 99)
+(funcall sys-add 1 a) <font color="#008844">; 100</font>
+(funcall sys-add 1 'a) <font color="#008844">; error: bad argument type</font>
+ <font color="#008844">; you can't add a symbol, only it's value</font>
+
+(setq a 2) <font color="#008844">; set A</font>
+(setq b 3) <font color="#008844">; and B values</font>
+(funcall (if (< a b) (function +) <font color="#008844">; 'function' can be computed</font>
+ (function -))
+ a b) <font color="#008844">; returns 5</font>
+
+(defun add-to-list (arg list) <font color="#008844">; add a list or an atom</font>
+ (funcall (if (atom arg) 'cons <font color="#008844">; to the front of a list</font>
+ 'append)
+ arg list))
+(add-to-list 'a '(b c)) <font color="#008844">; returns (A B C)</font>
+(add-to-list '(a b) '(b c)) <font color="#008844">; returns (A B B C)</font>
+</pre>
+
+<h2>Notes</h2>
+
+<p>In XLISP, a '<nobr>special form</nobr>' of type FSUBR is not a function.
+This means that 'funcall' only works with functions of type SUBR
+<nobr>[built-in</nobr> function] or CLOSURE [function defined by
+<a href="defun.htm">defun</a>, <a href="flet.htm">flet</a>,
+<a href="labels.htm">labels</a>, or <a href="lambda.htm">lambda</a>], but
+with special forms of <nobr>type FSUBR</nobr> a 'bad function' error is
+signalled. Here is an example how to work around this behaviour:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">funcall*</font> (function &rest args)
+ (if (eq (type-of function) 'fsubr)
+ (eval (cons function args))
+ (apply function args)))
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/function.htm b/docsrc/xlisp/xlisp-doc/reference/function.htm new file mode 100644 index 0000000..4e173fc --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/function.htm @@ -0,0 +1,87 @@ +<html><head><title>XLISP function</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>function</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(function <i>expr</i>)</dt>
+<dd><i>expr</i> - an expression that evaluates to a function<br>
+returns - the functional interpretation</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'function' special form returns the function definition of the
+'expr'. Execution of the 'expr' form does not occur. 'function' will operate
+on functions, special forms, lambda-expressions and macros.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(function car) <font color="#008844">; returns #<Subr-CAR: #23ac4></font>
+(function quote) <font color="#008844">; returns #<FSubr-QUOTE: #23d1c></font>
+#'quote <font color="#008844">; returns #<FSubr-QUOTE: #23d1c></font>
+(function 'cdr) <font color="#008844">; error: not a function</font>
+
+(defun foo (x) (+ x x)) <font color="#008844">; define FOO function</font>
+(function foo) <font color="#008844">; returns #<Closure-FOO: #2cfb6></font>
+
+(defmacro bar (x) (+ x x)) <font color="#008844">; define FOOMAC macro</font>
+(function bar) <font color="#008844">; returns #<Closure-BAR: #2ceee></font>
+
+(setq my 99) <font color="#008844">; define a variable MY</font>
+(function my) <font color="#008844">; error: unbound function</font>
+
+(defun my (x) (print x)) <font color="#008844">; define a function MY</font>
+(function my) <font color="#008844">; returns #<Closure-MY: #2cdd6></font>
+</pre>
+
+<p><b>Read macro:</b> XLISP supports the normal Lisp read macro of a hash
+and quote [#'] as a short-hand method of writing the 'function' special
+form.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-012.htm#function">function</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/gc.htm b/docsrc/xlisp/xlisp-doc/reference/gc.htm new file mode 100644 index 0000000..1761b81 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/gc.htm @@ -0,0 +1,74 @@ +<html><head><title>XLISP gc</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>gc</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xldmem.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(gc)</dt>
+<dd>returns - always returns <a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'gc' function starts a garbage collection of the unused memory of
+XLISP. <a href="nil.htm">NIL</a> is always returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(gc) <font color="#008844">; start a garbage collection right now</font>
+</pre>
+
+<p><b>Note:</b> The system will cause an automatic garbage collection if it
+runs out of free memory.</p>
+
+<p><b>Note:</b> When 'gc' is called or an automatic garbage collection
+occurs, if the amount of free memory is still low after the garbage
+collection, the system attempts to add more segments [an automatic
+<a href="expand.htm">expand</a>].</p>
+
+<p>See the
+<a href="../manual/xlisp-man-031.htm#gc">gc</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/gcd.htm b/docsrc/xlisp/xlisp-doc/reference/gcd.htm new file mode 100644 index 0000000..2dc7570 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/gcd.htm @@ -0,0 +1,75 @@ +<html><head><title>XLISP gcd</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>gcd</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(gcd [<i>int</i> ... ])</dt>
+<dd><i>int</i> - an integer expression<br>
+returns - the greatest common divisor</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'gcd' function returns the greatest common divisor of a series of
+integers. If no arguments are given, a zero is returned. If only one
+argument is given, the absolute value of the argument is returned. The
+successful result is always a positive integer.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(gcd 51 34) <font color="#008844">; returns 17</font>
+(gcd 99 66 22) <font color="#008844">; returns 11</font>
+(gcd -99 66 -33) <font color="#008844">; returns 33</font>
+(gcd -14) <font color="#008844">; returns 14</font>
+(gcd 0) <font color="#008844">; returns 0</font>
+(gcd) <font color="#008844">; returns 0</font>
+(gcd .2) <font color="#008844">; error: bad argument type - 0.2</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-023.htm#gcd">gcd</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/gensym.htm b/docsrc/xlisp/xlisp-doc/reference/gensym.htm new file mode 100644 index 0000000..93b05d2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/gensym.htm @@ -0,0 +1,89 @@ +<html><head><title>XLISP gensym</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>gensym</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(gensym [<i>tag</i>])</dt>
+<dd><i>tag</i> - an optional integer or string<br>
+returns - the new symbol</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'gensym' function generates and returns a symbol. The default symbol
+form is as a character 'G' followed by a number, 'Gn'. The default numbering
+starts at '1'. You can change what the generated symbol looks like. By
+calling 'gensym' with a string 'tag', the default string is set to the
+string parameter. If 'tag' is an integer number, the current number is
+set to the integer parameter.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(gensym) <font color="#008844">; first time => G1</font>
+(gensym 100) <font color="#008844">; returns G100</font>
+(gensym "MYGENSYM") <font color="#008844">; returns MYGENSYM101</font>
+(gensym 0) <font color="#008844">; returns MYGENSYM0</font>
+(gensym) <font color="#008844">; returns MYGENSYM1</font>
+(gensym "G") <font color="#008844">; \</font>
+(gensym 0) <font color="#008844">; / put it back to 'normal'</font>
+(gensym) <font color="#008844">; just like first time => G1</font>
+</pre>
+
+<p><b>Note:</b> It takes 2 calls to 'gensym' to set both portions of the
+'gensym' symbol.</p>
+
+<p><b>Note:</b> Although it is possible to call 'gensym' with numbers in the string
+like "AB1", this does generate an odd sequence. What will happen is you will
+get a sequence of symbols like:</p>
+
+<pre class="example">
+... AB18 AB19 AB110 AB111 ...
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-013.htm#gensym">gensym</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/get-env.htm b/docsrc/xlisp/xlisp-doc/reference/get-env.htm new file mode 100644 index 0000000..4511afa --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/get-env.htm @@ -0,0 +1,64 @@ +<html><head><title>XLISP get-env</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>get-env</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlsys.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(get-env <i>string</i>)</dt>
+<dd><i>string</i> - environment variable name as string<br>
+returns - the value of the environment variable as string,
+<nobr>or <a href="nil.htm">NIL</a></nobr></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The '<nobr>get-user</nobr>' function returns the value of an environment
+variable, or <a href="nil.htm">NIL</a> if no variable had been found.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/get-key.htm b/docsrc/xlisp/xlisp-doc/reference/get-key.htm new file mode 100644 index 0000000..b890899 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/get-key.htm @@ -0,0 +1,66 @@ +<html><head><title>XLISP get-key</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>get-key</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>sys/unix/osstuff.c, sys/mac/macfun.c, sys/win/msvc/winfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(get-key)</dt>
+<dd>returns - the decimal ASCII value of the key pressed</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'get-key' function gets a single key stroke from the keyboard [as
+opposed to an entire line, as <a href="">read</a> does].</p>
+
+<p><b>Note:</b> In Nyquist, this function is only defined to work on Unix
+systems [including Linux and <nobr>Mac OS X]</nobr>. <nobr>On
+Windows</nobr> systems, <a href="nil.htm">NIL</a> is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq mychar (get-key)) <font color="#008844"> ; get a character</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/get-lambda-expression.htm b/docsrc/xlisp/xlisp-doc/reference/get-lambda-expression.htm new file mode 100644 index 0000000..a3bc5bb --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/get-lambda-expression.htm @@ -0,0 +1,78 @@ +<html><head><title>XLISP get-lambda-expression</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>get-lambda-expression</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(get-lambda-expression <i>closure</i>)</dt>
+<dd><i>closure</i> - a closure object from a previously defined
+<a href="defun.htm">function</a> or
+<a href="defmacro.htm">macro</a><br>
+returns - the original lambda expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'get-lambda-expression' function takes the 'closure' object and
+returns a reconstruction of a
+<a href="lambda.htm">lambda</a> or
+<a href="defmacro.htm">macro</a> expression that defines the
+'closure'. The parameter must be a 'closure' expression.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun mine (a b) (print (+ a b))) <font color="#008844">; define MINE defun</font>
+(get-lambda-expression (function mine)) <font color="#008844">; returns (LAMBDA (A B) (PRINT (+ A B)))</font>
+
+(get-lambda-expression (lambda (a) (print a)) <font color="#008844">; returns (LAMBDA (A) (PRINT A))</font>
+
+(defmacro plus (n1 n2) `(+ ,n1 ,n2)) <font color="#008844">; define PLUS macro</font>
+(get-lambda-expression (function plus)) <font color="#008844">; returns (MACRO (N1 N2) (BACKQUOTE (+ (COMMA N1) (COMMA N2))))</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-012.htm#get-lambda-expression">get-lambda-expression</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/get-output-stream-list.htm b/docsrc/xlisp/xlisp-doc/reference/get-output-stream-list.htm new file mode 100644 index 0000000..94c0c6d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/get-output-stream-list.htm @@ -0,0 +1,75 @@ +<html><head><title>XLISP get-output-stream-list</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>get-output-stream-list</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(get-output-stream-list <i>stream</i>)</dt>
+<dd><i>stream</i> - an output stream expression<br>
+returns - the output so far as a list</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'get-output-stream-list' function empties the specified 'stream' and
+returns this data as a list. The output stream is emptied by this
+operation.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq out (make-string-output-stream)) <font color="#008844">; returns #<Unnamed-Stream: #...></font>
+
+(format out "123") <font color="#008844">; add some data to output stream</font>
+(get-output-stream-list out) <font color="#008844">; returns (#\1 #\2 #\3)</font>
+
+(format out "123") <font color="#008844">; add some data to output stream</font>
+(read out) <font color="#008844">; returns 123</font>
+(get-output-stream-list out) <font color="#008844">; returns NIL, the string was emptied by 'read'</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-030.htm#get-output-stream-list">get-output-stream-list</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/get-output-stream-string.htm b/docsrc/xlisp/xlisp-doc/reference/get-output-stream-string.htm new file mode 100644 index 0000000..4dbc02a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/get-output-stream-string.htm @@ -0,0 +1,80 @@ +<html><head><title>XLISP get-output-stream-string</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>get-output-stream-string</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(get-output-stream-string <i>stream</i>)</dt>
+<dd><i>stream</i> - an output stream expression<br>
+returns - the output so far as a string</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'get-output-stream-string' function empties the specified 'stream'
+and returns this data as a single string. The output stream is emptied by
+this operation.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq out (make-string-output-stream)) <font color="#008844">; returns #<Unnamed-Stream: #...></font>
+
+(format out "fee fi fo fum ") <font color="#008844">; \</font>
+(format out "I smell the blood of ") <font color="#008844">; fill up output stream</font>
+(format out "Elmer Fudd") <font color="#008844">; /</font>
+(get-output-stream-string out) <font color="#008844">; returns "fee fi fo fum I smell the blood of Elmer Fudd"</font>
+
+(format out "~%now what") <font color="#008844">; add more to output stream</font>
+(get-output-stream-string out) <font color="#008844">; returns "\nnow what"</font>
+(get-output-stream-string out) <font color="#008844">; returns ""</font>
+
+(format out "hello") <font color="#008844">; add more to output stream</font>
+(read out) <font color="#008844">; returns HELLO</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-030.htm#get-output-stream-string">get-output-stream-string</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/get-temp-path.htm b/docsrc/xlisp/xlisp-doc/reference/get-temp-path.htm new file mode 100644 index 0000000..eb015f9 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/get-temp-path.htm @@ -0,0 +1,68 @@ +<html><head><title>XLISP get-temp-path</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>get-temp-path</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>sys/unix/osstuff.c, sys/win/msvc/winfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(<b>get-temp-path</b>)</dt>
+<dd>returns - the resulting full path as a string</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The '<nobr>get-temp-path</nobr>' function tries to get a path where a
+temporary file can be created.</p>
+
+<p><b>Note:</b> Under Windows, the '<nobr>get-temp-path</nobr>' function is
+based on environment variables. <nobr>If XLISP</nobr> is running as a
+<nobr>sub-process</nobr> to Java, the environment may not exist, in which
+case the default result is the unfortunate choice
+'<nobr>c:\windows\</nobr>'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/get-user.htm b/docsrc/xlisp/xlisp-doc/reference/get-user.htm new file mode 100644 index 0000000..735a8e2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/get-user.htm @@ -0,0 +1,67 @@ +<html><head><title>XLISP get-user</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>get-user</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>sys/unix/osstuff.c, sys/win/msvc/winstuff.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(get-user)</dt>
+<dd>returns - a string naming the user, or "nyquist"</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The '<nobr>get-user</nobr>' function returns the current user name.
+<nobr>In Unix</nobr> systems [including <nobr>OS X</nobr> and Linux], this
+is the value of the USER environment variable. <nobr>In Windows</nobr>, this
+is currently just "nyquist", which is also returned if the
+environment variable cannot be accessed. This function is used to avoid the
+case of two users creating files of the same name in the same temp
+directory. </p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/get.htm b/docsrc/xlisp/xlisp-doc/reference/get.htm new file mode 100644 index 0000000..e8cc487 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/get.htm @@ -0,0 +1,97 @@ +<html><head><title>XLISP get</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>get</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(get <i>symbol property</i>)</dt>
+<dd><i>symbol</i> - the symbol with a property list<br>
+<i>property</i> - he property name being retrieved<br>
+returns - the property value or <a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'get' function returns the value of the'property' from the 'symbol'.
+If the 'property' does not exist, a <a href="nil.htm">NIL</a> is
+returned. The 'symbol' must be an existing symbol. The returned value may be
+a single value or a list.</p>
+
+<p>Property lists are lists attached to any user defined variables. The
+lists are in the form of:</p>
+
+<pre class="example">
+(<font color="#008844"><i>name1 value1 name2 value2</i></font> ... )
+</pre>
+
+<p>Any number of properties may be attached to a single variable.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq person 'bobby) <font color="#008844">; create a variable with a value</font>
+(putprop person 'boogie 'last-name) <font color="#008844">; add a LAST-NAME property</font>
+(putprop person 'disc-jockey 'job) <font color="#008844">; add a JOB property</font>
+
+(get person 'last-name) <font color="#008844">; retrieve LAST-NAME - boogie</font>
+(get person 'job) <font color="#008844">; retrieve JOB - disc-jockey</font>
+(get person 'height) <font color="#008844">; non-existant - returns NIL</font>
+
+(putprop person '(10 20 30) 'stats) <font color="#008844">; add STATS - a list</font>
+(get person 'stats) <font color="#008844">; retrieve STATS - (10 20 30)</font>
+</pre>
+
+<p><b>Note:</b> You can set a property to the value
+<a href="nil.htm">NIL</a>. However, this
+<a href="nil.htm">NIL</a> value is indistinguishable from the
+<a href="nil.htm">NIL</a> returned when a property does not
+exist.</p>
+
+<p><b>Common Lisp:</b> Common Lisp allows for an optional default value,
+which XLISP does not support.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-014.htm#get">get</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-applyhook.htm b/docsrc/xlisp/xlisp-doc/reference/global-applyhook.htm new file mode 100644 index 0000000..4bc2bbd --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-applyhook.htm @@ -0,0 +1,78 @@ +<html><head><title>XLISP *applyhook*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*applyhook*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlglob.c (not implemented)</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt> *applyhook*</dt>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p> *applyhook* is a system variable that exists and is initialized to
+<a href="nil.htm">NIL</a>. It is a hook that is intended to
+contain a user function that is to be called whenever a function is applied
+to a list of arguments. It is not, however, implemented in XLISP 2.0, it
+only exists as a dummy hook.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+*applyhook* => NIL
+</pre>
+
+<p>*applyhook* is often used to implement function stepping functionality in
+a debugger.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr><a href="../manual/contents.htm#symbols">Symbols</a></nobr></li>
+<li><nobr><a href="../manual/contents.htm#evaluation-functions">Evaluation Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-breakenable.htm b/docsrc/xlisp/xlisp-doc/reference/global-breakenable.htm new file mode 100644 index 0000000..9a22cf9 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-breakenable.htm @@ -0,0 +1,106 @@ +<html><head><title>XLISP *breakenable*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*breakenable*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xldbug.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<a href="setq.htm">setq</a> <b>*breakenable*</b> <i>boolean</i>)</dt>
+<dd><i>boolean</i> - a generalized boolean value<br>
+returns - <nobr>non-<a href="nil.htm">NIL</a></nobr> if errors shall be handled by the
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr>, or <a href="nil.htm">NIL</a> if not</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The *breakenable* system variable controls entry to the
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr> and
+the trapping of errors. <nobr>If *breakenable*</nobr> is set to
+<nobr><a href="nil.htm">NIL</a> ,</nobr> then no errors from the
+system or from the <a href="error.htm">error</a> or
+<a href="cerror.htm">cerror</a> functions will be trapped.
+<nobr>If *breakenable*</nobr> is <nobr>non-<a href="nil.htm">NIL</a></nobr>,
+the <nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr>
+will handle these errors. <nobr>The <a href="break.htm">break</a></nobr>
+function is not affected by *breakenable* and will always force entry to the
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr>.
+<nobr>If the</nobr> '<nobr>init.lsp</nobr>' initialization file sets
+*breakenable* to <nobr><a href="t.htm"> T </a></nobr>,
+errors will be trapped by the
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+> (defun foo (x) <font color="#008844">; define function FOO</font>
+ (+ x x))
+FOO
+
+> (setq *breakenable* NIL) <font color="#008844">; disable break loop</font>
+NIL
+
+> (foo "a")
+error: bad argument type <font color="#008844">; does NOT enter a break loop</font>
+
+> (setq *breakenable* T) <font color="#008844">; enable break loop</font>
+T
+
+> (foo "a")
+error: bad argument type
+
+1> <font color="#008844">; entered a break loop</font>
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#symbols">Symbols</a></nobr></li>
+<li><nobr>Contents → <a href="../manual/contents.htm#debugging-and-error-handling">Debugging and Error Handling</a></nobr></li>
+<li><nobr>XLISP 2.0 Manual → <a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr></li>
+<li><nobr>Tutorials → Nyquist → <a href="../tutorials/nyquist.htm#debugger-shortcuts">Debugger Shortcuts</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-debug-io.htm b/docsrc/xlisp/xlisp-doc/reference/global-debug-io.htm new file mode 100644 index 0000000..97edafd --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-debug-io.htm @@ -0,0 +1,72 @@ +<html><head><title>XLISP *debug-io*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*debug-io*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.c, xlio.c, xldbug.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dd>
+<dt>*debug-io*</dt>
+</dd>
+
+<h2>Description</h2>
+
+<p>*debug-io* is a system variable that contains a file pointer pointing to
+the stream where all debug input and output goes to and from. The default
+file for *debug-io* is the system standard error device, normally the
+keyboard and screen.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+*debug-io* <font color="#008844">; returns #<File-Stream...></font>
+</pre>
+
+<p><b>Note:</b>
+<nobr><a href="global-trace-output.htm">*trace-output*</a> ,</nobr>
+*debug-io* and <a href="global-error-output.htm">*error-output*</a> are normally
+all set to the same file stream 'stderr'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#debug-io">*debug-io*</a>
+system variable in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-error-output.htm b/docsrc/xlisp/xlisp-doc/reference/global-error-output.htm new file mode 100644 index 0000000..604e60d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-error-output.htm @@ -0,0 +1,71 @@ +<html><head><title>XLISP *error-output*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*error-output*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.c, xlio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *error-output*</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>*error-output* is a system variable that contains a file pointer that
+points to the file where all error output goes to. The default file for
+*error-output* is the system standard error device, normally the screen.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+*error-output* <font color="#008844">; returns #<File-Stream...></font>
+</pre>
+
+<p><b>Note:</b>
+<nobr><a href="global-trace-output.htm">*trace-output*</a> ,</nobr>
+<a href="global-debug-io.htm">*debug-io*</a> and *error-output* are normally
+all set to the same file stream 'stderr'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#error-output">*error-output*</a>
+system variable in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-evalhook.htm b/docsrc/xlisp/xlisp-doc/reference/global-evalhook.htm new file mode 100644 index 0000000..ad219d5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-evalhook.htm @@ -0,0 +1,123 @@ +<html><head><title>XLISP *evalhook*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*evalhook*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xleval.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *evalhook*</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>*evalhook* is a system variable whose value is user code that will
+intercept evaluations either through normal system evaluation or through
+calls to <a href="evalhook.htm">evalhook</a>. The default value for
+*evalhook* is <nobr><a href="nil.htm">NIL</a> ,</nobr> which
+specifies to use the built in system evaluator. If *evalhook* is
+<nobr>non-<a href="nil.htm">NIL</a> ,</nobr> the routine is
+called with expression and environment parameters. If the environment
+argument is <nobr><a href="nil.htm">NIL</a> ,</nobr> then the the
+current global environment is used. The environment, if
+<nobr>non-<a href="nil.htm">NIL</a> ,</nobr> is a structure
+composed of dotted pairs constructed of the symbol and its value which have
+the form:</p>
+
+<pre class="example">
+(((<font color="#008844"><i>sym1</i></font> . <font color="#008844"><i>val1</i></font>) (<font color="#008844"><i>sym2</i></font> . <font color="#008844"><i>val2</i></font>) ... )))
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun myeval (exp env) <font color="#008844">; define MYEVAL routine</font>
+ (princ "exp: ") (print exp)
+ (princ "env: ") (print env)
+ (evalhook exp #'myeval NIL env))
+
+(defun foo (a) (+ a a)) <font color="#008844">; create simple function</font>
+(setq *evalhook* #'myeval) <font color="#008844">; and install MYEVAL as hook</font>
+
+(foo 1) <font color="#008844">; prints exp: (FOO 1) env:NIL</font>
+ <font color="#008844">; exp: 1 env:NIL</font>
+ <font color="#008844">; exp: (+ A A) env:((((A . 1))))</font>
+ <font color="#008844">; exp: A env:((((A . 1))))</font>
+ <font color="#008844">; exp: A env:((((A . 1))))</font>
+ <font color="#008844">; returns 2</font>
+
+(top-level) <font color="#008844">; to clean up *evalhook*</font>
+</pre>
+
+<p><b>Note:</b> The <a href="evalhook.htm">evalhook</a> function and
+*evalhook* system variable are very useful in the construction of debugging
+facilities within XLISP. The <a href="trace.htm">trace</a> and
+<a href="untrace.htm">untrace</a> functions use
+<a href="evalhook.htm">evalhook</a> and *evalhook* to implement
+their functionality. The other useful aspect of
+<a href="evalhook.htm">evalhook</a> and *evalhook* is to help in
+understanding how XLISP works to see the expressions, their environment
+and how they are evaluated.</p>
+
+<p><b>Caution:</b> Be careful when using *evalhook* and
+<a href="evalhook.htm">evalhook</a>. If you put in a bad definition
+into *evalhook*, you might not be able to do anything and will need to
+exit XLISP.</p>
+
+<p><b>Unusual behaviour:</b> The <a href="evalhook.htm">evalhook</a>
+function and *evalhook* system variable, by their nature, cause some unusual
+things to happen. After you have set *evalhook* to some
+non-<a href="nil.htm">NIL</a> value, your function will be
+called. However, when you are all done and set *evalhook* to
+<a href="nil.htm">NIL</a> or some other new routine, it will
+never be set. This is because the
+<a href="evalhook.htm">evalhook</a> function [in the 'xlbfun.c'
+source file] saves the old value of *evalhook* before calling your routine,
+and then restores it after the evaluation. The mechanism to reset
+*evalhook* is to execute the
+<a href="top-level.htm">top-level</a> function, which sets
+*evalhook* to <a href="nil.htm">NIL</a>.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#evalhook">*evalhook*</a>
+system variable in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-file-separator.htm b/docsrc/xlisp/xlisp-doc/reference/global-file-separator.htm new file mode 100644 index 0000000..f30bb3b --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-file-separator.htm @@ -0,0 +1,68 @@ +<html><head><title>XLISP *file-separator*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*file-separator*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt> *file-separator*</dt>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The Nyquist *file-separator* variable is initialized to the operation
+system's file separator character. <nobr>It has</nobr> a value of #\\ on
+Windows and a value of #\/ on Unix [including Linux and <nobr>Mac OS
+X]</nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+*file-separator* => #\/ <font color="#008844">; on Unix, Linux, and Mac OS X</font>
+*file-separator* => #\\ <font color="#008844">; on Windows</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-float-format.htm b/docsrc/xlisp/xlisp-doc/reference/global-float-format.htm new file mode 100644 index 0000000..3665b7b --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-float-format.htm @@ -0,0 +1,179 @@ +<html><head><title>XLISP *float-format*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*float-format*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlprin.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *float-format*</dt>
+<dd>returns - the print format for <nobr>floating-point</nobr> numbers</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p> *float-format* is a system variable that allows a user to specify how
+floating point numbers are to be printed by XLISP. The value of
+*float-format* should be set to one of the string expressions
+"%e", "%f" or "%g". These format strings are
+similar to C-language floating point specifications:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr valign="top">
+ <td><nobr><code> "%e"</code></nobr></td>
+ <td><nobr> -<code> </code></nobr></td>
+ <td width="100%">exponential. The number is converted to decimal notation
+ of the form:
+
+<pre class="example">
+[-]<font color="#0000CC"><i>m</i></font>.<font color="#0000CC"><i>nnnnnn</i></font>E[+-]<font color="#0000CC"><i>xx</i></font>
+</pre>
+
+ There is one leading digit. There are 6 digits after the decimal
+ point.</td>
+</tr>
+<tr>
+ <td><nobr><font size="-2"> </font></nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code> "%f"</code></nobr></td>
+ <td><nobr> -<code> </code></nobr></td>
+ <td width="100%">decimal. The number is converted to decimal notation of
+ the form:
+
+<pre class="example">
+[-]<font color="#0000CC"><i>mmmmmm</i></font>.<font color="#0000CC"><i>nnnnnn</i></font>
+</pre>
+
+ There are as many digits before the decimal point as necessary. There
+ are 6 digits after the decimal point.</td>
+</tr>
+<tr>
+ <td><nobr><font size="-2"> </font></nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code> "%g"</code></nobr></td>
+ <td><nobr> -<code> </code></nobr></td>
+ <td width="100%">shortest. The number is converted to either the form of
+ "%e" or "%f", whichever produces the shortest output
+ string. Non-significant zeroes are not printed.</td>
+</tr>
+</tbody></table></p>
+
+<p> The default value for *float-format* is the string "%g".</p>
+
+<p>There are several additional flags and options available:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr><code> +</code></nobr></td>
+ <td><nobr> <code> </code>-<code> </code></nobr></td>
+ <td width="100%"><nobr>always print the sign</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr><code><i>space</i></code></nobr></td>
+ <td><nobr> <code> </code>-<code> </code></nobr></td>
+ <td width="100%"><nobr>print a space instead of a + sign</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr><code> #</code></nobr></td>
+ <td><nobr> <code> </code>-<code> </code></nobr></td>
+ <td width="100%"><nobr>always print the dot, do not remove zeros after the dot</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr><code> .<i>n</i></code></nobr></td>
+ <td><nobr> <code> </code>-<code> </code></nobr></td>
+ <td width="100%"><nobr>number of digits after the dot</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>The flags and options must be written between the "%" and the
+formatting letter, as shown in the examples below.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq *float-format* "%e") <font color="#008844">; exponential notation</font>
+(print 1.0) => 1.000000e+00
+(print -9e99) => -9.000000e+99
+
+(setq *float-format* "%f") <font color="#008844">; decimal notation</font>
+(print 1.0) => 1.000000
+(print 1.0e4) => 10000.000000
+(print -999.99e-99) => -0.000000</font>
+
+(setq *float-format* "%g") <font color="#008844">; shortest notation</font>
+(print 1.0) => 1
+(print 1.0e7) => 1e+07
+(print -999.999e99) => -9.99999e+101
+
+(setq *float-format* "%+g") <font color="#008844">; always print the sign</font>
+(print 1.1) => +1.1
+(print -1.1) => -1.1
+
+(setq *float-format* "% g") <font color="#008844">; print a space instead of the + sign</font>
+(print 1.1) => 1.1
+(print -1.1) => -1.1
+
+(setq *float-format* "%#.10g") <font color="#008844">; ten digits after the dot</font>
+(print 1.0) => 1.000000000
+(print 1.0e7) => 10000000.00
+(print -999.9999999e99) => -9.999999999e+101
+
+(setq *float-format* "%+#.10g") <font color="#008844">; ten digits after the dot plus sign</font>
+(print 1.2345) => +1.234500000
+(print -1.2345) => -1.234500000
+
+(setq *float-format* "%%") <font color="#008844">; bad format</font>
+(print 1.0) => %%
+
+(setq *float-format* "%g") <font color="#008844">; reset to shortest notation</font>
+</pre>
+
+<p><b>Note:</b> The string in the <nobr>*float-format*</nobr> variable is
+the format specifier for the the underlying 'sprintf'
+<nobr>C-function</nobr>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-gc-flag.htm b/docsrc/xlisp/xlisp-doc/reference/global-gc-flag.htm new file mode 100644 index 0000000..33e3834 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-gc-flag.htm @@ -0,0 +1,79 @@ +<html><head><title>XLISP *gc-flag*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*gc-flag*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xldmem.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *gc-flag*</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>*gc-flag* is a system variable that controls the printing of a garbage
+collection message. If *gc-flag* is
+<nobr><a href="nil.htm">NIL</a> ,</nobr>
+no garbage collection messages will be printed. If *gc-flag* is
+non-<nobr><a href="nil.htm">NIL</a> ,</nobr> a garbage collection
+message will be printed whenever a <a href="gc.htm">gc</a> takes
+place. The default value for *gc-flag* is
+<a href="nil.htm">NIL</a>. The message will be of the form:</p>
+
+<pre class="example">
+[ gc: total 4000, 2497 free ]
+</pre>
+
+
+<h2>Examples</h2>
+
+<pre class="example">
+*gc-flag* <font color="#008844">; returns NIL</font>
+(gc) <font color="#008844">; returns NIL</font>
+(setq *gc-flag* T) <font color="#008844">; set up for message</font>
+(gc) <font color="#008844">; prints a gc message</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#gc-flag">*gc-flag*</a>
+system variable in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-gc-hook.htm b/docsrc/xlisp/xlisp-doc/reference/global-gc-hook.htm new file mode 100644 index 0000000..df39b55 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-gc-hook.htm @@ -0,0 +1,125 @@ +<html><head><title>XLISP *gc-hook*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*gc-hook*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xldmem.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *gc-hook*</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>*gc-hook* is a system variable that allows a user function to be
+performed everytime garbage is collected [either explicitly with
+<a href="gc.htm">gc</a> or automatically]. The default value for
+*gc-hook* is <a href="nil.htm">NIL</a>. When *gc-hook* is set to
+a non-<a href="nil.htm">NIL</a> symbol, it is enabled to execute
+the specified user routine. The user routine can be a quoted symbol or a
+closure. There are two parameters to the user routine, the total number of
+nodes and current free nodes after the garbage collection.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+*gc-hook* <font color="#008844">; returns NIL</font>
+(gc) <font color="#008844">; returns NIL</font>
+
+(defun mygchook (&rest stuff) <font color="#008844">; define the hook</font>
+ (print stuff)
+ (print "my hook"))
+
+(setq *gc-hook* 'mygchook) <font color="#008844">; set up *GC-HOOK*</font>
+
+(gc) <font color="#008844">; prints (2640 232)</font>
+ <font color="#008844">; "my hook"</font>
+ <font color="#008844">; returns NIL</font>
+
+(setq *gc-flag* T) <font color="#008844">; turn on the system GC message</font>
+
+(gc) <font color="#008844">; prints</font>
+ <font color="#008844">; [ gc: total 2640, (2640 241)</font>
+ <font color="#008844">; "my hook"</font>
+ <font color="#008844">; 236 free ]</font>
+ <font color="#008844">; returns NIL</font>
+
+(setq *gc-flag* NIL) <font color="#008844">; turn off GC message</font>
+
+(setq *gc-hook* (lambda (x y) <font color="#008844">; enable user routine</font>
+ (princ "\007"))) <font color="#008844">; that beeps at every GC</font>
+
+(gc) <font color="#008844">; beeps</font>
+
+(defun expand-on-gc (total free) <font color="#008844">; define EXPAND-ON-GC</font>
+ (if (< (/ free 1.0 total) .1) <font color="#008844">; IF free/total < .10</font>
+ (progn (expand 2) <font color="#008844">; THEN expand memory</font>
+ (princ "\007")))) <font color="#008844">; and beep</font>
+
+ <font color="#008844">; NOTE: XLISP already gets more nodes</font>
+ <font color="#008844">; automatically, this is just an example.</font>
+
+(setq *gc-hook* 'expand-on-gc) <font color="#008844">; enable EXPAND-ON-GC</font>
+(gc) <font color="#008844">; beeps when low on nodes</font>
+</pre>
+
+<p><b>Note:</b> The *gc-hook* and <a href="global-gc-flag.htm">*gc-flag*</a>
+facilities can interact. If you do printing in the *gc-hook* user form and
+enable <nobr><a href="global-gc-flag.htm">*gc-flag*</a> ,</nobr> the
+*gc-hook* printing will come out in the middle of the
+<a href="global-gc-flag.htm">*gc-flag*</a> message.</p>
+
+<p><b>Note:</b> The *gc-hook* user form is evaluated after the execution of
+the actual garbage collection code. This means that if the user form causes
+an error, it does not prevent a garbage collection.</p>
+
+<p><b>Note:</b> Since *gc-hook* is set to a symbol, the user defined form
+can be changed by doing another <a href="defun.htm">defun</a> [or
+whatever] to the symbol in *gc-hook*. Note also that you should define the
+symbol first and then set *gc-hook* to the symbol. If you don't, an
+automatic garbage collection might occur before you set *gc-hook*,
+generating an error and stopping your program.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#gc-hook">*gc-hook*</a>
+system variable in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-integer-format.htm b/docsrc/xlisp/xlisp-doc/reference/global-integer-format.htm new file mode 100644 index 0000000..40cb06f --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-integer-format.htm @@ -0,0 +1,129 @@ +<html><head><title>XLISP *integer-format*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*integer-format*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlprin.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *integer-format*</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>*integer-format* is a system variable that allows a user to specify how
+integer numbers are to be printed by XLISP. The value of *integer-format*
+should be set to one of the string expressions "%ld",
+"%lo" or "%lx" [the character after the percent
+character is the lower-case 'L' character]. These format strings are similar
+to C-language floating point specifications:</p>
+
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr><code>"%ld"</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>decimal</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code>"%lu"</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>unsigned decimal</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code>"%lo"</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>unsigned octal</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code>"%lx"</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>unsigned hexadecimal</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>The default value for *integer-format* is the string "%ld".</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+*integer-format* <font color="#008844">; returns "%ld"</font>
+
+(setq *integer-format* "%ld") <font color="#008844">; signed decimal</font>
+(print 1) <font color="#008844">; prints 1</font>
+(print 1234) <font color="#008844">; prints 1234</font>
+(print -1) <font color="#008844">; prints -1</font>
+(print -1234) <font color="#008844">; prints -1234</font>
+
+(setq *integer-format* "%lo") <font color="#008844">; octal notation</font>
+(print 1) <font color="#008844">; prints 1</font>
+(print 1234) <font color="#008844">; prints 2322</font>
+(print -1) <font color="#008844">; prints 37777777777</font>
+(print -1234) <font color="#008844">; prints 37777775456</font>
+
+(setq *integer-format* "%lx") <font color="#008844">; hexadecimal notation</font>
+(print 1) <font color="#008844">; prints 1</font>
+(print -1) <font color="#008844">; prints ffffffff</font>
+(print 1234) <font color="#008844">; prints 4d2</font>
+(print -1234) <font color="#008844">; prints fffffb2e</font>
+
+(setq *integer-format* "%u") <font color="#008844">; unsigned decimal</font>
+(print 1) <font color="#008844">; prints 1</font>
+(print 1234) <font color="#008844">; prints 1234</font>
+(print -1) <font color="#008844">; prints 4294967295</font>
+(print -1234) <font color="#008844">; prints 4294966062</font>
+
+(setq *integer-format* "hi") <font color="#008844">; a bad notation</font>
+(print 1) <font color="#008844">; prints hi</font>
+(print 9999) <font color="#008844">; prints hi</font>
+
+(setq *integer-format* "%ld") <font color="#008844">; reset to original "%ld"</font>
+</pre>
+
+<p><b>Note:</b> There can be other characters put in the string, but in
+general, this will not produce particularly desirable behaviour. There is no
+error checking performed on the format string.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#integer-format">*integer-format*</a>
+system variable in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-obarray.htm b/docsrc/xlisp/xlisp-doc/reference/global-obarray.htm new file mode 100644 index 0000000..5014f40 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-obarray.htm @@ -0,0 +1,79 @@ +<html><head><title>XLISP *obarray*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*obarray*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlsym.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *obarray*</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>The *obarray* system variable contains the system symbol table.
+This symbol table is an XLISP array that is constructed out of lists.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun lookin (sym) <font color="#008844">; create a function to</font>
+ (aref *obarray* <font color="#008844">; look inside *OBARRAY*</font>
+ (hash sym (length *obarray*)))) <font color="#008844">; and look for a specific</font>
+ <font color="#008844">; symbol - returns a list</font>
+
+(lookin "CAR") <font color="#008844">; returns (TEST PEEK CAR)</font>
+(lookin "car") <font color="#008844">; returns NIL</font>
+</pre>
+
+<p><b>Note:</b> When looking into *obarray* or
+<a href="intern.htm">intern</a>ing symbols, remember that
+"car" and "CAR" written as strings [with quotation marks
+in front and behind] are two different symbols in *obarray*. Remember also
+that normal symbols created by XLISP are upper case names. So, if you type
+in 'car as a normal symbol [with a single quote in front of it], it will be
+the symbol CAR after this normal upper-casing operation.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#obarray">*obarray*</a>
+system variable in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-print-case.htm b/docsrc/xlisp/xlisp-doc/reference/global-print-case.htm new file mode 100644 index 0000000..34b84a2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-print-case.htm @@ -0,0 +1,82 @@ +<html><head><title>XLISP *print-case*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*print-case*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlprin.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *print-case*</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>*print-case* is a system variable that allows a user to specify how
+symbols are to be printed by XLISP. If *print-case* is set to ':downcase',
+all symbols will be printed in lower case characters. If *print-case* is set
+to ':upcase', all symbols will be printed in upper case characters. If
+*print-case* is set to anything other than ':upcase' or ':downcase', all
+symbols will be printed in upper case characters. The default value for
+*print-case* is ':upcase'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq *print-case* :downcase) <font color="#008844">; returns :downcase</font>
+(setq a 'b) <font color="#008844">; returns b</font>
+
+(setq *print-case* 'foo) <font color="#008844">; returns FOO</font>
+(setq a 'b) <font color="#008844">; returns B</font>
+
+(setq *print-case* :upcase) <font color="#008844">; returns :UPCASE</font>
+(setq a 'b) <font color="#008844">; returns B</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common LISP supports a third keyword ':capitalize' to
+print the first character of symbol names in upper-case. XLISP does not
+support this. In XLISP, if *print-case* is set to ':capitalize', all
+characters in symbols names will be printed in upper-case characters.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#print-case">*print-case*</a>
+system variable in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-readtable.htm b/docsrc/xlisp/xlisp-doc/reference/global-readtable.htm new file mode 100644 index 0000000..caa3d70 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-readtable.htm @@ -0,0 +1,166 @@ +<html><head><title>XLISP *readtable*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*readtable*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlread.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *readtable*</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p> The *readtable* is a system variable that contains XLISP's data
+structures relating to the processing of characters from the user (or files)
+and read-macro expansions. The table is 128 entries [0..127] for each of the
+7-bit <a href="../misc/ascii-table.htm">ASCII</a> characters that
+XLISP can read. Each entry in the *readtable* array must be one of
+<nobr><a href="nil.htm">NIL</a> ,</nobr>
+<nobr><a href="keyword-constituent.htm">:constituent</a> ,</nobr>
+<nobr><a href="keyword-white-space.htm">:white-space</a> ,</nobr>
+<nobr><a href="keyword-sescape.htm">:sescape</a> ,</nobr>
+<nobr><a href="keyword-mescape.htm">:mescape</a> ,</nobr> a
+<a href="keyword-tmacro.htm">:tmacro</a> dotted pair or a
+<a href="keyword-nmacro.htm">:nmacro</a> dotted pair with the meaning
+of:</p>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr><code> NIL</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr>the character is invalid</nobr></td>
+ <td width="100%"><nobr> [see
+ <a href="nil.htm">nil</a>]</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code>:CONSTITUENT</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr>the character is valid, as is</nobr></td>
+ <td width="100%"><nobr> [see
+ <a href="keyword-constituent.htm">:constituent</a>]</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code>:WHITE-SPACE</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr>the character may be skipped over</nobr></td>
+ <td width="100%"><nobr> [see
+ <a href="keyword-white-space.htm">:white-space</a>]</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code>:SESCAPE</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr>the single escape character '\'</nobr></td>
+ <td width="100%"><nobr> [see
+ <a href="keyword-sescape.htm">:sescape</a>]</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code>:MESCAPE</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr>the multiple escape character '|'</nobr></td>
+ <td width="100%"><nobr> [see
+ <a href="keyword-mescape.htm">:mescape</a>]</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code>(:TMACRO . <i>fun</i>)</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr>a terminating readmacro</nobr></td>
+ <td width="100%"><nobr> [see
+ <a href="keyword-tmacro.htm">:tmacro</a>]</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code>(:NMACRO . <i>fun</i>)</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr>a non-terminating readmacro</nobr></td>
+ <td width="100%"><nobr> [see
+ <a href="keyword-nmacro.htm">:nmacro</a>]</nobr></td>
+</tr>
+</tbody></table></p>
+
+
+<p>In the case of <a href="keyword-nmacro.htm">:nmacro</a> and
+<nobr><a href="keyword-tmacro.htm">:tmacro</a> ,</nobr> the form of the
+*readtable* entry is a list like:</p>
+
+<pre class="example">
+(:tmacro . <font color="#008844"><i>function</i></font>)
+(:nmacro . <font color="#008844"><i>function</i></font>)
+</pre>
+
+<p>The 'function' can be a built-in read-macro function or a user defined
+<a href="lambda.htm">lambda</a> expression. The 'function' takes two
+parameters, an input stream specification, and an integer that is the
+character value. The 'function' should return
+<a href="nil.htm">NIL</a> if the character is 'white-space' or a
+value <a href="cons.htm">cons</a>ed with
+<a href="nil.htm">NIL</a> to return the value.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+*readtable* <font color="#008844">; returns the current table</font>
+
+<font color="#008844">;; define a function to look in a table and</font>
+<font color="#008844">;; print out any entries with a function</font>
+
+(defun look-at (table)
+ (dotimes (ch 127)
+ (prog ((entry (aref table ch)))
+ (case entry
+ (nil nil)
+ (:constituent nil)
+ (:white-space nil)
+ (:sescape nil)
+ (:mescape nil)
+ (t (princ (int-char ch))))))
+ (terpri))
+
+(look-at *readtable*) <font color="#008844">; prints "#'(),;`</font>
+</pre>
+
+<p><b>Caution:</b> If you experiment with *readtable*, it is useful to save
+the old value in a variable, so that you can restore the system state.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#readtable">*readtable*</a>
+system variable in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-rslt.htm b/docsrc/xlisp/xlisp-doc/reference/global-rslt.htm new file mode 100644 index 0000000..84e2254 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-rslt.htm @@ -0,0 +1,83 @@ +<html><head><title>XLISP *rslt*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*rslt*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>not explicitely defined</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>*rslt*</dt>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>When a function returns more than one value, the global Nyquist *rslt*
+variable is set to a list of the 'extra' values. This provides a
+<nobr>make-shift</nobr> version of the '<nobr>multiple-value-return</nobr>'
+facility in <nobr>Common Lisp</nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun cl:values (&rest args)
+ (setq *rslt* args)
+ (first args))
+
+(values 1 2 3) => 1
+*rslt* => (1 2 3)
+</pre>
+
+<p>See <a href="defun.htm">defun</a>, <a href="first.htm">first</a>,
+<a href="rest.htm">rest</a>,
+<a href="lambda-keyword-rest.htm">&rest</a>,
+<a href="setq.htm">setq</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr><a href="../examples/values.htm">Multiple Values</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-standard-input.htm b/docsrc/xlisp/xlisp-doc/reference/global-standard-input.htm new file mode 100644 index 0000000..37cdcbc --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-standard-input.htm @@ -0,0 +1,73 @@ +<html><head><title>XLISP *standard-input*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*standard-input*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *standard-input*</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>The *standard-input* system variable contains a file pointer that points
+to the file where all normal input from the programmer or user comes from.
+The default file for *standard-input* is the system standard input device,
+normally the system keyboard.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+*standard-input* <font color="#008844">; returns #<File-Stream: #2442e></font>
+</pre>
+
+<p><b>Note:</b> Be careful when modifying the *standard-input*. If you do
+not save the old file pointer, you will not be able to return to normal
+operation and will need to exit XLISP. If the file or source that you have
+set *standard-input* to does not reset *standard-input* to its previous
+value, you will never get control back to the keyboard.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#standard-input">*standard-input*</a>
+system variable in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-standard-output.htm b/docsrc/xlisp/xlisp-doc/reference/global-standard-output.htm new file mode 100644 index 0000000..65c0d73 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-standard-output.htm @@ -0,0 +1,81 @@ +<html><head><title>XLISP *standard-output*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*standard-output*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *standard-output*</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>The *standard-output* system variable contains a file pointer that points
+to the file where all normal printing and messages from XLISP will go. The
+default file for *standard-output* is the system standard output device,
+normally the screen display.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+*standard-output* <font color="#008844">; returns #<File-Stream: #24406></font>
+(setq old-so *standard-output*) <font color="#008844">; save the file pointer</font>
+(setq fp (open "f" :direction :output)) <font color="#008844">; open a new output file</font>
+(setq *standard-output* fp) <font color="#008844">; change where output goes</font>
+
+(+ 2 2) <font color="#008844">; you won't see any messages</font>
+ <font color="#008844">; just the echo of input line</font>
+
+(setq *standard-output* old-so) <font color="#008844">; restore standard output</font>
+(close fp) <font color="#008844">; close file</font>
+</pre>
+
+<p><b>Note:</b> Be careful when modifying the *standard-output*, you will
+not be able to see what you are doing. If you do not save the old file
+pointer, you will not be able to return to normal operation and will need to
+exit XLISP.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#standard-output">*standard-output*</a>
+system variable in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-trace-output.htm b/docsrc/xlisp/xlisp-doc/reference/global-trace-output.htm new file mode 100644 index 0000000..697a70f --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-trace-output.htm @@ -0,0 +1,71 @@ +<html><head><title>XLISP *trace-output*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*trace-output*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.c, xlio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *trace-output*</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>The *trace-output* system variable contains a file pointer that points to
+the file where all trace output goes to. The default file for *trace-output*
+is the system standard error device, normally the screen.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+*trace-output* <font color="#008844">; returns #<File-Stream...></font>
+</pre>
+
+<p><b>Note:</b> *trace-output*,
+<a href="global-debug-io.htm">*debug-io*</a> and
+<a href="global-error-output.htm">*error-output*</a> are normally all set to
+the same file stream 'stderr'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#trace-output">*trace-output*</a>
+system variable in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-tracelimit.htm b/docsrc/xlisp/xlisp-doc/reference/global-tracelimit.htm new file mode 100644 index 0000000..7af1f15 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-tracelimit.htm @@ -0,0 +1,103 @@ +<html><head><title>XLISP *tracelimit*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*tracelimit*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.c, xldbug.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *tracelimit*</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>The *tracelimit* system variable controls the number of forms printed on
+entry to the <nobr><a href="../manual/xlisp-man-004.htm">break
+loop</a></nobr>. If *tracelimit* is an integer, then the integer is the
+maximum number of forms that will be printed. If *tracelimit* is <a
+href="nil.htm">NIL</a> or a non-integer, then all of the forms
+will be printed. Note that <a href="global-tracenable.htm">*tracenable*</a>
+needs to be set to a non-<a href="nil.htm">NIL</a> value to
+enable the printing of back-trace information on entry to the <nobr><a
+href="../manual/xlisp-man-004.htm">break loop</a></nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun foo (x) (fee x)) <font color="#008844">; define FOO</font>
+(defun fee (y) (break)) <font color="#008844">; define FEE</font>
+(setq *tracenable* T) <font color="#008844">; enable the back trace</font>
+(setq *tracelimit* NIL) <font color="#008844">; show all the entries</font>
+
+(foo 5) <font color="#008844">; break: **BREAK**</font>
+ <font color="#008844">; prints Function:#<Subr-BREAK...></font>
+ <font color="#008844">; Function:#<Closure-FEE...></font>
+ <font color="#008844">; Arguments:</font>
+ <font color="#008844">; 5</font>
+ <font color="#008844">; Function:#<Closure-FOO...></font>
+ <font color="#008844">; Arguments:</font>
+ <font color="#008844">; 5</font>
+
+(clean-up) <font color="#008844">; from break loop</font>
+(setq *tracelimit* 2) <font color="#008844">; show only 2 entries</font>
+
+(foo 5) <font color="#008844">; break: **BREAK**</font>
+ <font color="#008844">; prints Function:#<Subr-BREAK...></font>
+ <font color="#008844">; Function:#<Closure-FEE...></font>
+ <font color="#008844">; Arguments:</font>
+ <font color="#008844">; 5</font>
+
+(clean-up) <font color="#008844">; from break loop</font>
+</pre>
+
+<p><b>Note:</b> <a href="global-tracenable.htm">*tracenable*</a> and
+*tracelimit* system variables have to do with back trace information at
+entry to a
+<nobr><a href="../manual/xlisp-man-004.htm">break loop</a></nobr>
+and are not related to the
+<a href="trace.htm">trace</a> and
+<a href="untrace.htm">untrace</a> functions.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#tracelimit">*tracelimit*</a>
+system variable in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-tracelist.htm b/docsrc/xlisp/xlisp-doc/reference/global-tracelist.htm new file mode 100644 index 0000000..3c84faa --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-tracelist.htm @@ -0,0 +1,74 @@ +<html><head><title>XLISP *tracelist*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*tracelist*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.c, xleval.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *tracelist*</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>The *tracelist* system variable contains a list of the current
+functions being <a href="trace.htm">trace</a>d.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun foo (x) (print (car x))) <font color="#008844">; define FOO</font>
+(trace foo) <font color="#008844">; returns (FOO)</font>
+(trace car) <font color="#008844">; returns (CAR FOO)</font>
+
+(print *tracelist*) <font color="#008844">; prints (CAR FOO)</font>
+
+(untrace foo) <font color="#008844">; returns (CAR)</font>
+(untrace car) <font color="#008844">; returns NIL</font>
+
+(print *tracelist*) <font color="#008844">; prints NIL</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#tracelist">*tracelist*</a>
+system variable in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-tracenable.htm b/docsrc/xlisp/xlisp-doc/reference/global-tracenable.htm new file mode 100644 index 0000000..8863e96 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-tracenable.htm @@ -0,0 +1,105 @@ +<html><head><title>XLISP *tracenable*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*tracenable*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.c, xldbug.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *tracenable*</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>The *tracenable* system variable controls whether or not the
+<nobr><a href="../manual/xlisp-man-004.htm">break loop</a></nobr>
+prints any back trace information on entry to the
+<nobr><a href="../manual/xlisp-man-004.htm">break loop</a></nobr>. If
+*tracenable* is <nobr><a href="nil.htm">NIL</a> ,</nobr> then
+there will be no information printed on entry to the
+<nobr><a href="../manual/xlisp-man-004.htm">break loop</a>.</nobr>
+If *tracenable* is <nobr>non-<a href="nil.htm">NIL</a> ,</nobr>
+then information will be printed. The 'init.lsp' initialization file sets
+*tracenable* usually to <nobr><a href="nil.htm">NIL</a> ,</nobr>
+which suppresses the printing.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun foo (x) (fee x)) <font color="#008844">; define FOO</font>
+(defun fee (y) (break)) <font color="#008844">; define FEE</font>
+(setq *tracenable* T) <font color="#008844">; enable the back trace</font>
+(setq *tracelimit* NIL) <font color="#008844">; show all the entries</font>
+
+(foo 5) <font color="#008844">; break: **BREAK**</font>
+ <font color="#008844">; prints Function:#<Subr-BREAK...></font>
+ <font color="#008844">; Function:#<Closure-FEE...></font>
+ <font color="#008844">; Arguments:</font>
+ <font color="#008844">; 5</font>
+ <font color="#008844">; Function:#<Closure-FOO...></font>
+ <font color="#008844">; Arguments:</font>
+ <font color="#008844">; 5</font>
+
+(clean-up) <font color="#008844">; from break loop</font>
+(setq *tracelimit* 2) <font color="#008844">; show only 2 entries</font>
+
+(foo 5) <font color="#008844">; break: **BREAK**</font>
+ <font color="#008844">; prints Function:#<Subr-BREAK...></font>
+ <font color="#008844">; Function:#<Closure-FEE...></font>
+ <font color="#008844">; Arguments:</font>
+ <font color="#008844">; 5</font>
+
+(clean-up) <font color="#008844">; from break loop</font>
+</pre>
+
+<p><b>Note:</b> *tracenable* and
+<a href="global-tracelimit.htm">*tracelimit*</a> system variables have to do
+with back trace information at entry to a
+<nobr><a href="../manual/xlisp-man-004.htm">break loop</a></nobr>
+and are not related to the
+<a href="trace.htm">trace</a> and
+<a href="untrace.htm">untrace</a> functions.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#tracenable">*tracenable*</a>
+system variable in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/global-unbound.htm b/docsrc/xlisp/xlisp-doc/reference/global-unbound.htm new file mode 100644 index 0000000..424b603 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/global-unbound.htm @@ -0,0 +1,70 @@ +<html><head><title>XLISP *unbound*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*unbound*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system constant</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.c, xlsym.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> *unbound*</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>The *unbound* system constant is used to indicate when a symbol has no
+value. *unbound* is set to the value *unbound*. This means that the system
+thinks the symbol *unbound* has no value.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+*unbound* <font color="#008844">; error: unbound variable</font>
+(setq a 5) <font color="#008844">; returns 5</font>
+a <font color="#008844">; returns 5</font>
+(setq a '*unbound*) <font color="#008844">; returns *UNBOUND*</font>
+a <font color="#008844">; error: unbound variable</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-011.htm#unbound">*unbound*</a>
+system constant in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/go.htm b/docsrc/xlisp/xlisp-doc/reference/go.htm new file mode 100644 index 0000000..3c3715f --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/go.htm @@ -0,0 +1,106 @@ +<html><head><title>XLISP go</title></head>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>go</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(go <i>tag-symbol</i>)</dt>
+<dd><i>tag-symbol</i> - a symbol<br>
+returns - never returns a value</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'go' special form allows 'goto' style branching within 'block' constructs
+<nobr>[<a href="do.htm">do</a> ,</nobr>
+<nobr><a href="do-star.htm">do*</a> ,</nobr>
+<nobr><a href="dolist.htm">dolist</a> ,</nobr>
+<nobr><a href="dotimes.htm">dotimes</a> ,</nobr>
+<nobr><a href="tagbody.htm">tagbody</a> ,</nobr>
+<nobr><a href="loop.htm">loop</a> ,</nobr>
+<a href="prog.htm">prog</a> and
+<a href="prog-star.htm">prog*</a>]. The
+'tag-symbol' is the 'label' and must exist somewhere within the 'block'
+that the 'go' occurs within. Otherwise an error will be generated:</p>
+
+<pre class="example">
+<font color="#AA0000">error: no target for GO</font>
+</pre>
+
+<p>'go' never returns a value. If the 'tag-symbol' exists, then
+the execution will continue immediately after the'tag-symbol'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun foo (i j) <font color="#008844">; define FOO</font>
+ (prog () <font color="#008844">; with a PROG</font>
+ (print "begin")
+ start (print j) <font color="#008844">; tag - START</font>
+ (setq j (1- j))
+ (if (eql i j) (GO start) <font color="#008844">; 2-way branch</font>
+ (GO end))
+ (print "hello") <font color="#008844">; won't ever be reached</font>
+ end (print "done") <font color="#008844">; tag - END</font>
+ (return 42)))
+
+(foo 1 2) <font color="#008844">; prints "begin" 2 1 "done"</font>
+ <font color="#008844">; returns 42</font>
+
+(foo 2 1) <font color="#008844">; prints "begin" 1 "done"</font>
+ <font color="#008844">; returns 42</font>
+</pre>
+
+<p><b>Note:</b> Although 'go' will accept a 'tag-symbol' that is not a
+symbol, it will not find this improper 'tag-symbol'. An error will be
+generated:</p>
+
+<pre class="example">
+<font color="#AA0000">error: no target for GO</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-021.htm#go">go</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/hash.htm b/docsrc/xlisp/xlisp-doc/reference/hash.htm new file mode 100644 index 0000000..03abbe7 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/hash.htm @@ -0,0 +1,90 @@ +<html><head><title>XLISP hash</title></head>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>hash</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c, xlsym.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(hash <i>name table-size</i>)</dt>
+<dd><i>name</i> - a symbol or string expression<br>
+<i>table-size</i> - an integer expression<br>
+returns - the hash index as an integer value</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'hash' function computes and returns an integer index for a given
+symbol 'name' and a given size of hash table 'table-size'. The intention is
+for 'hash' to be used with tables made by
+<a href="make-array.htm">make-array</a> and accessed by
+<a href="aref.htm">aref</a>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(hash "zzzz" 1000) <font color="#008844">; returns index 322</font>
+(hash "ZZZZ" 1000) <font color="#008844">; returns index 626</font>
+(hash 'ZZZZ 1000) <font color="#008844">; returns index 626</font>
+(hash "hiho" 1000) <font color="#008844">; returns index 519</font>
+(hash 'hiho 1000) <font color="#008844">; returns index 143</font>
+(hash "abcd" 1000) <font color="#008844">; returns index 72</font>
+
+<font color="#008844">;; create a function to look inside *OBARRAY* and</font>
+<font color="#008844">;; look for a specific symbol - returns a list</font>
+
+(defun lookin (sym)
+ (aref *obarray*
+ (hash sym (length *obarray*))))
+
+(lookin 'caar) <font color="#008844">; returns the hash table entry</font>
+ <font color="#008844">; (ZEROP CDDDDR CAAR HASH)</font>
+</pre>
+
+<p><b>Note:</b> This is a useful function for creating and accessing tables.
+It is also useful for looking inside of XLISP's own symbol table
+<a href="global-obarray.htm">*obarray*</a>.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-013.htm#hash">hash</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/if.htm b/docsrc/xlisp/xlisp-doc/reference/if.htm new file mode 100644 index 0000000..423e5bf --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/if.htm @@ -0,0 +1,83 @@ +<html><head><title>XLISP if</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>if</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(if <i>test-expr then-expr</i> [<i>else-expr</i>])</dt>
+<dd><i>test-expr</i> - an expression<br>
+<i>then-expr</i> - the THEN clause, an expression<br>
+<i>else-expr</i> - the ELSE clause, an optional expression<br>
+returns - the value of the selected expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'if' special form evaluates the 'test-expr'. If 'test-expr' evaluates
+to a non-<a href="nil.htm">NIL</a> value, then 'then-expr' is
+evaluated and returned as the result. If 'test-expr' evaluates to
+<a href="nil.htm">NIL</a> and there is an 'else-expr', then the
+'else-expr' is evaluated and its result is returned. If there is no
+'else-expr' and 'test-expr' evaluates to
+<nobr><a href="nil.htm">NIL</a> ,</nobr> then
+<a href="nil.htm">NIL</a> is returned as a result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(if T (print "will print") <font color="#008844">; prints "will print"</font>
+ (print "won't print"))
+
+(if NIL (print "won't print")
+ (print "will print")) <font color="#008844">; prints "will print"</font>
+
+(if 'a T NIL) <font color="#008844">; returns T</font>
+
+(if NIL 'nope 'yep) <font color="#008844">; returns YEP</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-019.htm#if"> if </a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/incf.htm b/docsrc/xlisp/xlisp-doc/reference/incf.htm new file mode 100644 index 0000000..bcf70f2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/incf.htm @@ -0,0 +1,88 @@ +<html><head><title>XLISP incf</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>incf</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp macro (closure)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>misc.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>incf</b> <i>symbol</i>)</nobr></dt>
+<dd><i>symbol</i> - a symbol with numerical value bound to it<br>
+returns - the new value of the symbol</dd>
+</dl>
+
+</div></p>
+
+<p>In Nyquist, 'incf' is implemented as a Lisp macro:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">incf</font> (symbol)
+ `(setf ,symbol (1+ ,symbol)))
+</pre>
+
+<h2>Description</h2>
+
+<p>The 'incf' macro is used for incrementing a numerical value of a variable.
+<nobr>1 is</nobr> added to the number and the result is stored in the
+variable. <nobr>An error</nobr> is signalled if the variable doesn't hold a
+number.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq n 1) => 1
+(incf n) => 2
+n => 2
+(incf n) => 3
+
+(setq n -1.8) => -1.8
+(incf n) => -0.8
+(incf n) => 0.2
+(incf n) => 1.2
+n => 1.2
+
+(setq n #\a) => #\a
+(incf a) => <font color="#AA0000">error: bad argument type - #\a</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/increment.htm b/docsrc/xlisp/xlisp-doc/reference/increment.htm new file mode 100644 index 0000000..06f3c57 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/increment.htm @@ -0,0 +1,75 @@ +<html><head><title>XLISP 1+</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>1+</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(1+ <i>expr</i>)</nobr></dt>
+<dd><i>expr</i> - integer or floating point number/expression<br>
+returns - the number plus one</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The <nobr>'1+' [increment]</nobr> function adds one to a number and
+returns the result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(1+ 1) => 2
+(1+ 99.1) => 100.1
+(1+ 1 2) => <font color="#AA0000">error: too many arguments</font>
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/info.htm b/docsrc/xlisp/xlisp-doc/reference/info.htm new file mode 100644 index 0000000..d76b33c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/info.htm @@ -0,0 +1,63 @@ +<html><head><title>XLISP info</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>info</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xldmem.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(info)</dt>
+<dd>returns - <a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The '<nobr>info</nobr>' function shows information about memory usage.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+> (info)
+[ Free: 5689, GC calls: 17, Total: 675111; samples 1KB, 0KB free]
+NIL
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/int-char.htm b/docsrc/xlisp/xlisp-doc/reference/int-char.htm new file mode 100644 index 0000000..8bdd97e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/int-char.htm @@ -0,0 +1,92 @@ +<html><head><title>XLISP int-char</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>int-char</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(int-char <i>int</i>)</dt>
+<dd><i>int</i> - an integer numeric expression<br>
+returns - the character with that code</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'int-char' function returns a character which is the result of turning the
+'int' expression into a character. If a 'int' cannot be made into a
+character, an error is signalled:</p>
+
+<pre class="example">
+<font color="#AA0000">error: character code out of range</font>
+</pre>
+
+<p>The range that 'int' produces a valid character is 0 through 255.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(int-char 48) <font color="#008844">; returns #\0</font>
+(int-char 65) <font color="#008844">; returns #\A</font>
+(int-char 97) <font color="#008844">; returns #\a</font>
+(int-char 91) <font color="#008844">; returns #\[</font>
+(int-char 10) <font color="#008844">; returns #\Newline</font>
+(int-char 999) <font color="#008844">; error - character code out of range</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp specifies that 'int-char' should return a
+<a href="nil.htm">NIL</a> when there is no valid character for
+the integer value being passed in while XLISP generates an error in these cases.
+In some cases it is possible to substitue the
+<a href="code-char.htm">code-char</a> function for 'int-char'.</p>
+
+<p><b>Note:</b> Unlike the <a href="char-code.htm">char-code</a> and
+<a href="char-int.htm">char-int</a> functions,
+<a href="code-char.htm">code-char</a> and 'int-char' are not identical
+in use. <a href="code-char.htm">code-char</a> accepts 0..127 for its
+range and then produces <a href="nil.htm">NIL</a> results while
+'int-char' accepts 0..255 for its range and then produces errors.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-026.htm#int-char">int-char</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/integerp.htm b/docsrc/xlisp/xlisp-doc/reference/integerp.htm new file mode 100644 index 0000000..9bce615 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/integerp.htm @@ -0,0 +1,82 @@ +<html><head><title>XLISP integerp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>integerp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(integerp <i>expr</i>)</dt>
+<dd><i>expr</i> - the expression to check<br>
+returns - <a href="t.htm"> T </a> if the value is an
+integer, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'integerp' predicate function checks if an 'expr' is a integer
+number. <a href="t.htm"> T </a> is returned if
+'expr' is a integer number,
+<a href="nil.htm">NIL</a> is returned otherwise.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(integerp 1) <font color="#008844">; returns T - integer</font>
+(integerp #x034) <font color="#008844">; returns T - integer readmacro</font>
+(integerp '1) <font color="#008844">; returns T - still an integer</font>
+(setq a 14)
+(integerp a) <font color="#008844">; returns T - evaluates to int.</font>
+(integerp 0) <font color="#008844">; returns T - integer zero</font>
+
+(integerp 1.2) <font color="#008844">; returns NIL - float</font>
+(integerp 0.0) <font color="#008844">; returns NIL - float zero</font>
+(integerp 'a) <font color="#008844">; returns NIL - symbol</font>
+(integerp #\a) <font color="#008844">; returns NIL - character</font>
+(integerp NIL) <font color="#008844">; returns NIL - NIL</font>
+(integerp #(0 1 2)) <font color="#008844">; returns NIL - array</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#integerp">integerp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/intern.htm b/docsrc/xlisp/xlisp-doc/reference/intern.htm new file mode 100644 index 0000000..3b23ac5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/intern.htm @@ -0,0 +1,117 @@ +<html><head><title>XLISP intern</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>intern</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(intern <i>name-str</i>)</dt>
+<dd><i>name-str</i> - a string expression<br>
+returns - the new symbol</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'intern' function takes a string name 'name-str' and creates a new
+interned symbol. What this means is that the symbol 'name-str' will be
+placed into the symbol hash table
+<a href="global-obarray.htm">*obarray*</a>. It's value will be unbound. It's
+property list will be <a href="nil.htm">NIL</a> [empty]. If the
+symbol already exists, no error or action is taken and the old values and
+property lists remain intact. The 'intern' function returns the symbol as
+its result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun lookin (sym) <font color="#008844">; create a function to</font>
+ (aref *obarray* <font color="#008844">; look inside *OBARRAY* and</font>
+ (hash sym (length *obarray*)))) <font color="#008844">; look for a specific symbol</font>
+ <font color="#008844">; returns a list</font>
+
+(lookin "FINGERS") <font color="#008844">; see if "FINGERS" is a symbol</font>
+ <font color="#008844">; returns (:START1) - it isn't</font>
+
+(intern "FINGERS") <font color="#008844">; intern "FINGERS" as a symbol</font>
+ <font color="#008844">; returns FINGERS</font>
+
+(lookin "FINGERS") <font color="#008844">; returns (FINGERS :START1)</font>
+
+(print fingers) <font color="#008844">; error: unbound variable</font>
+ <font color="#008844">; it exists, but has no value</font>
+
+(lookin "TOES") <font color="#008844">; returns NIL - doesn't exist</font>
+toes <font color="#008844">; error: unbound variable</font>
+
+(lookin "TOES") <font color="#008844">; returns (TOES)</font>
+ <font color="#008844">; the act of looking for a</font>
+ <font color="#008844">; value or using a symbol</font>
+ <font color="#008844">; causes it to be INTERNed</font>
+
+(lookin "KNEECAPS") <font color="#008844">; returns (MAX MAPLIST)</font>
+ <font color="#008844">; KNEECAPS doesn't exist</font>
+
+(setq kneecaps 'a-bone) <font color="#008844">; create symbol with a value</font>
+(lookin "KNEECAPS") <font color="#008844">; returns (KNEECAPS MAX MAPLIST)</font>
+</pre>
+
+<p><b>Note:</b> When you 'intern' a string symbol like "fingers"
+in lower case letters, this gets placed in the
+<a href="global-obarray.htm">*obarray*</a> symbol table as a lower case
+symbol. Note that this is different from doing an 'intern' on a string
+symbol "FINGERS" in upper case letters which will get placed in
+the <a href="global-obarray.htm">*obarray*</a> as a upper case symbol.
+"fingers" and "FINGERS" then are two different symbols
+in <a href="global-obarray.htm">*obarray*</a>. Remember also that normal
+symbols created by XLISP are automatically converted to upper case names.
+So, an intern of the lower case symbol name 'fingers and the upper case
+symbol name 'FINGERS will result in the effect that both symbol names get
+interned as the same upper-case symbol FINGERS.</p>
+
+<p><b>Common Lisp:</b> Common LISP allows an optional package
+specification, which XLISP does not support.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-013.htm#intern">intern</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/interpolate.htm b/docsrc/xlisp/xlisp-doc/reference/interpolate.htm new file mode 100644 index 0000000..72cee34 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/interpolate.htm @@ -0,0 +1,76 @@ +<html><head><title>XLISP interpolate</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>interpolate</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp function (closure)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xm.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(interpolate <i>x x1 y1 x2 y2</i>)</nobr></dt>
+<dd><i>x</i>, <i>x1</i>, <i>y1</i>, <i>x2</i>, <i>y2</i> - integer or floating point numbers<br>
+returns - the 'y' value corresponding to 'x'</dd>
+</dl>
+
+</div></p>
+
+<p>In Nyquist, 'interpolate' is implemented as a Lisp function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">interpolate</font> (x x1 y1 x2 y2)
+ (cond ((= x1 x2) x1)
+ (t (+ y1 (* (- x x1) (/ (- y2 y1) (- x2 (float x1))))))))
+</pre>
+
+<h2>Description</h2>
+
+<p>The 'interpolate' function linearly interpolates [or extrapolates]
+between points <nobr>(x1, y1)</nobr> and <nobr>(x2, y2)</nobr> to compute
+the <nobr>'y' value</nobr> corresponding <nobr>to 'x'</nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/intersection.htm b/docsrc/xlisp/xlisp-doc/reference/intersection.htm new file mode 100644 index 0000000..80af5f7 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/intersection.htm @@ -0,0 +1,76 @@ +<html><head><title>XLISP intersection</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>intersection</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp function (closure)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xm.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(intersection <i>list1 list2</i>)</nobr></dt>
+<dd><i>listN</i> - a list of symbols or numbers<br>
+returns - the intersection of <i>list1</i> and <i>list2</i></dd>
+</dl>
+
+</div></p>
+
+<p>In Nyquist, 'intersection' is implemented as a Lisp function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">intersection</font> (a b)
+ (let (result)
+ (dolist (elem a)
+ (if (member elem b) (push elem result)))
+ result))
+</pre>
+
+<h2>Description</h2>
+
+<p>The 'intersection' function computes the intersection of two lists.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/keyword-answer.htm b/docsrc/xlisp/xlisp-doc/reference/keyword-answer.htm new file mode 100644 index 0000000..d17b39b --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/keyword-answer.htm @@ -0,0 +1,107 @@ +<html><head><title>XLISP :answer</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>:answer</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>message selector</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlobj.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<a href="send.htm">send</a> <i>class</i> <b>:answer</b> <i>selector fargs body</i>)</nobr></dt>
+<dd><i>class</i> - an existing <a href="class.htm">class</a><br>
+<i>selector</i> - the message selector symbol<br>
+<i>fargs</i> - formal argument list of the same form as a <a href="lambda.htm">lambda</a> argument list<br>
+<i>body</i> - a list containing the method code<br>
+returns - the <a href="class.htm">class</a> object</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The ':answer' message selector adds or changes a method in the specified
+<a href="class.htm">class</a>. <nobr>This method</nobr> consists of the
+message selector symbol, the formal argument list and the executable code
+associated with the message.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq myclass (send class :new '(var))) <font color="#008844">; create MYCLASS with VAR</font>
+
+(send myclass :answer :isnew '() <font color="#008844">; set up initialization</font>
+ '((setq var nil) self))
+
+(send myclass :answer :set-it '(value) <font color="#008844">; create :SET-IT message</font>
+ '((setq var value)))
+
+(send myclass :answer :mine '() <font color="#008844">; create :MINE message</font>
+ '((print "hi there")))
+
+(setq my-obj (send myclass :new)) <font color="#008844">; create MY-OBJ of MYCLASS</font>
+(send my-obj :set-it 5) <font color="#008844">; VAR is set to 5</font>
+(send my-obj :mine) <font color="#008844">; prints "hi there"</font>
+</pre>
+
+<p><b>Note:</b> When you define a message in a
+
+<a href="class.htm">class</a>, the message is only valid for
+<b>instances</b> of the <a href="class.htm">class</a> or its
+<nobr>sub-classes</nobr>. <nobr>You will</nobr> get an error if you try to
+send the message to the <a href="class.htm">class</a> where it was first
+defined. <nobr>If you</nobr> want to add a message to a
+<a href="class.htm">class</a>, you need to define it in the
+<nobr>super-class</nobr> of the class.</p>
+
+<p><b>Message structure:</b> The normal XLISP convention for a message is to
+have a valid symbol preceeded by a colon like
+<a href="keyword-isnew.htm">:isnew</a> or ':my-message'. However, it is
+possible to define a message that is a symbol without a colon, but this
+pollutes the global namespace and also makes the code less readable.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr><a href="../manual/objects.htm">XLISP Object System</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/keyword-class.htm b/docsrc/xlisp/xlisp-doc/reference/keyword-class.htm new file mode 100644 index 0000000..75b1ef5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/keyword-class.htm @@ -0,0 +1,83 @@ +<html><head><title>XLISP :class</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>:class</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>message selector</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlobj.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(send <i>object</i> :class)</dt>
+<dd><i>object</i> - an existing <a href="object.htm">object</a><br>
+returns the <a href="class.htm">class</a> object</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The ':class' message selector will cause a method to run that will return the
+object which is the class of the specified 'object'. Note that the
+returned value is an object which will look like:</p>
+
+<pre class="example">
+#<Object: #18d8c>
+</pre>
+
+<p>The 'object' must exist or an error will be generated:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument type</font>
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(send object :class) <font color="#008844">; returns the CLASS object</font>
+(send class :class) <font color="#008844">; returns the CLASS object</font>
+(setq new-cls (send class :new '(var))) <font color="#008844">; create NEW-CLS</font>
+(setq new-obj (send new-cls :new)) <font color="#008844">; create NEW-OBJ of NEW-CLS</font>
+(send new-obj :class) <font color="#008844">; returns the NEW-CLS object</font>
+(send new-cls :class) <font color="#008844">; returns the CLASS object</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-010.htm#object-class">:class</a>
+message selector in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/keyword-constituent.htm b/docsrc/xlisp/xlisp-doc/reference/keyword-constituent.htm new file mode 100644 index 0000000..f9eca40 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/keyword-constituent.htm @@ -0,0 +1,95 @@ +<html><head><title>XLISP :constituent</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>:constituent</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>keyword</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlread.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> :constituent</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>':constituent' is an entry that is used in the
+<a href="global-readtable.htm">*readtable*</a> system variable that
+contains XLISP's data structures relating to the processing of characters
+from the user [or files] and read-macro expansions. The existance of the
+':constituent' keyword means that the specified character is to be used, as
+is, with no further processing. The system defines that the following
+characters are ':constituent' characters:</p>
+
+<pre class="example">
+0123456789
+!$%&*+-./:<=>?@[]^_{}~
+ABCDEFGHIJKLMNOPQRSTUVWXYZ
+abcdefghijklmnopqrstuvwxyz
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun look-at (table) <font color="#008844">; define a function to</font>
+ (dotimes (ch 127) <font color="#008844">; look in a table</font>
+ (prog ((entry (aref table ch))) <font color="#008844">; and print out any</font>
+ (case entry <font color="#008844">; entries with a function</font>
+ (:CONSTITUENT
+ (princ (int-char ch)))
+ (T NIL))))
+ (terpri))
+
+(look-at *readtable*) <font color="#008844">; prints !$%&*+-./0123456789</font>
+ <font color="#008844">; :<=>?@ABCDEFGHIJKLM</font>
+ <font color="#008844">; NOPQRSTUVWXYZ[]^_ab</font>
+ <font color="#008844">; cdefghijklmnopqrstu</font>
+ <font color="#008844">; vwxyz{}~</font>
+</pre>
+
+<p><b>Caution:</b> If you experiment with
+<nobr><a href="global-readtable.htm">*readtable*</a> ,</nobr> it is useful to
+save the old value in a variable, so that you can restore the system
+state.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-008.htm#constituent">:constituent</a>
+keyword in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/keyword-isa.htm b/docsrc/xlisp/xlisp-doc/reference/keyword-isa.htm new file mode 100644 index 0000000..e1b3e5c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/keyword-isa.htm @@ -0,0 +1,83 @@ +<html><head><title>XLISP :isnew</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>:isa</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>message selector</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlobj.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<a href="send.htm">send</a> <i>object</i> :isa <i>class</i>) - test if object inherits from class</dt>
+<dd>returns - <a href="../reference/t.htm"> T </a> if object
+is an instance of class or a subclass of class, otherwise
+<a href="../reference/nil.htm">NIL</a><br><br></dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The ':isa' message selector tests if an object inherits from a class.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq a-class (send class :new '(state))) <font color="#008844">; create a new class A-CLASS with STATE</font>
+
+(send a-class :answer :isnew '() <font color="#008844">; set up initialization</font>
+ '((setq state nil) self))
+
+(send a-class :answer :set-it '(value) <font color="#008844">; create :SET-IT message</font>
+ '((setq state value)))
+
+(setq an-obj (send a-class :new)) <font color="#008844">; create AN-OBJ out of A-CLASS</font>
+
+(send an-obj :show) <font color="#008844">; returns object - STATE = NIL</font>
+
+(send an-obj :set-it 5) <font color="#008844">; STATE is set to 5</font>
+(send an-obj :show) <font color="#008844">; returns object - STATE = 5</font>
+
+(SEND an-obj :ISNEW) <font color="#008844">; re-initialize AN-OBJ</font>
+(send an-obj :show) <font color="#008844">; returns object - STATE = NIL</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/keyword-isnew.htm b/docsrc/xlisp/xlisp-doc/reference/keyword-isnew.htm new file mode 100644 index 0000000..eb595bc --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/keyword-isnew.htm @@ -0,0 +1,96 @@ +<html><head><title>XLISP :isnew</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>:isnew</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>message selector</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlobj.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(send <i>object</i> :isnew <i>args</i>)</dt>
+<dd><i>object</i> - an existing object<br>
+<i>args</i> - the arguments to be passed to the init code<br>
+returns - the object</dd>
+</dl>
+
+<dl>
+<dt>(send <i>class</i> :isnew <i>ivars</i> [<i>cvars</i> [<i>superclass</i>]])</dt>
+<dd><i>class</i> - an existing XLISP class<br>
+<i>ivars</i> - list of instance variables for the new class<br>
+<i>cvars</i> - list of class variable symbols for the new class<br>
+<i>superclass</i> - superclass for the new object, default is
+<a href="object.htm">object</a><br>
+returns - the new class object</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The ':isnew' message selector causes an instance to run its
+initialization method. If an ':isnew' message is sent to a class, the class
+definition and state will be reset as specified in the arguments of the
+message.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq a-class (send class :new '(state))) <font color="#008844">; create a new class A-CLASS with STATE</font>
+
+(send a-class :answer :isnew '() <font color="#008844">; set up initialization</font>
+ '((setq state nil) self))
+
+(send a-class :answer :set-it '(value) <font color="#008844">; create :SET-IT message</font>
+ '((setq state value)))
+
+(setq an-obj (send a-class :new)) <font color="#008844">; create AN-OBJ out of A-CLASS</font>
+
+(send an-obj :show) <font color="#008844">; returns object - STATE = NIL</font>
+
+(send an-obj :set-it 5) <font color="#008844">; STATE is set to 5</font>
+(send an-obj :show) <font color="#008844">; returns object - STATE = 5</font>
+
+(SEND an-obj :ISNEW) <font color="#008844">; re-initialize AN-OBJ</font>
+(send an-obj :show) <font color="#008844">; returns object - STATE = NIL</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-010.htm#object-isnew">:isnew</a>
+message selector in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/keyword-mescape.htm b/docsrc/xlisp/xlisp-doc/reference/keyword-mescape.htm new file mode 100644 index 0000000..a0210f5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/keyword-mescape.htm @@ -0,0 +1,86 @@ +<html><head><title>XLISP :mescape</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>:mescape</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>keyword</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlread.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> :mescape</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>The ':mescape' keyword is an entry used in the
+<a href="global-readtable.htm">*readtable*</a> system variable that
+contains XLISP's data structures relating to the processing of characters
+from the user (or files) and read-macro expansions. The existance of the
+':mescape' keyword means that the specified character is to be used as a
+multiple escape character. The system defines that the the vertical bar
+character '|' is the only ':mescape' character.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+<font color="#008844">;; define a function to look in a table</font>
+<font color="#008844">;; and print out any :mescape character</font>
+
+(defun look-at (table)
+ (dotimes (ch 127)
+ (prog ((entry (aref table ch)))
+ (case entry
+ (:mescape (princ (int-char ch)))
+ (t nil))))
+ (terpri))
+
+(look-at *readtable*) <font color="#008844">; prints |</font>
+</pre>
+
+<p><b>Caution:</b> If you experiment with
+<nobr><a href="global-readtable.htm">*readtable*</a> ,</nobr> it is useful
+to save the old value in a variable, so that you can restore the system
+state.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-008.htm#mescape">:mescape</a>
+keyword in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/keyword-new.htm b/docsrc/xlisp/xlisp-doc/reference/keyword-new.htm new file mode 100644 index 0000000..deee953 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/keyword-new.htm @@ -0,0 +1,86 @@ +<html><head><title>XLISP :new</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>:new</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>message selector</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlobj.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(send <i>class</i> :new <i>args</i>)</dt>
+<dd><i>class</i> - an existing XLISP class except for <a href="class.htm">class</a><br>
+<i>args</i> - the initializing arguments for the new instance<br>
+returns - the new class object</dd>
+</dl>
+
+<dl>
+<dt>(send class :new <i>ivars</i> [<i>cvars</i> [<i>superclass</i>]])</dt>
+<dd><i>ivars</i> - list of instance variables for new class<br>
+<i>cvars</i> - list of class variable symbols for new class<br>
+<i>superclass</i> - superclass for new object, the default is <a href="object.htm">object</a><br>
+returns - the new class object</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The ':new' message selector exhibits two different behaviors. When you
+are creating an instance of a <a href="class.htm">class</a> you
+only need the ':new' message [consisting of the message selector and any
+data]. When you are creating a new <a href="class.htm">class</a>
+with ':new', you need to specify instance variables and optionally the
+<a href="class.htm">class</a> variables and superclass.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq new-class (send class :new '(state))) <font color="#008844">; create NEW-CLASS with STATE</font>
+(setq new-obj (send new-class :new)) <font color="#008844">; create NEW-OBJ of NEW-CLASS</font>
+(send new-obj :show) <font color="#008844">; shows the object</font>
+
+(setq sub-class (send class :new '(sub-state) <font color="#008844">; create SUB-CLASS of NEW-CLASS</font>
+ '() new-class))
+(send sub-class :show) <font color="#008844">; show the SUB-CLASS</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-010.htm#class-new">:new</a>
+message selector in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/keyword-nmacro.htm b/docsrc/xlisp/xlisp-doc/reference/keyword-nmacro.htm new file mode 100644 index 0000000..17732a2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/keyword-nmacro.htm @@ -0,0 +1,103 @@ +<html><head><title>XLISP :nmacro</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>:nmacro</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>keyword</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlread.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(:nmacro . <i>function</i>)</dt>
+<dd><i>function</i> - a function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>':nmacro' is an entry that is used in the
+<a href="global-readtable.htm">*readtable*</a> system variable that contains
+XLISP's data structures relating to the processing of characters from the
+user [or files] and read-macro expansions. The existance of the ':nmacro'
+keyword means that the specified character is the start of a non-terminal
+read macro. For ':nmacro', the form of the
+<a href="global-readtable.htm">*readtable*</a> entry is a dotted pair
+like:</p>
+
+<pre class="example">
+(:nmacro . <font color="#008844"><i>function</i></font>)
+</pre>
+
+<p>The 'function' can be a built-in read-macro function or a user defined
+lambda expression. The 'function' takes two parameters, an input stream
+specification, and an integer that is the character value. The 'function'
+should return <a href="nil.htm">NIL</a> if the character is
+'white-space' or a value <a href="cons.htm">cons</a>ed with
+<a href="nil.htm">NIL</a> to return the value. The 'function'
+will probably read additional characters from the input stream.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun look-at (table) <font color="#008844">; define a function to</font>
+ (dotimes (ch 127) <font color="#008844">; look in a table</font>
+ (prog ((entry (aref table ch))) <font color="#008844">; and print out any</font>
+ (if (and (consp entry) <font color="#008844">; :NMACRO entries</font>
+ (equal (car entry)
+ ':nmacro))
+ (princ (int-char ch)))))
+ (terpri))
+(look-at *readtable*) <font color="#008844">; prints #</font>
+</pre>
+
+<p><b>Note:</b> The system defines that the hash [#] character is a
+non-terminal. This is because the hash is used for a variety of 'read macro
+expansions' including <a href="function.htm">function</a>, an
+<a href="../misc/ascii-table.htm">ASCII</a> code, and hexadecimal
+numbers.</p>
+
+<p><b>Caution:</b> If you experiment with
+<nobr><a href="global-readtable.htm">*readtable*</a> ,</nobr> it is useful
+to save the old value in a variable, so that you can restore the system
+state.</p>
+
+<p>See the
+<a href="../manual/manual/xlisp-man-008.htm#nmacro">:nmacro</a>
+keyword in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/keyword-sescape.htm b/docsrc/xlisp/xlisp-doc/reference/keyword-sescape.htm new file mode 100644 index 0000000..44d98f9 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/keyword-sescape.htm @@ -0,0 +1,84 @@ +<html><head><title>XLISP :sescape</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>:sescape</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>keyword</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlread.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> :sescape</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>The ':sescape' keyword is an entry used in the
+<a href="global-readtable.htm">*readtable*</a> system variable that contains
+XLISP's data structures relating to the processing of characters from the
+user [or files] and read-macro expansions. The existance of the ':sescape'
+keyword means that the specified character is to be used as a single escape
+character. The system defines that the the backslash character '\' is the
+only defined ':sescape' character.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+<font color="#008844">;; define a function to look in a table</font>
+<font color="#008844">;; and print out any :SESCAPE character</font>
+
+(defun look-at (table)
+ (dotimes (ch 127)
+ (prog ((entry (aref table ch)))
+ (case entry
+ (:SESCAPE (princ (int-char ch)))
+ (t nil))))
+ (terpri))
+
+(look-at *readtable*) <font color="#008844">; prints \</font>
+</pre>
+
+<p><b>Caution:</b> If you experiment with *readtable*, it is useful to save
+the old value in a variable, so that you can restore the system state.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-008.htm#sescape">:sescape</a>
+keyword in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/keyword-show.htm b/docsrc/xlisp/xlisp-doc/reference/keyword-show.htm new file mode 100644 index 0000000..0700e31 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/keyword-show.htm @@ -0,0 +1,82 @@ +<html><head><title>XLISP :show</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>:show</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>message selector</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlobj.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(send <i>object</i> :show)</dt>
+<dd><i>object</i> - an existing <a href="object.htm">object</a><br>
+returns - the <i>object</i></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The ':show' message selector attempts to find the 'show' method in the
+specified <a href="object.htm">object</a>s class. Since the ':show'
+message selector is built-in in the root
+<a href="class.htm">class</a>, this is always a valid message
+selector. The <a href="object.htm">object</a> must already
+exist.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq my-class (send class :new '(state))) <font color="#008844">; create MY-CLASS with STATE</font>
+
+(send my-class :answer :isnew '() <font color="#008844">; set up initialization</font>
+ '((setq state nil) self))
+
+(send my-class :answer :set-it '(value) <font color="#008844">; create :SET-IT message</font>
+ '((setq state value)))
+
+(setq my-obj (send my-class :new)) <font color="#008844">; create MY-OBJ of MY-CLASS</font>
+(send my-obj :show) <font color="#008844">; returns object state including STATE = NIL</font>
+(send my-obj :set-it 5) <font color="#008844">; STATE is set to 5</font>
+(send new-obj :show) <font color="#008844">; error: unbound variable</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-010.htm#object-show">:show</a>
+message selector in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/keyword-tmacro.htm b/docsrc/xlisp/xlisp-doc/reference/keyword-tmacro.htm new file mode 100644 index 0000000..d290d9d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/keyword-tmacro.htm @@ -0,0 +1,107 @@ +<html><head><title>XLISP :tmacro</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>:tmacro</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>keyword</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlread.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(:tmacro . <i>function</i>)</dt>
+<dd><i>function</i> - a function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>':tmacro' is an entry that is used in the
+<a href="global-readtable.htm">*readtable*</a> system variable that contains
+XLISP's data structures relating to the processing of characters from the
+user [or files] and read-macro expansions. The existance of the ':tmacro'
+keyword means that the specified character is the start of a terminal read
+macro. For ':tmacro', the form of the
+<a href="global-readtable.htm">*readtable*</a> entry is a dotted pair
+like:</p>
+
+<pre class="example">
+(:tmacro . <font color="#008844"><i>function</i></font>)
+</pre>
+
+<p>The 'function' can be a built-in read-macro function or a user defined
+lambda expression. The 'function' takes two parameters, an input stream
+specification, and an integer that is the character value. The 'function'
+should return <a href="nil.htm">NIL</a> if the character is
+'white-space' or a value <a href="cons.htm">cons</a>ed with
+<a href="nil.htm">NIL</a> to return the value. The 'function'
+will probably read additional characters from the input stream.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun look-at (table) <font color="#008844">; define a function to look in a table</font>
+ (dotimes (ch 127) <font color="#008844">; and print out any :TMACRO entries</font>
+ (prog ((entry (aref table ch)))
+ (if (and (consp entry)
+ (equal (car entry) ':TMACRO))
+ (princ (int-char ch)))))
+ (terpri))
+
+(look-at *readtable*) <font color="#008844">; prints "'(),;`</font>
+</pre>
+
+<p><b>Note:</b> The system defines that the following are ':tmacro'
+characters:</p>
+
+<pre>
+ \ " ` , ( ) ;
+</pre>
+
+<p>[backslash, double quote, backquote, comma, opening parenthesis, closing
+parenthesis, semicolon.]</p>
+
+<p><b>Caution:</b> If you experiment with
+<nobr><a href="global-readtable.htm">*readtable*</a> ,</nobr> it is useful
+to save the old value in a variable, so that you can restore the system
+state.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-008.htm#tmacro">:tmacro</a>
+keyword in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/keyword-white-space.htm b/docsrc/xlisp/xlisp-doc/reference/keyword-white-space.htm new file mode 100644 index 0000000..be3fed0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/keyword-white-space.htm @@ -0,0 +1,92 @@ +<html><head><title>XLISP :white-space</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>:white-space</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>keyword</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlread.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> :white-space</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>The ':white-space' keyword is an entry that is used in the <a
+href="global-readtable.htm">*readtable*</a> system variable that contains
+XLISP's data structures relating to the processing of characters from the
+user [or files] and read-macro expansions. The existance of the
+':white-space' keyword means that the specified character may be skipped
+over. The system defines that 'tab', 'space', 'return' and 'line-feed' are
+':white-space' characters.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+<font color="#008844">;; define a function to look in a table</font>
+<font color="#008844">;; and print out any white-space characters</font>
+
+(defun look-at (table)
+ (dotimes (ch 127)
+ (prog ((entry (aref table ch)))
+ (case entry
+ (nil nil)
+ (:constituent nil)
+ (:white-space (print ch))
+ (t nil))))
+ (terpri))
+
+(look-at *readtable*) <font color="#008844">; prints 9 - tab</font>
+ <font color="#008844">; 10 - newline</font>
+ <font color="#008844">; 12 - formfeed</font>
+ <font color="#008844">; 13 - return</font>
+ <font color="#008844">; 32 - space</font>
+</pre>
+
+<p><b>Caution:</b> If you experiment with
+<nobr><a href="global-readtable.htm">*readtable*</a> ,</nobr> it is useful
+to save the old value in a variable, so that you can restore the system
+state.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-008.htm#white-space">:white-space</a>
+keyword in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/keywordp.htm b/docsrc/xlisp/xlisp-doc/reference/keywordp.htm new file mode 100644 index 0000000..dc49926 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/keywordp.htm @@ -0,0 +1,78 @@ +<html><head><title>XLISP keywordp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>keywordp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp function (closure)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>sal-parse.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(keywordp <i>expr</i>)</nobr></dt>
+<dd><i>expr</i> - an arbitrary Lisp expression<br>
+returns - <a href="t.htm"> T </a> if the expression is a keyword symbol, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">keywordp</font> (s)
+ (and (symbolp s)
+ (eq (type-of (symbol-name s)) 'string)
+ (equal (char (symbol-name s) 0) #\:)))
+</pre>
+
+<h2>Description</h2>
+
+<p>The 'keywordp' function tests if a lisp expression is a keyword symbol.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(keywordp :a) => T
+(keywordp :B) => T
+(keywordp 'c) => NIL
+(keywordp "d") => NIL
+(keywordp #\e) => NIL
+(keywordp 123) => NIL
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/labels.htm b/docsrc/xlisp/xlisp-doc/reference/labels.htm new file mode 100644 index 0000000..16fbc3c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/labels.htm @@ -0,0 +1,101 @@ +<html><head><title>XLISP labels</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>labels</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(labels ([<i>function</i> ... ]) <i>expr</i> ... )</dt>
+<dd><i>function</i> - a function definition binding which is of the form:<br>
+<dl><dd>(<i>symbol arg-list body</i>)</dd>
+<dl><dd><i>symbol</i> - the symbol specifying the function name<br>
+<i>arg-list</i> - the argument list for the function<br>
+<i>body</i> - the body of the function</dd></dl></dl>
+<i>expr</i> - an expression<br>
+returns - the value of the last expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'labels' special form is basically a local block construct that
+allows local 'function' definitions followed by a block of code to evaluate.
+The first form after the labels is the 'binding' form. It contains a series
+of 'functions'. 'labels' allows the'functions' to be defined in a mutually
+recursive manner. [The similar <a href="flet.htm">flet</a> form
+does not allow this.] The 'labels' form will go through and define the
+'symbols' of the 'functions' and then sequentially execute the 'exprs'. The
+value of the last 'expr' evaluated is returned. When the 'labels' is
+finished execution, the 'symbols' that were defined will no longer
+exist.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(labels ((fuzz (x) (+ x x))) <font color="#008844">; a LABELS with a local function FUZZ</font>
+ (fuzz 2)) <font color="#008844">; returns 4</font>
+
+ <font color="#008844">; FUZZ no longer exists</font>
+(fuzz 2) <font color="#008844">; error: unbound function - FUZZ</font>
+
+ <font color="#008844">; an empty LABELS</font>
+(labels () (print 'a)) <font color="#008844">; prints A</font>
+
+ <font color="#008844">; LABELS form including</font>
+(labels ((inc (arg) (est arg)) <font color="#008844">; INC definition using EST</font>
+ (est (var) (* .1 var))) <font color="#008844">; EST definition</font>
+ (inc 99) ) <font color="#008844">; returns 9.9</font>
+
+ <font color="#008844">; FLET form including</font>
+(flet ((inc (arg) (est arg)) <font color="#008844">; INC definition using EST</font>
+ (est (var) (* .1 var))) <font color="#008844">; EST definition</font>
+ (inc 99) <font color="#008844">; error: unbound function - EST</font>
+</pre>
+
+<p><b>Note:</b> <a href="flet.htm">flet</a> does not allow
+recursive definitions of functions. The 'label' special form does allow
+this.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-019.htm#labels">labels</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/lambda-keyword-aux.htm b/docsrc/xlisp/xlisp-doc/reference/lambda-keyword-aux.htm new file mode 100644 index 0000000..b3c5324 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/lambda-keyword-aux.htm @@ -0,0 +1,116 @@ +<html><head><title>XLISP &aux</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>&aux</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>keyword</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xleval.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><b>&aux</b> [<i>aux-var</i> | (<i>aux-var aux-value</i>)] ...</dt>
+<dd><i>aux-var</i> - auxiliary variable<br>
+<i>aux-value</i> - auxiliary variable initialization</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p> In XLISP, there are several times that you define a formal argument list
+for a body of code [like <a href="defun.htm">defun</a>,
+<a href="defmacro.htm">defmacro</a>,
+<a href="keyword-answer.htm">:answer</a> and <a
+href="lambda.htm">lambda</a>]. <nobr>The 'aux-var'</nobr> variables are a
+mechanism for you to define variables local to the function or operation
+definition. <nobr>If there</nobr> is an optional <nobr>'aux-value'</nobr>,
+they will be set to that value on entry to the body of code. Otherwise, they
+are initialized <nobr>to <a href="nil.htm">NIL</a></nobr>. <nobr>At
+the</nobr> end of the function or operation execution, these local symbols
+and their values are removed.</p>
+
+<h2>Examples</h2>
+
+<p>A function '<nobr>my-add</nobr>' with <nobr>one required</nobr> argument
+'num1', <nobr>one <a href="lambda-keyword-rest.htm">&rest</a></nobr>
+argument <nobr>'num-list'</nobr>, and <nobr>one &aux</nobr>
+<nobr>variable 'sum'</nobr>:</p>
+
+<pre class="example">
+(defun my-add (num1 &rest num-list &aux sum)
+ (setq sum num1) <font color="#008844">; initialize SUM</font>
+ (dolist (i num-list) <font color="#008844">; loop through the num-list</font>
+ (setq sum (+ sum i))) <font color="#008844">; add each number to SUM</font>
+ sum) <font color="#008844">; return SUM when finished</font>
+
+(my-add 1 2 3 4) => 10
+(my-add 5 5 5 5 5) => 25
+</pre>
+
+<p>See <nobr><a href="addition.htm"> + </a></nobr>,
+<a href="defun.htm">defun</a>, <a href="dolist.htm">dolist</a>,
+<a href="lambda-keyword-rest.htm">&rest</a>,
+<a href="setq.htm">setq</a>.</p>
+
+<p>A function '<nobr>more-keys</nobr>' with <nobr>one required</nobr>
+<nobr>argument 'a'</nobr> and <nobr>three &aux</nobr> variables <nobr>'b'
+[initialized</nobr> <nobr>to <a href="nil.htm">NIL</a>]</nobr>, <nobr>'c'
+[initialized</nobr> <nobr>to 99]</nobr>, and <nobr>'d' [initialized</nobr>
+<nobr>to <a href="t.htm"> T </a>]</nobr>:</p>
+
+<pre class="example">
+(defun more-keys (a &aux b (c 99) (d t))
+ (format t "a=~a b=~a c=~a d=~a~%" a b c d))
+
+> (more-keys "hi")
+a=hi b=NIL c=99 d=T
+NIL
+</pre>
+
+<p>See <a href="defun.htm">defun</a>, <a href="format.htm">format</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr><a href="../manual/xlisp.htm#auxiliary-variables">Auxiliary Variables</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/lambda-keyword-key.htm b/docsrc/xlisp/xlisp-doc/reference/lambda-keyword-key.htm new file mode 100644 index 0000000..b9062d2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/lambda-keyword-key.htm @@ -0,0 +1,132 @@ +<html><head><title>XLISP &key</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>&key</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>keyword</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xleval.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>&key <i>key-arg</i> ...<br>
+&key (<i>key-arg</i> [<i>key-value</i> [<i>supplied-p-var</i>]]) ...<br>
+&key ((<i>key-symbol key-arg</i>) [<i>key-value</i> [<i>supplied-p-var</i>]]) ...</dt>
+<dd><i>key-arg</i> - keyword argument<br>
+<i>key-symbol</i> - keyword argument symbol<br>
+<i>key-value</i> - keyword argument initialization<br>
+<i>supplied-p-var</i> - argument existence variable</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>In XLISP, there are several times that you define a formal argument list
+for a body of code [like
+<nobr><a href="defun.htm">defun</a> ,</nobr>
+<nobr><a href="defmacro.htm">defmacro</a> ,</nobr>
+<a href="keyword-answer.htm">:answer</a> and
+<a href="lambda.htm">lambda</a>].
+All of the formal arguments that are defined are required to appear in the
+invocation of the defined function or operation. If there are any
+<a href="lambda-keyword-optional.htm">&optional</a> arguments defined, they will
+be filled in order.</p>
+
+<p>There are other optional arguments called 'keyword' arguments. These
+arguments are not position dependent but can be specified in any order by a
+preceding keyword [a symbol with a leading colon ':']. If there is no
+'key-symbol' specified in the argument list, the keyword will be constructed
+from the 'key-arg' name by adding a leading colon ':'. For example a
+'key-arg' of 'furter' will generate a keyword symbol of ':furter'.</p>
+
+<p>Like the <a href="lambda-keyword-optional.htm">&optional</a> arguments, there
+can be initialization values provided via the 'key-value' argument. If there
+is no 'key-value' argument and no value is provided by the function call,
+the 'key-arg' value will be <a href="nil.htm">NIL</a>.</p>
+
+<p>The 'supplied-p-var', if it is specified, will contain a
+<a href="t.htm"> T </a> if the 'key-arg' value was
+supplied by the function call and a <a href="nil.htm">NIL</a> if
+it was not supplied by the function call. This 'supplied-p-var' allows the
+programmer to test for an argument's existence. At the end of the function
+or operation execution, these local symbols and their values are are
+removed.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun foo (a &key b c)
+ (print a) (print b) (print c))
+
+(foo) <font color="#008844">; error: too few arguments</font>
+(foo 1) <font color="#008844">; prints 1 NIL NIL</font>
+(foo 1 2) <font color="#008844">; prints 1 NIL NIL</font>
+(foo 1 :b 2 :c 3) <font color="#008844">; prints 1 2 3</font>
+(foo 1 :c 3 :b 2) <font color="#008844">; prints 1 2 3</font>
+(foo 1 :b 3 :b 2) <font color="#008844">; prints 1 3 NIL</font>
+
+(defun fee (a &key (b 9 b-passed))
+ (print a) (print b)
+ (if b-passed (print "b was passed")
+ (print "b not passed")))
+
+(fee) <font color="#008844">; error: too few arguments</font>
+(fee 1) <font color="#008844">; prints 1 9 "b not passed"</font>
+(fee 1 2) <font color="#008844">; prints 1 9 "b not passed"</font>
+(fee 1 :b 2) <font color="#008844">; prints 1 2 "b was passed"</font>
+
+(defun fi (a &key ((:mykey b) 9 b-passed))
+ (print a) (print b)
+ (if b-passed (print "b was passed")
+ (print "b not passed")))
+
+(fi) <font color="#008844">; error: too few arguments</font>
+(fi 1) <font color="#008844">; prints 1 9 "b not passed"</font>
+(fi 1 2) <font color="#008844">; prints 1 9 "b not passed"</font>
+(fi 1 :b 2) <font color="#008844">; prints 1 9 "b not passed"</font>
+(fi 1 :mykey 2) <font color="#008844">; prints 1 2 "b was passed"</font>
+</pre>
+
+<p><b>Note:</b> There is a '&allow-other-keys' keyword in XLISP and
+Common Lisp. In the case of XLISP, this keyword is extraneous since the
+default for keyword arguments is to allow other keys (without errors).</p>
+
+<p>See the
+<a href="../manual/xlisp-man-009.htm#9-1-4">&key</a>
+keyword in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/lambda-keyword-optional.htm b/docsrc/xlisp/xlisp-doc/reference/lambda-keyword-optional.htm new file mode 100644 index 0000000..1b746d0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/lambda-keyword-optional.htm @@ -0,0 +1,98 @@ +<html><head><title>XLISP &optional</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>&optional</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>keyword</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xleval.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>&optional [<i>opt-arg</i> | (<i>opt-arg</i> [<i>opt-value</i> [<i>supplied-p</i>]])] ...</dt>
+<dd><i>opt-arg</i> - optional argument<br>
+<i>opt-value</i> - optional argument initialization value<br>
+<i>supplied-p</i> - optional argument existence variable</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>In XLISP, there are several times that you define a formal argument list
+for a body of code like
+<nobr><a href="defun.htm">defun</a> ,</nobr>
+<nobr><a href="defmacro.htm">defmacro</a> ,</nobr>
+<a href="keyword-answer.htm">:answer</a> and
+<a href="lambda.htm">lambda</a>. All of the formal arguments
+that are defined are required to appear in the invocation of the defined
+function or operation. If there are any '&optional' arguments defined,
+they will be filled in order. If there are insufficient parameters for the
+'&optional' arguments, they will contain
+<nobr><a href="nil.htm">NIL</a> ,</nobr> unless the arguments
+have an 'opt-value' initial value specified. The 'supplied-p' variable, if
+specified, will contain <a href="t.htm"> T </a> if
+the 'opt-arg' was supplied by the function call and
+<a href="nil.htm">NIL</a> if it was not supplied by the function
+call. This 'supplied-p' variable allows the programmer to test for an
+arguments existence. At the end of the function or operation execution,
+these local symbols and their values are are removed.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun foo <font color="#008844">; define function FOO</font>
+ (a &optional b (c 1) ) <font color="#008844">; with some optional args</font>
+ (print a) (print b) (print c))
+(foo) <font color="#008844">; error: too few arguments</font>
+(foo 1) <font color="#008844">; prints 1 NIL 1</font>
+(foo 1 2) <font color="#008844">; prints 1 2 1</font>
+(foo 1 2 3) <font color="#008844">; prints 1 2 3</font>
+
+(defun fee <font color="#008844">; define function FEE</font>
+ (a &optional (b 9 b-passed) ) <font color="#008844">; with some optional args</font>
+ (print a) (print b)
+ (if b-passed (print "b was passed")
+ (print "b not passed")))
+(fee 1) <font color="#008844">; prints 1 9 "b not passed"</font>
+(fee 1 2) <font color="#008844">; prints 1 2 "b was passed"</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-009.htm#9-1-2">&optional</a>
+keyword in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/lambda-keyword-rest.htm b/docsrc/xlisp/xlisp-doc/reference/lambda-keyword-rest.htm new file mode 100644 index 0000000..639465d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/lambda-keyword-rest.htm @@ -0,0 +1,104 @@ +<html><head><title>XLISP &rest</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>&rest</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>keyword</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xleval.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>&rest [<i>rest-arg</i>]</dt>
+<dd><i>rest-arg</i> - rest argument symbol</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>In XLISP, there are several times that you define a formal argument list
+for a body of code like
+<nobr><a href="defun.htm">defun</a> ,</nobr>
+<nobr><a href="defmacro.htm">defmacro</a> ,</nobr>
+<a href="keyword-answer.htm">:answer</a> and
+<a href="lambda.htm">lambda</a>. All of the formal arguments that
+are defined are required to appear in the invocation of the defined function
+or operation. If there are any
+<a href="lambda-keyword-optional.htm">&optional</a> arguments defined, they will
+be filled in order. If there is a '&rest' argument defined, and all
+the required formal arguments and
+<a href="lambda-keyword-optional.htm">&optional</a> arguments are filled, any and
+all further parameters will be passed into the function via the 'rarg'
+argument. There can be only one 'rest-arg' argument for '&rest'. If
+there are insufficient parameters for any of the
+<a href="lambda-keyword-optional.htm">&optional</a> or '&rest' arguments,
+they will contain <a href="nil.htm">NIL</a>. At the end of the
+function or operation execution, these local symbols and their values are
+removed.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun foo <font color="#008844">; define function FOO</font>
+ (a b &optional c d &rest e) <font color="#008844">; with some of each argument</font>
+ (print a) (print b)
+ (print c) (print d) <font color="#008844">; print out each</font>
+ (print e))
+(foo) <font color="#008844">; error: too few arguments</font>
+(foo 1) <font color="#008844">; error: too few arguments</font>
+(foo 1 2) <font color="#008844">; prints 1 2 NIL NIL NIL</font>
+(foo 1 2 3) <font color="#008844">; prints 1 2 3 NIL NIL</font>
+(foo 1 2 3 4) <font color="#008844">; prints 1 2 3 4 NIL</font>
+(foo 1 2 3 4 5) <font color="#008844">; prints 1 2 3 4 (5)</font>
+(foo 1 2 3 4 5 6 7 8 9) <font color="#008844">; prints 1 2 3 4 (5 6 7 8 9)</font>
+
+(defun my-add <font color="#008844">; define function MY-ADD</font>
+ (num1 &rest num-list &aux sum) <font color="#008844">; with 1 arg, rest, 1 aux var</font>
+ (setq sum num1) <font color="#008844">; clear SUM</font>
+ (dotimes (i (length num-list) ) <font color="#008844">; loop through rest list</font>
+ (setq sum (+ sum (car num-list))) <font color="#008844">; add the number to sum</font>
+ (setq num-list (cdr num-list))) <font color="#008844">; and remove num from list</font>
+ sum) <font color="#008844">; return sum when finished</font>
+(my-add 1 2 3 4) <font color="#008844">; returns 10</font>
+(my-add 5 5 5 5 5) <font color="#008844">; returns 25</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-009.htm#9-1-3">&rest</a>
+keyword in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/lambda.htm b/docsrc/xlisp/xlisp-doc/reference/lambda.htm new file mode 100644 index 0000000..6f656a2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/lambda.htm @@ -0,0 +1,109 @@ +<html><head><title>XLISP lambda</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>lambda</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(lambda <i>arg-list</i> [<i>body</i>])</dt>
+<dd><i>arg-list</i> - a list of the formal arguments to the function of the form:<br>
+<dl>
+<dd>([<i>arg1</i> ... ]<br>
+ [<a href="lambda-keyword-optional.htm">&optional</a> <i>oarg1</i> ... ]<br>
+ [<a href="lambda-keyword-rest.htm">&rest</a> <i>rarg</i>]<br>
+ [<a href="lambda-keyword-key.htm">&key</a> ... ]<br>
+ [<a href="lambda-keyword-aux.htm">&aux</a> <i>aux1</i> ... ])</dd>
+</dl>
+<i>body</i> - a series of LISP forms (expressions) that are executed in order<br>
+returns - the function closure</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The LAMBDA special form returns a function definition [an executable
+function] that has no name. All of the 'argN' formal arguments that are
+defined are required to appear in a call to the defined function. If there
+are any <a href="lambda-keyword-optional.htm">&optional</a> arguments defined,
+they will be filled in order. If there is a
+<a href="lambda-keyword-rest.htm">&rest</a> argument defined, and all the
+required formal arguments and <a href="lambda-keyword-optional.htm">&optional</a>
+arguments are filled, any and all further parameters will be passed into the
+function via the 'rarg' argument. Note that there can be only one 'rarg'
+argument for <a href="lambda-keyword-rest.htm">&rest</a>. If there are
+insufficient parameters for any of the
+<a href="lambda-keyword-optional.htm">&optional</a> or
+<a href="lambda-keyword-rest.htm">&rest</a> arguments, they will contain
+<a href="nil.htm">NIL</a>. The
+<a href="lambda-keyword-aux.htm">&aux</a> variables are a mechanism for you
+to define variables local to the function definition. At the end of the
+function execution, these local symbols and their values are are
+removed.</p>
+
+<p>Read also the chapter about
+<nobr><a href="../manual/xlisp-man-009.htm">lambda lists</a></nobr>
+in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(funcall (lambda (a b) (* a b)) 4 8 ) <font color="#008844">; evaluate a lambda function</font>
+ <font color="#008844">; returns 32</font>
+
+(funcall (lambda '(a b) (+ a b)) 1 2) <font color="#008844">; evaluate another function</font>
+ <font color="#008844">; returns 3</font>
+
+(funcall (lambda (a b) <font color="#008844">; evaluate a more complex function</font>
+ (print "a no-name fnc") <font color="#008844">; prints "a no-name fnc"</font>
+ (* a b)) 3 8) <font color="#008844">; and returns 24</font>
+</pre>
+
+<p><b>Note:</b> Using a <a href="setq.htm">setq</a> on a 'lambda'
+expression is not the same as a <a href="defun.htm">defun</a>. A
+<a href="setq.htm">setq</a> on a 'lambda' will give the
+variable the value of the 'lambda' closure. This does not mean that the
+variable name can be used as a function.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-012.htm#lambda">lambda</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/last.htm b/docsrc/xlisp/xlisp-doc/reference/last.htm new file mode 100644 index 0000000..6abb312 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/last.htm @@ -0,0 +1,75 @@ +<html><head><title>XLISP last</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>last</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(last <i>list-expr</i>)</dt>
+<dd><i>list-expr</i> - a list or list expression<br>
+returns - the last list node in the list</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'last' function returns a list containing the last node or element of
+a list. If the last node is a sub-list, this is returned unaffected.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(last NIL) <font color="#008844">; returns NIL</font>
+(last 'a) <font color="#008844">; error: bad argument type</font>
+(last '(A)) <font color="#008844">; returns (A)</font>
+(last '(A B C D E)) <font color="#008844">; returns (E)</font>
+(last '( A (B C) (D E (F)))) <font color="#008844">; returns ((D E (F)))</font>
+
+(setq children '(junie vicki cindy chris))
+
+(last children) <font color="#008844">; returns (CHRIS)</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#last">last</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/length.htm b/docsrc/xlisp/xlisp-doc/reference/length.htm new file mode 100644 index 0000000..119d838 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/length.htm @@ -0,0 +1,74 @@ +<html><head><title>XLISP length</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>length</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(length <i>expr</i>)</dt>
+<dd><i>expr</i> - a list expression or string expression<br>
+returns - the length of the list, array or string</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'length' function returns the length of the 'expr'. If the 'expr' is
+a string, the number of characters is returned. If the 'expr' is a list, the
+number of top level elements [atoms or sublists] is returned. If the list is
+<nobr><a href="nil.htm">NIL</a> ,</nobr> a '0' is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(length NIL) <font color="#008844">; returns 0</font>
+(length 'a) <font color="#008844">; error: bad argument type</font>
+(length '(a)) <font color="#008844">; returns 1</font>
+(length '(1 2 3 4 5 6)) <font color="#008844">; returns 6</font>
+(length '(a (b c) (d (e) f) g)) <font color="#008844">; returns 4</font>
+(length "12345") <font color="#008844">; returns 5</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#length">length</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/let-star.htm b/docsrc/xlisp/xlisp-doc/reference/let-star.htm new file mode 100644 index 0000000..f6ac98a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/let-star.htm @@ -0,0 +1,106 @@ +<html><head><title>XLISP let*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>let*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(let* ([<i>binding</i> ... ]) <i>expr</i> ... )</dt>
+<dd><i>binding</i> - a variable binding which is one of the forms:
+<dl>
+<dd><i>symbol</i><br>
+(<i>symbol init-expr</i>)
+<dl>
+<dd><i>symbol</i> - a symbol<br>
+<i>init-expr</i> - an initialization expression for <i>symbol</i></dd>
+</dl></dd></dl>
+<i>expr</i> - an expression<br>
+returns - the value of the last expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'let*' special form is basically a local block construct that
+contains symbols [with optional initializations] and a block of code
+[expressions] to evaluate. The first form after the 'let*' is the 'binding'
+form. It contains a series of 'symbols' or 'bindings'. The 'binding' is a
+'symbol' followed by an initialization expression 'init-expr'. If there is
+no 'init-expr', the 'symbol' will be initialized to
+<a href="nil.htm">NIL</a>. The execution of the bindings will
+occur from the first to the last binding. The 'let*' form will go through
+and create and initialize the symbols and then sequentially execute the
+'exprs'. The value of the last 'expr' evaluated is returned. When the 'let*'
+is finished execution, the 'symbols' that were defined will no longer exist
+or retain their values.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(let* (x y z) <font color="#008844">; LET* with local vars</font>
+ (print x) (print y) (print z)) <font color="#008844">; prints NIL NIL NIL</font>
+
+(let* ((a 1) (b 2) (c 3)) <font color="#008844">; LET* with local vars & init</font>
+ (print (+ a b c))) <font color="#008844">; prints and returns 6</font>
+
+(let* ((a 1) (b 2) (c (+ a b))) <font color="#008844">; LET* with local vars & init</font>
+ (print (+ a b c))) <font color="#008844">; prints and returns 6</font>
+</pre>
+
+<p><b>Note:</b></p>
+
+<pre class="example">
+(let* (a b) ... )
+</pre>
+
+<p>can be understood as:</p>
+
+<pre class="example">
+(let (a)
+ (let (b)
+ ... ))
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-019.htm#let*">let*</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/let.htm b/docsrc/xlisp/xlisp-doc/reference/let.htm new file mode 100644 index 0000000..442fecf --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/let.htm @@ -0,0 +1,94 @@ +<html><head><title>XLISP let</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>let</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(let ([<i>binding</i> ... ]) <i>expr</i> ... )</dt>
+<dd><i>binding</i> - a variable binding which is one of the forms:
+<dl>
+<dd><i>symbol</i><br>
+(<i>symbol init-expr</i>)
+<dl>
+<dd><i>symbol</i> - a symbol<br>
+<i>init-expr</i> - an initialization expression for <i>symbol</i></dd>
+</dl></dd></dl>
+<i>expr</i> - an expression<br>
+returns - the value of the last expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'let' special form is basically a local block construct that contains
+symbols [with optional initializations] and a block of code [expressions] to
+evaluate. The first form after the 'let' is the 'binding' form. It contains
+a series of 'symbols' or 'bindings'. The 'binding' is a 'symbol' followed by
+an initialization expression 'init-expr'. If there is no 'init-expr', the
+'symbol' will be initialized to <a href="nil.htm">NIL</a>. There
+is no specification as to the order of execution of the bindings. The 'let'
+form will go through and create and initialize the symbols and then
+sequentially execute the 'exprs'. The value of the last 'expr' evaluated is
+returned. When the 'let' is finished execution, the 'symbols' that were
+defined will no longer exist or retain their values.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(let (x y z) <font color="#008844">; LET with local vars</font>
+ (print x) (print y) (print z)) <font color="#008844">; prints NIL NIL NIL</font>
+
+(let ((a 1) (b 2) (c 3)) <font color="#008844">; LET with local vars & init</font>
+ (print (+ a b c))) <font color="#008844">; prints and returns 6</font>
+
+(let ((a 1) (b 2) (c (+ a b))) <font color="#008844">; LET with local vars & init</font>
+ (print (+ a b c))) <font color="#008844">; error: unbound variable - A</font>
+</pre>
+
+<p><b>Note:</b> to make the last example work you need the
+<a href="let-star.htm">let*</a> special form.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-019.htm#let">let</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/list.htm b/docsrc/xlisp/xlisp-doc/reference/list.htm new file mode 100644 index 0000000..c62588d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/list.htm @@ -0,0 +1,74 @@ +<html><head><title>XLISP list</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>list</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(list [<i>expr1</i> ... ])</dt>
+<dd><i>exprN</i> - an expression<br>
+returns - the new list</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'list' function takes the expressions and constructs a list out of
+them. This constructed list is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(list) <font color="#008844">; returns NIL</font>
+(list nil) <font color="#008844">; returns (NIL)</font>
+(list 'a) <font color="#008844">; returns (A)</font>
+(list 'a 'b) <font color="#008844">; returns (A B)</font>
+(list 'a 'b 'c) <font color="#008844">; returns (A B C)</font>
+(list 'a 'b nil) <font color="#008844">; returns (A B NIL)</font>
+(list '(a b) '(c d) '( (e f) )) <font color="#008844">; returns ((A B) (C D) ((E F)))</font>
+(list (+ 1 2) (+ 3 4)) <font color="#008844">; returns (3 7)</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#list">list</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/listdir.htm b/docsrc/xlisp/xlisp-doc/reference/listdir.htm new file mode 100644 index 0000000..c155abe --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/listdir.htm @@ -0,0 +1,67 @@ +<html><head><title>XLISP listdir</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>listdir</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(<b>listdir</b> <i>path</i>)</dt>
+<dd><i>path</i> - the path of the directory to be listed<br>
+returns - list of filenames in the directory</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'listdir' function returns a list with all filenames in the directory
+or <a href="nil.htm">NIL</a> if the directory could not be found.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(let ((filenames (sort (listdir ".") #'string-lessp)))
+ (dolist (filename filenames)
+ (print filename)))
+</pre>
+
+<p>See also <a href="setdir.htm">setdir</a>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/listp.htm b/docsrc/xlisp/xlisp-doc/reference/listp.htm new file mode 100644 index 0000000..21fd92c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/listp.htm @@ -0,0 +1,92 @@ +<html><head><title>XLISP listp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>listp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(listp <i>expr</i>)</dt>
+<dd><i>expr</i> - the expression to check<br>
+returns - <a href="t.htm"> T </a> if the value is a
+list or <nobr><a href="nil.htm">NIL</a> ,</nobr>
+<a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'listp' predicate function checks if the 'expr' is a list.
+<a href="t.htm"> T </a> is returned if 'expr' is a
+list or an empty list [the <a href="nil.htm">NIL</a> value],
+<a href="nil.htm">NIL</a> is returned otherwise.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(listp '(a b)) <font color="#008844">; returns T - list</font>
+(listp nil) <font color="#008844">; returns T - NIL</font>
+(listp '(a . b)) <font color="#008844">; returns T - dotted pair list</font>
+
+(listp (lambda (x) (print x))) <font color="#008844">; returns NIL - closure - lambda</font>
+(listp #(1 2 3)) <font color="#008844">; returns NIL - array</font>
+(listp *standard-output*) <font color="#008844">; returns NIL - stream</font>
+(listp 1.2) <font color="#008844">; returns NIL - float</font>
+(listp #'quote) <font color="#008844">; returns NIL - fsubr</font>
+(listp 1) <font color="#008844">; returns NIL - integer</font>
+(listp object) <font color="#008844">; returns NIL - object</font>
+(listp "str") <font color="#008844">; returns NIL - string</font>
+(listp #'car) <font color="#008844">; returns NIL - subr</font>
+(listp 'a) <font color="#008844">; returns NIL - symbol</font>
+</pre>
+
+<p><b>Note:</b> <a href="nil.htm">NIL</a> or '() is used in many
+places as a list-class or atom-class expression. Both
+<a href="atom.htm">atom</a> and 'listp', when applied to
+<nobr><a href="nil.htm">NIL</a> ,</nobr> return
+<a href="t.htm"> T </a>. If you wish to check
+for a non-empty list, use the <a href="consp.htm">consp</a>
+predicate function.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#listp">listp</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/load.htm b/docsrc/xlisp/xlisp-doc/reference/load.htm new file mode 100644 index 0000000..627dccd --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/load.htm @@ -0,0 +1,162 @@ +<html><head><title>XLISP load</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>load</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlsys.c, xlread.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(load <i>file</i> [:verbose <i>v-flag</i>] [:print <i>p-flag</i>]))</dt>
+<dd><i>file</i> - a string expression or symbol<br>
+<i>v-flag</i> - an optional key-word expression, default is
+<a href="t.htm"> T </a><br>
+<i>p-flag</i> - an optional key-word expression, default is
+<a href="nil.htm">NIL</a><br>
+returns - the filename</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'load' function opens the 'file', reads and evaluates all the forms
+within the 'file'. 'file' may be a string expression or a symbol. When
+'file' is a string, you may specify a complete file location or extensions
+like "/usr/local/bin/myfile.lsp" or "A:\LISP\TIM.LSP".
+If 'file' is a string and includes a file type or an extension [like
+".lsp"], then 'load' accesses the specified file. If there is no
+extension on 'file', it will add ".lsp". If the ':verbose' keyword
+is present and 'v-flag' is
+<nobr>non-<a href="nil.htm">NIL</a> ,</nobr> a load message of
+the form:</p>
+
+<pre class="example">
+; loading "xxxx.lsp"
+</pre>
+
+<p>will be printed to <a href="global-standard-output.htm">*standard-output*</a>.
+If the ':print' keyword is present and 'p-flag' is
+<nobr>non-<a href="nil.htm">NIL</a> ,</nobr> the resulting value
+of each top-level form in 'file' will be printed to
+<a href="global-standard-output.htm">*standard-output*</a>. If the file load was
+successful, then <a href="t.htm"> T </a> is returned
+as the result. If the file load was not successful, a
+<a href="nil.htm">NIL</a> is returned.</p>
+
+<p><b>Note:</b> in Nyquist, the XLISP 'load' function first tries to load a
+file from the current directory. <nobr>A '.lsp'</nobr> extension is added if
+there is not already an alphanumeric extension following a period. <nobr>If
+that</nobr> fails, XLISP searches the path, which is obtained from the
+XLISPPATH environment variable in Unix and
+HKEY_LOCAL_MACHINE\SOFTWARE\CMU\Nyquist\XLISPPATH under Win32.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(load 'gloop) <font color="#008844">; prints ; loading "GLOOP.lsp"</font>
+ <font color="#008844">; returns NIL there is no file</font>
+
+(defun foo (x) (print x)) <font color="#008844">; create a function</font>
+(savefun foo) <font color="#008844">; create a file FOO.lsp</font>
+
+(load 'foo) <font color="#008844">; prints ; loading "FOO.lsp"</font>
+ <font color="#008844">; returns T</font>
+
+(load 'foo :verbose NIL) <font color="#008844">; no printing returns T</font>
+
+(load 'foo :print T) <font color="#008844">; prints FOO returns T</font>
+
+(load 'save :verbose T :print T) <font color="#008844">; prints ; loading "FOO.lsp"</font>
+ <font color="#008844">; prints FOO returns T</font>
+
+(load "foo") <font color="#008844">; prints ; loading "foo.lsp"</font>
+ <font color="#008844">; returns NIL - didn't work</font>
+ <font color="#008844">; because the file is "FOO.lsp"</font>
+
+(load "FOO") <font color="#008844">; prints ; loading "FOO.lsp"</font>
+ <font color="#008844">; returns T - did work</font>
+
+(load "FOO.lsp") <font color="#008844">; prints ; loading "FOO.lsp"</font>
+ <font color="#008844">; returns T - did work</font>
+</pre>
+
+<p><b>File names:</b> In the PC and DOS world, all file names and extensions
+["foo.bat"] are automatically made uppercase. In using XLISP, this
+means you don't have to worry about whether the name is "foo.bat",
+"FOO.BAT" or even "FoO.bAt", they will all work.
+However, in other file systems [UNIX in particular], uppercase and lowercase
+do make a difference:</p>
+
+<p>This will create a file named FOO-FILE in UNIX, because XLISP uppercases
+its symbols:</p>
+
+<pre class="example">
+(open 'foo-file :direction :output)
+</pre>
+
+<p>This will create a file named 'foo-file' because UNIX doesn't
+uppercase its file names:</p>
+
+<pre class="example">
+(open "foo-file" :direction :output)
+</pre>
+
+<p>So, if you are having trouble with opening and accessing files, check to
+make sure the file name is in the proper case.</p>
+
+<p><b>Common Lisp:</b> Common Lisp has a 'load' function that is similar
+to XLISP's 'load'. The only difference is that Common Lisp uses an optional
+keyword parameter ':if-does-not-exist' which XLISP does not support.</p>
+
+<p><b>Nyquist:</b> in Nyquist, the XLISP 'load' function first tries to load
+a file from the current directory. A '.lsp' extension is added if there is
+not already an alphanumeric extension following a period. If that fails,
+XLISP searches the path, which is obtained from the XLISPPATH environment
+variable in Unix and HKEY_LOCAL_MACHINE\SOFTWARE\CMU\Nyquist\XLISPPATH under
+Win32. [The Macintosh version has no search path.]</p>
+
+<p><b>Note:</b> In XLISP, the keyword parameters are order sensitive. If
+both ':verbose' and ':print' keywords are used, ':verbose' must come
+first.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-031.htm#load">load</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/log.htm b/docsrc/xlisp/xlisp-doc/reference/log.htm new file mode 100644 index 0000000..98bfe25 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/log.htm @@ -0,0 +1,67 @@ +<html><head><title>XLISP log</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>log</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>sndfnint.c, sound.h</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>log</b> <i>number</i>)</dt>
+<dd><i>number</i> - a floating-point number<br>
+returns - the natural logarithm of <i>number</i></dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'log' function computes the natural logarithm of a
+<nobr>floating-point</nobr> number and returns the result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/logand.htm b/docsrc/xlisp/xlisp-doc/reference/logand.htm new file mode 100644 index 0000000..959f918 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/logand.htm @@ -0,0 +1,81 @@ +<html><head><title>XLISP logand</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>logand</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(logand <i>expr1</i> ... )</dt>
+<dd><i>expr</i> - an integer expression<br>
+returns - the result of the AND operation</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'logand' function returns the logical bitwise 'and' of the list of
+expressions. If there is only one argument, it is returned unaltered. If
+there are two or more arguments, the 'logand' function performs the logical
+and operation successively applying the bitwise operation.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(logand 0 0) <font color="#008844">; returns 0</font>
+(logand 0 1) <font color="#008844">; returns 0</font>
+(logand 1 0) <font color="#008844">; returns 0</font>
+(logand 1 1) <font color="#008844">; returns 1</font>
+(logand 55 #x0F) <font color="#008844">; returns 7</font>
+(logand 7 #b0011) <font color="#008844">; returns 3</font>
+(logand 1 2 4 8 16) <font color="#008844">; returns 0</font>
+(logand 15 7 3) <font color="#008844">; returns 3</font>
+</pre>
+
+<p><b>Note:</b> XLISP does not check when read-macro expansions like '#x0FF'
+are out of bounds. It gives no error message and will just truncate the
+number to the low-order bits that it can deal with [usually 32 bits or 8 hex
+digits].</p>
+
+<p>See the
+<a href="../manual/xlisp-man-024.htm#logand">logand</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/logior.htm b/docsrc/xlisp/xlisp-doc/reference/logior.htm new file mode 100644 index 0000000..d0e004a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/logior.htm @@ -0,0 +1,82 @@ +<html><head><title>XLISP logior</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>logior</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(logior <i>expr1</i> ... )</dt>
+<dd><i>exprN</i> - an integer expression<br>
+returns - the result of the Inclusive OR operation</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'logior' function returns the logical bitwise 'inclusive-or' of the
+list of expressions. If there is only one argument, it is returned
+unaltered. If there are two or more arguments, the 'logior' function
+performs the 'inclusive-or' successively applying the bitwise operation.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(logior 0 0) <font color="#008844">; returns 0</font>
+(logior 0 1) <font color="#008844">; returns 1</font>
+(logior 1 0) <font color="#008844">; returns 1</font>
+(logior 1 1) <font color="#008844">; returns 1</font>
+
+(logior 1 2 4 8 16 32 64) <font color="#008844">; returns 127</font>
+(logior 5 #b010) <font color="#008844">; returns 7</font>
+(logior 99 #x1FF) <font color="#008844">; returns 511</font>
+(logior 99 #x400) <font color="#008844">; returns 1123</font>
+</pre>
+
+<p><b>Note:</b> XLISP does not check when read-macro expansions like '#x0FF'
+are out of bounds. It gives no error message and will just truncate the
+number to the low-order bits that it can deal with [usually 32 bits or 8 hex
+digits].</p>
+
+<p>See the
+<a href="../manual/xlisp-man-024.htm#logior">logior</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/lognot.htm b/docsrc/xlisp/xlisp-doc/reference/lognot.htm new file mode 100644 index 0000000..3ca21b4 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/lognot.htm @@ -0,0 +1,79 @@ +<html><head><title>XLISP lognot</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>lognot</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(lognot <i>expr</i>)</dt>
+<dd><i>expr</i> - an integer expression<br>
+returns - the bitwise inversion of number</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p> The 'lognot' function returns the logical bitwise inversion of the
+expression.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(lognot 255) <font color="#008844">; returns -256</font>
+(lognot #xffff0000) <font color="#008844">; returns 65535</font>
+(lognot #x00000000) <font color="#008844">; returns -1</font>
+(lognot 1) <font color="#008844">; returns -2</font>
+
+(logand (lognot 256) 65535) <font color="#008844">; returns 65279</font>
+(lognot #xFFFFFFFE) <font color="#008844">; returns 1</font>
+(lognot #xFFFFFFFC) <font color="#008844">; returns 3</font>
+</pre>
+
+<p><b>Note:</b> XLISP does not check when read-macro expansions like '#x0FF'
+are out of bounds. It gives no error message and will just truncate the
+number to the low-order bits that it can deal with [usually 32 bits or 8 hex
+digits].</p>
+
+<p>See the
+<a href="../manual/xlisp-man-024.htm#lognot">lognot</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/logxor.htm b/docsrc/xlisp/xlisp-doc/reference/logxor.htm new file mode 100644 index 0000000..2cf8b11 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/logxor.htm @@ -0,0 +1,82 @@ +<html><head><title>XLISP logxor</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>logxor</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(logxor <i>expr1</i> ... )</dt>
+<dd>exprN - an integer expression<br>
+returns - the result of the eXclusive OR operation</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'logxor' function returns the logical bitwise 'exclusive-or' of the
+list of expressions. If there is only one argument, it is returned
+unaltered. If there are two or more arguments, the 'logxor' function
+performs the 'exclusive-or' successively applying the bitwise operation.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(logxor 0 0) <font color="#008844">; returns 0</font>
+(logxor 0 1) <font color="#008844">; returns 1</font>
+(logxor 1 0) <font color="#008844">; returns 1</font>
+(logxor 1 1) <font color="#008844">; returns 0</font>
+
+(logxor #b0011 #b0101) <font color="#008844">; returns 6</font>
+(logxor 255 #xF0) <font color="#008844">; returns 15</font>
+(logxor 255 #x0F) <font color="#008844">; returns 240</font>
+(logxor 255 (logxor 255 99)) <font color="#008844">; returns 99</font>
+</pre>
+
+<p><b>Note:</b> XLISP does not check when read-macro expansions like '#x0FF'
+are out of bounds. It gives no error message and will just truncate the
+number to the low-order bits that it can deal with [usually 32 bits or 8 hex
+digits].</p>
+
+<p>See the
+<a href="../manual/xlisp-man-024.htm#logxor">logxor</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/loop.htm b/docsrc/xlisp/xlisp-doc/reference/loop.htm new file mode 100644 index 0000000..85c3170 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/loop.htm @@ -0,0 +1,84 @@ +<html><head><title>XLISP loop</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>loop</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(loop <i>body</i> ... )</dt>
+<dd><i>body</i> - a series of expressions<br>
+returns - never returns [must use non-local exit]</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'loop' special form specifies a 'repeat-forever' construct. The
+expressions in'body' will be evaluated. When the last expression is
+evaluated in 'body', 'loop' will then repeat the 'body'. When a
+<a href="return.htm">return</a> is evaluated within a 'loop', the
+specified value will be returned. 'loop' itself does not generate a return
+value. Other exit mechanisms include
+<nobr><a href="go.htm">go</a> ,</nobr>
+<nobr><a href="throw.htm">throw</a> ,</nobr>
+<nobr><a href="return-from.htm">return-from</a> and errors.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq i 65) <font color="#008844">; initial value</font>
+
+(loop <font color="#008844">; LOOP</font>
+ (princ (int-char i)) <font color="#008844">; print the character</font>
+ (if (= i 90) (return "done")) <font color="#008844">; test for limit</font>
+ (setq i (1+ i))) <font color="#008844">; increment and repeat</font>
+ <font color="#008844">; prints ABCDEFGHIJKLMNOPQRSTUVWXYZ</font>
+ <font color="#008844">; returns "done"</font>
+</pre>
+
+<p><b>Note:</b> If you create a 'loop' with no exit mechanism, you will
+probably have to abort your XLISP session.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-020.htm#loop">loop</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/lower-case-p.htm b/docsrc/xlisp/xlisp-doc/reference/lower-case-p.htm new file mode 100644 index 0000000..e683614 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/lower-case-p.htm @@ -0,0 +1,79 @@ +<html><head><title>XLISP lower-case-p</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>lower-case-p</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(lower-case-p <i>char</i>)</dt>
+<dd><i>char</i> - a character expression<br>
+returns - <a href="t.htm"> T </a>
+if the character is lower case,
+<a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'lower-case-p' predicate function checks if the 'char' expression
+is a lower case character. If 'char' is lower case a
+<a href="t.htm"> T </a> is returned,
+otherwise a
+<a href="nil.htm">NIL</a> is returned.
+Lower case characters are 'a'
+[<a href="../misc/ascii-table.htm">ASCII</a> decimal value 97]
+through 'z'
+[<a href="../misc/ascii-table.htm">ASCII</a> decimal value 122].</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(lower-case-p #\a) <font color="#008844">; returns T</font>
+(lower-case-p #\A) <font color="#008844">; returns NIL</font>
+(lower-case-p #\1) <font color="#008844">; returns NIL</font>
+(lower-case-p #\[) <font color="#008844">; returns NIL</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-026.htm#lower-case-p">lower-case-p</a>
+predicate function form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/macroexpand-1.htm b/docsrc/xlisp/xlisp-doc/reference/macroexpand-1.htm new file mode 100644 index 0000000..5c43a44 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/macroexpand-1.htm @@ -0,0 +1,85 @@ +<html><head><title>XLISP macroexpand-1</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>macroexpand-1</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(macroexpand-1 <i>form</i>)</dt>
+<dd><i>form</i> - a macro form<br>
+returns - the macro expansion</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'macroexpand-1' function takes a 'form' and expands the first level
+of the macro definition used in the 'form'. The function returns the
+expansion. If the 'form' does not contain a macro, the form is returned
+unaltered.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defmacro plus (n1 n2) `(+ ,n1 ,n2)) <font color="#008844">; define PLUS macro</font>
+(plus 1 2) <font color="#008844">; returns 3</font>
+(macroexpand '(plus 3 4)) <font color="#008844">; returns (+ 3 4)</font>
+(macroexpand-1 '(plus 3 4)) <font color="#008844">; returns (+ 3 4)</font>
+
+(defmacro pl (p1 p2) `(plus ,p1 ,p2)) <font color="#008844">; define PL macro using PLUS</font>
+(pl 3 4) <font color="#008844">; returns 7</font>
+(macroexpand '(pl 3 4)) <font color="#008844">; returns (+ 3 4)</font>
+(macroexpand-1 '(pl 3 4)) <font color="#008844">; returns (PLUS 3 4)</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp returns 2 values for its result of
+'macroexpand-1', the expanded form and a
+<a href="t.htm"> T </a> or
+<a href="nil.htm">NIL</a> value that indicates if the form was a
+macro. XLISP returns only the expanded form. Common Lisp also supports an
+optional argument in 'macroexpand-1' for the environment of the expansion.
+XLISP does not support this optional argument.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-012.htm#macroexpand-1">macroexpand-1</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/macroexpand.htm b/docsrc/xlisp/xlisp-doc/reference/macroexpand.htm new file mode 100644 index 0000000..771f752 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/macroexpand.htm @@ -0,0 +1,83 @@ +<html><head><title>XLISP macroexpand</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>macroexpand</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(macroexpand <i>form</i>)</dt>
+<dd><i>form</i> - a macro form<br>
+returns - the macro expansion</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'macroexpand' function takes a 'form' and recursively expands the
+macro definitions used in the 'form'. The function returns the expansion. If
+the 'form' does not contain a macro, the form is returned unaltered.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defmacro plus (n1 n2) `(+ ,n1 ,n2)) <font color="#008844">; define PLUS macro</font>
+(plus 1 2) <font color="#008844">; returns 3</font>
+(macroexpand '(plus 3 4)) <font color="#008844">; returns (+ 3 4)</font>
+
+(defmacro pl (p1 p2) `(plus ,p1 ,p2)) <font color="#008844">; define PL macro using PLUS</font>
+(pl 3 4) <font color="#008844">; returns 7</font>
+(macroexpand '(pl 3 4)) <font color="#008844">; returns (+ 3 4)</font>
+(macroexpand-1 '(pl 3 4)) <font color="#008844">; returns (PLUS 3 4)</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp returns 2 values for its result of
+'macroexpand', the expanded form and a
+<a href="t.htm"> T </a> or
+<a href="nil.htm">NIL</a> value that indicates if the form was a
+macro. XLISP returns only the expanded form. Common Lisp also supports an
+optional argument in 'macroexpand' for the environment of the expansion.
+XLISP does not support this optional argument.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-012.htm#macroexpand">macroexpand</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/macrolet.htm b/docsrc/xlisp/xlisp-doc/reference/macrolet.htm new file mode 100644 index 0000000..39de0f2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/macrolet.htm @@ -0,0 +1,146 @@ +<html><head><title>XLISP macrolet</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>macrolet</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>macrolet</b> ([<i>macro</i> ... ]) <i>expr</i> ... )</dt>
+<dd><i>macro</i> - a macro definition binding which is of the form:<br>
+<dl><dd>(<i>symbol arg-list body</i>)</dd>
+<dl><dd><i>symbol</i> - the symbol specifying the macro name<br>
+<i>arg-list</i> - the argument list for the macro<br>
+<i>body</i> - the body of the macro</dd></dl></dl>
+<i>expr</i> - an expression<br>
+returns - the value of the last expression</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'macrolet' special form is basically a local <a
+href="block.htm">block</a> construct that allows local 'macro' definitions
+followed by a block of code to evaluate. <nobr>The first</nobr> form after
+the macrolet is the 'binding' form. <nobr>It contains</nobr> a series of
+'macros'. <nobr>The 'macrolet'</nobr> form will sequentially execute the
+'exprs' after defining the 'macros'. <nobr>The value</nobr> of the last
+'expr' evaluated is returned. When the 'macrolet' is finished execution, the
+'symbols' that were defined will no longer exist.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+> (macrolet ((pls (n1 n2) <font color="#008844">; MACROLET defining a PLS macro</font>
+ `(+ ,n1 ,n2)))
+ (pls 4 5))
+9
+
+> (pls 4 5) <font color="#008844">; the PLS macro no longer exists</font>
+<font color="#AA0000">error: unbound function - PLS</font>
+
+> (macrolet () <font color="#008844">; an empty MACROLET</font>
+ (print 'a))
+A <font color="#008844">; screen output of PRINT</font>
+A <font color="#008844">; return value</font>
+</pre>
+
+<h2>Known Problems</h2>
+
+<p><b>1.</b> In XLISP, only macros defined by
+
+<a href="defmacro.htm">defmacro</a> [interned in the
+<a href="global-obarray.htm">*obarray*</a>] can be used with
+<a href="setf.htm">setf</a>:</p>
+
+<pre class="example">
+(setq a #(1 2 3))
+
+(defmacro second-array-element (array)
+ `(aref ,array 1))
+
+(second-array-element a) => 2
+(setf (second-array-element a) 'x) => X
+a => #(1 X 3)
+</pre>
+
+<p>With macros defined by 'macrolet' [stored in the lexical environment],
+<a href="setf.htm">setf</a> signals a '<nobr>bad place form</nobr>' error:</p>
+
+<pre class="example">
+(macrolet ((second-element (array)
+ `(aref ,array 1)))
+ (second-element a)) => X
+
+(macrolet ((second-element (array)
+ `(aref ,array 1)))
+ (setf (second-element a) 'y)) => <font color="#AA0000">error: bad place form</font>
+</pre>
+
+<p><b>2.</b> In XLISP, the <a href="macroexpand.htm">macroexpand</a> and
+<nobr><a href="macroexpand-1.htm">macroexpand-1</a></nobr> functions can
+only expand macros defined
+<nobr>by <a href="defmacro.htm">defmacro</a>:</nobr></p>
+
+<pre class="example">
+> (macroexpand-1 '(second-array-element a))
+(AREF A 1)
+</pre>
+
+<p>With macros defined by 'macrolet', the macro form is returned
+unexpanded:</p>
+
+<pre class="example">
+> (macrolet ((second-element (array)
+ `(aref ,array 1)))
+ (macroexpand-1 '(second-element a)))
+(SECOND-ELEMENT A)
+</pre>
+
+<p>In XLISP, the <a href="macroexpand.htm">macroexpand</a> and
+<nobr><a href="macroexpand-1.htm">macroexpand-1</a></nobr> functions only
+search in the <a href="global-obarray.htm">*obarray*</a> for defined macros,
+but not in the lexical environment.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/make-array.htm b/docsrc/xlisp/xlisp-doc/reference/make-array.htm new file mode 100644 index 0000000..47b576e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/make-array.htm @@ -0,0 +1,95 @@ +<html><head><title>XLISP make-array</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>make-array</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(make-array <i>size</i>)</dt>
+<dd><i>size</i> - the size [integer] of the array to be created<br>
+returns - the new array</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'make-array' function creates an array of the specified size and
+returns the array. Array elements may be any valid lisp data type, including
+lists or arrays. Arrays made by 'make-array' and accessed by
+<a href="aref.htm">aref</a> are <nobr>base 0.</nobr> This means
+the first element is accessed by element number '0' and the last element is
+accessed by element number 'n-1', where 'n' is the array size. Array
+elements are initialized to <a href="nil.htm">NIL</a>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq my-array (make-array 16)) <font color="#008844">; make the array</font>
+(aref my-array 0) <font color="#008844">; return 0th (first) element</font>
+(aref my-array 15) <font color="#008844">; return 15th (last) element</font>
+(aref my-array 16) <font color="#008844">; error: non existant element</font>
+
+(dotimes (i 16) <font color="#008844">; set each element to its index</font>
+ (setf (aref my-array i) i)) <font color="#008844">; by the setf function</font>
+
+(setq new (make-array 4)) <font color="#008844">; make another array</font>
+(setf (aref new 0) (make-array 4)) <font color="#008844">; make new[0] an array of 4</font>
+(setf (aref (aref new 0) 1) 'a) <font color="#008844">; set new[0,1] = 'a</font>
+(setf (aref new 2) '(a b c)) <font color="#008844">; set new[2] = '(a b c)</font>
+my-array <font color="#008844">; look at array</font>
+</pre>
+
+<p><b>Read macro:</b> There is a built-in read-macro for arrays, '#(...)'
+[the hash symbol with an opening and a closing parenthesis]. This allows you
+to create arbitrary arrays with initial values without going through a
+'make-array' function. There is also the XLISP <a
+href="vector.htm">vector</a> function to create initialized arrays.</p>
+
+<p><b>Common Lisp:</b> Common Lisp supports multi-dimensional arrays, XLISP
+only supports one-dimensional arrays. In XLISP, multi-dimenstional arrays
+can be created by using 'arrays within arrays'. Common Lisp supports various
+keyword parameters that are not supported in XLISP.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-015.htm#make-array">make-array</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/make-string-input-stream.htm b/docsrc/xlisp/xlisp-doc/reference/make-string-input-stream.htm new file mode 100644 index 0000000..0dd3fe9 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/make-string-input-stream.htm @@ -0,0 +1,84 @@ +<html><head><title>XLISP make-string-input-stream</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>make-string-input-stream</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(make-string-input-stream <i>string</i> [<i>start-pos</i> [<i>end-pos</i>]])</dt>
+<dd><i>string</i> - a string expression<br>
+<i>start-pos</i> - an optional numeric expression, default value is '0' [the first character of the string]<br>
+<i>end-pos</i> - an optional numeric expression, default value is the length of the string<br>
+returns - an unnamed stream that reads from the string</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'make-string-input-stream' function creates an unnamed stream from
+the 'string' expression. The stream can then be used as any other stream
+object. The optional 'start-pos' expression specifies the starting offset of
+the 'string' expression. A 'start-pos' of '0' will start with the beginning
+of the 'string'. The optional 'end-pos' expression specifies the ending
+offset of the 'string' expression. A 'end-pos' of 4 will make the fourth
+character the last in the stream. If the function is successful, it returns
+the unnamed stream object. If the string is empty, an unnamed stream is
+still returned. Error conditions include 'start-pos' and 'end-pos' being out
+of bounds.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(make-string-input-stream "abcdefgh") <font color="#008844">; returns #<Unnamed-Stream: #277e2></font>
+(read (make-string-input-stream "123456")) <font color="#008844">; returns 123456</font>
+(read (make-string-input-stream "123456" 1)) <font color="#008844">; returns 23456</font>
+(read (make-string-input-stream "123456" 1 3)) <font color="#008844">; returns 23</font>
+(read (make-string-input-stream "123" 0)) <font color="#008844">; returns 123</font>
+(read (make-string-input-stream "123" 0 3)) <font color="#008844">; returns 123</font>
+(read (make-string-input-stream "123" 2 1)) <font color="#008844">; returns NIL</font>
+(read (make-string-input-stream "123" 0 4)) <font color="#008844">; error: string index out of bounds - 4</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-030.htm#make-string-input-stream">make-string-input-stream</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/make-string-output-stream.htm b/docsrc/xlisp/xlisp-doc/reference/make-string-output-stream.htm new file mode 100644 index 0000000..ae2cfe2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/make-string-output-stream.htm @@ -0,0 +1,79 @@ +<html><head><title>XLISP make-string-output-stream</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>make-string-output-stream</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(make-string-output-stream)</dt>
+<dd>returns - an unnamed output stream</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'make-string-output-stream' function creates and returns an unnamed
+output stream. The stream can then be used as any other stream object.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(make-string-output-stream) <font color="#008844">; returns #<Unnamed-Stream: #2d9c0></font>
+
+(setq out (make-string-output-stream)) <font color="#008844">; returns #<Unnamed-Stream: #2d95c></font>
+
+(format out "fee fi fo fum ") <font color="#008844">; \</font>
+(format out "I smell the blood of ") <font color="#008844">; fill up output stream</font>
+(format out "Elmer Fudd") <font color="#008844">; /</font>
+(get-output-stream-string out) <font color="#008844">; returns "fee fi fo fum I smell the blood of Elmer Fudd"</font>
+
+(format out "~%now what") <font color="#008844">; add more to output stream</font>
+(get-output-stream-string out) <font color="#008844">; returns "\nnow what"</font>
+
+(format out "hello") <font color="#008844">; add more to output stream</font>
+(read out) <font color="#008844">; returns HELLO</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-030.htm#make-string-output-stream">make-string-output-stream</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/make-symbol.htm b/docsrc/xlisp/xlisp-doc/reference/make-symbol.htm new file mode 100644 index 0000000..f0d0a7b --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/make-symbol.htm @@ -0,0 +1,93 @@ +<html><head><title>XLISP make-symbol</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>make-symbol</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(make-symbol <i>symbol-str</i>)</dt>
+<dd><i>symbol-str</i> - a string expression<br>
+returns - the new symbol</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'make-symbol' function takes a string name 'symbol-str' and creates a
+new symbol. This symbol is temporary and is not
+<a href="intern.htm">intern</a>ed [placed] into the symbol hash
+table <a href="global-obarray.htm">*obarray*</a>. If the symbol already
+exists, no error or action is taken and the old values and property lists
+remain intact. The 'make-symbol' function returns the symbol as its
+result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun lookin (sym) <font color="#008844">; create a function to</font>
+ (aref *obarray* <font color="#008844">; look inside *OBARRAY*</font>
+ (hash sym (length *obarray*)))) <font color="#008844">; and look for a specific</font>
+ <font color="#008844">; symbol - returns a list</font>
+
+(lookin "FEE") <font color="#008844">; returns (CHAR-INT NTH ++)</font>
+ <font color="#008844">; FEE symbol doesn't exist</font>
+
+(make-symbol "FEE") <font color="#008844">; returns FEE symbol</font>
+(lookin "FEE") <font color="#008844">; returns (CHAR-INT NTH ++)</font>
+ <font color="#008844">; FEE still doesn't exist</font>
+
+(intern "FEE") <font color="#008844">; intern FEE symbol</font>
+(lookin "FEE") <font color="#008844">; returns (FEE CHAR-INT NTH ++)</font>
+ <font color="#008844">; FEE does now exist</font>
+</pre>
+
+<p><b>Note:</b> When you 'make-symbol' a string type symbol like
+"fingers", this is a lower case symbol. This is different from
+doing a 'make-symbol' on a string type symbol "FINGERS", which is
+an upper case symbol. With string type symbols, "fingers" and
+"FINGERS" are two different symbols. Remember also that normal
+symbols created by XLISP are automatically converted to upper case.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-013.htm#make-symbol">make-symbol</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/mapc.htm b/docsrc/xlisp/xlisp-doc/reference/mapc.htm new file mode 100644 index 0000000..83fe3fc --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/mapc.htm @@ -0,0 +1,87 @@ +<html><head><title>XLISP mapc</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>mapc</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(mapc <i>function list1</i> [<i>list2</i> ... ])</dt>
+<dd><i>function</i> - a function definition like a
+<a href="lambda.htm">lambda</a> form or a function name<br>
+<i>listN</i> - a list or list expression<br>
+returns - the first list of arguments</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'mapc' function applies the 'function' to the succesive
+<a href="car.htm">car</a>s of each of the lists 'listN'. Each of
+the lists supplies one of the arguments to 'function'. The 'mapc' function
+returns a list that is equivalent to the first list 'list1'. It's purpose is
+to perform operations that have side-effects. If the lists are of different
+lengths, the shortest list will determine the number of applications of
+'function'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(mapc 'princ '(hi there bob)) <font color="#008844">; prints HITHEREBOB</font>
+ <font color="#008844">; returns (HI THERE BOB)</font>
+
+(mapc '+ '(1 2 3) '(1 2 3)) <font color="#008844">; returns (1 2 3)</font>
+ <font color="#008844">; there were no side effects</font>
+
+(mapc (lambda (x y) (print (+ x y))) <font color="#008844">; define a function with side effects</font>
+ '(1 2 3) '(1 2 3)) <font color="#008844">; prints 2 4 6 </font>
+ <font color="#008844">; returns (1 2 3)</font>
+</pre>
+
+<p><b>Note:</b> The use of the 'function' will work properly when it is a
+quoted symbol [the name of the function], an unquoted symbol, whose value is
+a function, or a closure object like a
+<a href="lambda.htm">lambda</a> form.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#mapc">mapc</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/mapcar.htm b/docsrc/xlisp/xlisp-doc/reference/mapcar.htm new file mode 100644 index 0000000..8112cba --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/mapcar.htm @@ -0,0 +1,151 @@ +<html><head><title>XLISP mapcar</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>mapcar</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(mapcar <i>function list1</i> [<i>list2</i> ... ])</dt>
+<dd><i>function</i> - a function definition like a
+<a href="lambda.htm">lambda</a> or a function name<br>
+<i>listN</i> - a list or list expression<br>
+returns - a list that is constructed from the results of the <i>function</i> applications</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The mapcan function 'mapcar' applies the 'function' to the succesive
+<a href="car.htm">car</a>s of each of the lists 'listN'. Each of
+the lists supplies one of the arguments to 'function'. The 'mapcar' function
+returns a list that is constructed from the results of the 'function'
+applications. If the lists are of different lengths, the shortest list will
+determine the number of applications of 'function'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+> (mapcar #'+ '(1 2 3) '(1 2 3))
+(2 4 6)
+
+> (mapcar #'princ '(1 2 3))
+123 <font color="#008844">; screen output</font>
+(1 2 3) <font color="#008844">; return value</font>
+
+> (mapcar #'+ '(1 2 3) '(1 2 3 4 5 6) <font color="#008844">; different length lists</font>
+(2 4 6)
+</pre>
+
+<p><b>Note:</b> The use of the 'function' will work properly when it is a
+<nobr>sharp-quoted</nobr> symbol, <nobr>a quoted</nobr> symbol [must be the
+name of a function], <nobr>an unquoted</nobr> symbol whose value is a
+function, or a closure object like a <a href="lambda.htm">lambda</a>
+form.</p>
+
+<p><div class="box">
+
+<p><b>Bug:</b> The proper syntax for 'function' when 'function' is a
+<a href="lambda.htm">lambda</a> expression is, for example:</p>
+
+<pre class="example">
+(mapcar #'(lambda (arg1 arg2) (+ arg1 arg2)) '(1 2))
+</pre>
+
+<p>and not:</p>
+
+<pre class="example">
+(mapcar '(lambda (arg1 arg2) (+ arg1 arg2)) '(1 2))
+</pre>
+
+<p>That is, the #' [<a href="function.htm">function</a>] read macro must be
+present. This error should be caught by the XLISP interpreter, but it is
+not, with the result that very obscure garbage collection bugs occur.
+<nobr>[I still</nobr> haven't tested Nyquist for possible garbage collection
+bugs caused by this.]</p>
+
+</div></p>
+
+<h2>Notes</h2>
+
+<p>In XLISP, a '<nobr>special form</nobr>' of type FSUBR is not a function.
+This means that 'mapcar' only works with functions of type SUBR
+<nobr>[built-in</nobr> function] or CLOSURE [function defined by
+<a href="defun.htm">defun</a>, <a href="flet.htm">flet</a>,
+<a href="labels.htm">labels</a>, or <a href="lambda.htm">lambda</a>], but
+with special forms of <nobr>type FSUBR</nobr> a 'bad function' error is
+signalled. Here is an example how to work around this behaviour:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">mapcar*</font> (function &rest args)
+ (if (eq (type-of (symbol-function (second function))) 'fsubr)
+ (let ((rest (gensym)))
+ `(mapcar #'(lambda (&rest ,rest)
+ (eval (cons ,function ,rest)))
+ ,@args))
+ `(mapcar ,function ,@args)))
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+(type-of #'eql) => SUBR <font color="#008844">; built-in function</font>
+(type-of #'and) => FSUBR <font color="#008844">; built-in special form</font>
+
+> (macroexpand-1 '(mapcar* #'eql '(1 2 3) '(t nil 3)))
+(MAPCAR (FUNCTION EQL)
+ (QUOTE (1 2 3))
+ (QUOTE (T NIL 3)))
+
+> (macroexpand-1 '(mapcar* #'and '(1 2 3) '(t nil 3)))
+(MAPCAR (FUNCTION (LAMBDA (&REST G7)
+ (EVAL (CONS (FUNCTION AND) G7))))
+ (QUOTE (1 2 3))
+ (QUOTE (T NIL 3)))
+
+(mapcar #'eql '(1 2 3) '(t nil 3))) => (NIL NIL T)
+(mapcar* #'eql '(1 2 3) '(t nil 3))) => (NIL NIL T)
+
+(mapcar #'and '(1 2 3) '(t nil 3))) => <font color="#AA0000">error: bad function</font>
+(mapcar* #'and '(1 2 3) '(t nil 3))) => (T NIL 3)
+</pre>
+
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/mapl.htm b/docsrc/xlisp/xlisp-doc/reference/mapl.htm new file mode 100644 index 0000000..fb65045 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/mapl.htm @@ -0,0 +1,89 @@ +<html><head><title>XLISP mapl</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>mapl</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(mapl <i>function list1</i> [<i>list2</i> ... ])</dt>
+<dd><i>function</i> - a function definition like a
+<a href="lambda.htm">lambda</a> form or a function name<br>
+<i>listN</i> - a list or list expression<br>
+returns - a list that is equivalent to <i>list1</i></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>Tha 'mapl' function applies the 'function' to the successive
+<a href="cdr.htm">cdr</a>s of each of the lists 'listN'. Each of
+the lists supplies one of the arguments to 'function'. The 'mapl' function
+returns a list that is equivalent to the first list 'list1'. It's purpose is
+to perform operations that have side-effects. If the lists are of different
+lengths, the shortest list will determine the number of applications of
+'function'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(mapl 'print '(a b c)) <font color="#008844">; prints (A B C)</font>
+ <font color="#008844">; (B C)</font>
+ <font color="#008844">; (C)</font>
+ <font color="#008844">; returns (A B C)</font>
+
+<font color="#008844">;; apply a lambda function to a list</font>
+(mapl (lambda (x y) (princ x) (princ y) (terpri))
+ '(a b c) '(1 2 3)) <font color="#008844">; prints (A B C)(1 2 3)</font>
+ <font color="#008844">; (B C)(2 3)</font>
+ <font color="#008844">; (C)(3)</font>
+ <font color="#008844">; returns (A B C)</font>
+</pre>
+
+<p><b>Note:</b> The use of the 'function' will work properly when it is a
+quoted symbol [the name of the function], an unquoted symbol whose value is
+a function or a closure object like a
+<a href="lambda.htm">lambda</a> form.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#mapl">mapl</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/maplist.htm b/docsrc/xlisp/xlisp-doc/reference/maplist.htm new file mode 100644 index 0000000..a0abe69 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/maplist.htm @@ -0,0 +1,86 @@ +<html><head><title>XLISP maplist</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>maplist</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(maplist <i>function list1</i> [<i>list2</i> ... ])</dt>
+<dd><i>function</i> - a function definition like a
+<a href="lambda.htm">lambda</a> or a function name<br>
+<i>listN</i> - a list or list expression<br>
+returns - a list that is constructed from the results of the
+<i>function</i> applications</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'maplist' function applies the 'function' to the successive
+<a href="cdr.htm">cdr</a>s of each of the lists 'listN'. Each of
+the lists supplies one of the arguments to 'function'. The 'maplist'
+function returns a list that is constructed from the results of the
+'function' applications. If the lists are of different lengths, the shortest
+list will determine the number of applications of 'function'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(maplist 'print '(a b c)) <font color="#008844">; prints (A B C)</font>
+ <font color="#008844">; (B C)</font>
+ <font color="#008844">; (C)</font>
+ <font color="#008844">; returns ((A B C) (B C) (C))</font>
+
+<font color="#008844">;; append the lists into one list and find it's length</font>
+(maplist (lambda (x y) (length (append x y)))
+ '(a b c d) '(1 2 3 4)) <font color="#008844">; returns (8 6 4 2)</font>
+</pre>
+
+<p><b>Note:</b> The use of the 'function' will work properly when it is a
+quoted symbol [the name of the function], an unquoted symbol whose value is
+a function or a closure object like a
+<a href="lambda.htm">lambda</a> form.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#maplist">maplist</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/max.htm b/docsrc/xlisp/xlisp-doc/reference/max.htm new file mode 100644 index 0000000..bdac974 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/max.htm @@ -0,0 +1,73 @@ +<html><head><title>XLISP max</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>max</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(max <i>expr1</i> ... )</dt>
+<dd><i>exprN</i> - integer or floating point number/expression<br>
+returns - the largest number in the list of numbers/expressions</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'max' function returns the largest numeric expression from the list
+of arguments.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(max 1) <font color="#008844">; returns 1</font>
+(max 1 -5 9) <font color="#008844">; returns 9</font>
+
+(setq a '( 9 3 5 2)) <font color="#008844">; set up a list - (9 3 5 2)</font>
+(apply 'max a) <font color="#008844">; returns 9</font>
+(apply #'max a) <font color="#008844">; returns 9</font>
+(apply 'min a) <font color="#008844">; returns 2</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-023.htm#max">max</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/member.htm b/docsrc/xlisp/xlisp-doc/reference/member.htm new file mode 100644 index 0000000..3dfbebf --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/member.htm @@ -0,0 +1,93 @@ +<html><head><title>XLISP member</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>member</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(member <i>expr list-expr</i> [{:test | :test-not} <i>test</i>])</dt>
+<dd><i>expr</i> - the expression to find [an atom or a list]<br>
+<i>list-expr</i> - the list to search<br>
+<i>test</i> - optional test function, default is
+<a href="eql.htm">eql</a><br>
+returns - the remainder of the list starting with <i>expr</i></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'member' function searches through 'list-expr' for 'expr'. If found,
+'member' returns the remainder of the 'list-expr' starting with 'expr'. If
+'expr' is not found, a <a href="nil.htm">NIL</a> is returned. You
+may specify your own test with the ':test' and ':test-not' keywords followed
+by the test you which to perform.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(member 'a '(1 2 3 4)) <font color="#008844">; returns NIL</font>
+(member '2 '(1 2 3 4)) <font color="#008844">; returns (2 3 4)</font>
+
+(setq mylist '(2 4 8 16 32 64 128 256)) <font color="#008844">; make a numeric list</font>
+(member 6 mylist :test '<) <font color="#008844">; returns (8 16 32 64 128 256)</font>
+(member 6 (reverse mylist) :test-not '<) <font color="#008844">; returns (4 2)</font>
+(member '20 '(60 40 20 10) :test '> ) <font color="#008844">; returns (10)</font>
+
+(member '(a) '((see) (a) (cat)) :test 'equal) <font color="#008844">; returns ((A) (CAT)) with EQUAL as test</font>
+(member "hi" '("a" "hi" "c") :test 'string= ) <font color="#008844">; returns ("hi" "c") with STRING= as test</font>
+
+</pre>
+
+<p><b>Note:</b> The 'member' function can work with a list or string as the
+'expr'. However, the default <a href="eql.htm">eql</a> test does
+not work with lists or strings, only symbols and numbers. To make this work,
+you need to use the ':test' keyword along with
+<a href="equal.htm">equal</a> for 'test'.</p>
+
+<p><b>Common Lisp:</b> Common Lisp supports the use of the ':key' keyword
+which specifies a function that is applied to each element of 'list-expr'
+before it is tested. XLISP does not support this.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#member">member</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/min.htm b/docsrc/xlisp/xlisp-doc/reference/min.htm new file mode 100644 index 0000000..287c85a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/min.htm @@ -0,0 +1,73 @@ +<html><head><title>XLISP min</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>min</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(min <i>expr1</i> ... )</dt>
+<dd><i>exprN</i> - integer or floating point number/expression<br>
+returns - the smallest number in the list of numbers/expressions</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'min' function returns the minimum [most negative or most nearly
+negative] numeric expression from the list of arguments.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(min 1) <font color="#008844">; returns 1</font>
+(min 8 7 4 2) <font color="#008844">; returns 2</font>
+(min 2 3 -1 -99) <font color="#008844">; returns -99</font>
+(setq a '( 9 3 5 2)) <font color="#008844">; make a numeric list - (9 3 5 2)</font>
+(apply 'min a) <font color="#008844">; returns 2</font>
+(apply #'min a) <font color="#008844">; returns 2</font>
+(apply 'max a) <font color="#008844">; returns 9</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-023.htm#min">min</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/minusp.htm b/docsrc/xlisp/xlisp-doc/reference/minusp.htm new file mode 100644 index 0000000..e01376e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/minusp.htm @@ -0,0 +1,84 @@ +<html><head><title>XLISP minusp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>minusp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+(minusp <i>expr</i>)
+<dd><i>expr</i> - the numeric expression to check<br>
+returns - <a href="t.htm"> T </a> if the number is
+negative, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'minusp' predicate function checks to see if the number 'expr' is
+negative. <a href="t.htm"> T </a> is returned if the
+number is negative [less than zero], <a href="nil.htm">NIL</a> is
+returned otherwise. An error is generated if the
+'expr' is not a numeric expression:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument type</font>
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(minusp 1) <font color="#008844">; returns NIL</font>
+(minusp 0) <font color="#008844">; returns NIL</font>
+(minusp -1) <font color="#008844">; returns T</font>
+(minusp -.000000005) <font color="#008844">; returns T</font>
+(minusp #xFFFFFFFF) <font color="#008844">; returns T</font>
+(minusp #x01) <font color="#008844">; returns NIL</font>
+
+(minusp 'a) <font color="#008844">; error: bad argument type</font>
+(setq a -3.5) <font color="#008844">; set A to -3.5</font>
+(minusp a) <font color="#008844">; returns T</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#minusp">minusp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/multiplication.htm b/docsrc/xlisp/xlisp-doc/reference/multiplication.htm new file mode 100644 index 0000000..07b6b6e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/multiplication.htm @@ -0,0 +1,87 @@ +<html><head><title>XLISP *</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(* <i>expr1</i> ...)</nobr></dt>
+<dd><i>exprN</i> - integer or floating point number/expression<br>
+returns - the result of the multiplication</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The '*' function multiplies one or more numbers together and
+returns the result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(* 1) => 1
+(* 1 2) => 2
+(* 1 2 3) => 6
+(* 1 2 3 4) => 24
+</pre>
+
+<pre class="example">
+> (print (+ 1 2 (* 3.5 (/ 3.9 1.45))))
+12.4138
+12.4138
+</pre>
+
+<p>See <a href="addition.htm"> + </a>,
+<a href="division.htm"> / </a>, <a href="print.htm">print</a>.
+XLISP first prints the value on the screen, the second number is the
+return value.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/nconc.htm b/docsrc/xlisp/xlisp-doc/reference/nconc.htm new file mode 100644 index 0000000..20e3b91 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/nconc.htm @@ -0,0 +1,89 @@ +<html><head><title>XLISP nconc</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>nconc</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(nconc [<i>list1</i> ... ])</dt>
+<dd><i>listN</i> - a list to destructively concatenate<br>
+returns - the result of concatenating the lists</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'nconc' function destructively concatenates a sequence of lists and
+returns the result of this concatentation. The destructive aspect of this
+operation means that the actual symbol values are used in the list-modifying
+operations, not copies. This means, for 'nconc', that the lists are spliced
+together. 'listN' must evaluate to a valid list. An atom for 'listN' will
+result in an error. <a href="nil.htm">NIL</a> is a valid
+'listN'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq a '(1 2 3)) <font color="#008844">; set up A with (1 2 3)</font>
+(setq b '(4 5 6)) <font color="#008844">; set up B with (4 5 6)</font>
+(setq c '(7 8 9)) <font color="#008844">; set up C with (7 8 9)</font>
+(NCONC a b c) <font color="#008844">; returns (1 2 3 4 5 6 7 8 9)</font>
+(setf (nth 8 a) 'end) <font color="#008844">; change last element of A</font>
+(print a) <font color="#008844">; prints (1 2 3 4 5 6 7 8 END)</font>
+(print b) <font color="#008844">; prints (4 5 6 7 8 END)</font>
+(print c) <font color="#008844">; prints (7 8 END)</font>
+</pre>
+
+<p><b>Note:</b> with Nyquist, no error is raised if 'listN' is an atom.
+Instead, all atoms given to the 'nconc' function, if not given as the last
+argument, just disappear:</p>
+
+<pre class="example">
+(nconc 'a 'b 'c 'd) <font color="#008844">; returns D</font>
+(nconc 'a '(b) 'c '(d)) <font color="#008844">; returns (B D)</font>
+(nconc '(a) 'b '(c) 'd) <font color="#008844">; returns (A C . D)</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-017.htm#nconc">nconc</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/nil.htm b/docsrc/xlisp/xlisp-doc/reference/nil.htm new file mode 100644 index 0000000..b8265e9 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/nil.htm @@ -0,0 +1,70 @@ +<html><head><title>XLISP nil</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>nil</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system constant</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlsym.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> nil</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'nil' constant represents the empty list or the false value, as
+oppossed to the true value [the symbol
+<a href="t.htm"> T </a>]. 'nil' can be written as
+the three character symbol 'nil' or as the empty list ().</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq myvar nil) <font color="#008844">; set MYVAR to False</font>
+(setq myvar 'nil) <font color="#008844">; NIL and 'NIL evaluate to NIL</font>
+(setq myvar ()) <font color="#008844">; () is the empty list = NIL</font>
+(setq myvar '()) <font color="#008844">; () and '() evaluate to NIL</font>
+(if nil (print "this won't print") <font color="#008844">; if/then/else</font>
+ (print "this will print"))
+</pre>
+
+<p><b>Note:</b> You can not change the value of NIL.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/not.htm b/docsrc/xlisp/xlisp-doc/reference/not.htm new file mode 100644 index 0000000..a6ba8d0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/not.htm @@ -0,0 +1,80 @@ +<html><head><title>XLISP not</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>not</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(not <i>expr</i>)</dt>
+<dd><i>expr</i> - the expression to check<br>
+return - <a href="t.htm"> T </a> if the value is
+<nobr><a href="nil.htm">NIL</a> ,</nobr>
+<a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'not' predicate function checks to see if the 'expr' is false.
+<a href="t.htm"> T </a> is returned if the
+expression is <nobr><a href="nil.htm">NIL</a> ,</nobr>
+<a href="nil.htm">NIL</a> is returned otherwise.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(not '()) <font color="#008844">; returns T - empty list</font>
+(not ()) <font color="#008844">; returns T - still empty</font>
+(setq a NIL) <font color="#008844">; set up a variable</font>
+(not a) <font color="#008844">; returns T - value = empty list</font>
+
+(not "a") <font color="#008844">; returns NIL - not a list</font>
+(not 'a) <font color="#008844">; returns NIL - not a list</font>
+</pre>
+
+<p><b>Note:</b> The 'not' predicate is the same function as the
+<a href="null.htm">null</a> predicate.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#not">not</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/nstring-downcase.htm b/docsrc/xlisp/xlisp-doc/reference/nstring-downcase.htm new file mode 100644 index 0000000..4d30642 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/nstring-downcase.htm @@ -0,0 +1,82 @@ +<html><head><title>XLISP nstring-downcase</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>nstring-downcase</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(nstring-downcase <i>string</i> [{:start | :end} <i>offset</i>] ... )</dt>
+<dd><i>string</i> - a string expression<br>
+<i>offset</i> - an optional integer expression for a keyword<br>
+returns - the converted string, not a copy</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'nstring-downcase' function takes a string argument and makes it
+lower case. This function modifies the string or string variable itself, it
+does not just make a copy. The lower case string is returned.</p>
+
+<p> The keyword arguments allow for accessing substrings within 'string'.
+The keyword arguments require a keyword [':start' or ':end'] first and a
+single integer expression second. The ':start' keyword specifies the
+starting offset for the 'nstring-downcase' operation on 'string'. A value of
+0 starts the string at the beginning [no offset]. The ':end' keyword
+specifies the end offset for the operation on 'string'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(nstring-downcase "ABcd+-12&[") <font color="#008844">; returns "abcd+-&["</font>
+(nstring-downcase "ABCDEFGH" :start 2 :end 4) <font color="#008844">; returns "ABcdEFGH"</font>
+
+(setq mystr "ABcdEFgh") <font color="#008844">; set up variable</font>
+(nstring-downcase mystr) <font color="#008844">; returns "abcdefgh"</font>
+(print mystr) <font color="#008844">; prints "abcdefgh"</font>
+ <font color="#008844">; note that MYSTR is modified</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#nstring-downcase">nstring-downcase</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/nstring-upcase.htm b/docsrc/xlisp/xlisp-doc/reference/nstring-upcase.htm new file mode 100644 index 0000000..98b2b33 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/nstring-upcase.htm @@ -0,0 +1,82 @@ +<html><head><title>XLISP nstring-upcase</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>nstring-upcase</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(nstring-upcase <i>string</i> [{:start | :end} <i>offset</i>] ... )</dt>
+<dd><i>string</i> - a string expression<br>
+<i>offset</i> - an optional integer expression for a keyword<br>
+returns - the converted string, not a copy</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'nstring-upcase' function takes a string argument and makes it upper
+case. This function modifies the string or string variable itself, it does
+not just make a copy. The upper case string is returned.</p>
+
+<p>The keyword arguments allow for accessing substrings within 'string'. The
+keyword arguments require a keyword (':start' or ':end') first and a single
+integer expression second. The ':start' keyword specifies the starting
+offset for the 'nstring-upcase' operation on 'string'. A value of 0 starts
+the string at the beginning [no offset]. The ':end' keyword specifies the
+end offset for the operation on 'string'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(nstring-upcase "ABcd+-12&[") <font color="#008844">; returns "ABCD+-&["</font>
+(nstring-upcase "abcdefgh" :start 2 :end 4) <font color="#008844">; returns "abCDefgh"</font>
+
+(setq mystr "ABcdEFgh") <font color="#008844">; set up variable</font>
+(nstring-upcase mystr) <font color="#008844">; returns "ABCDEFGH"</font>
+(print mystr) <font color="#008844">; prints "ABCDEFGH"</font>
+ <font color="#008844">; note that MYSTR is modified</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#nstring-upcase">nstring-upcase</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/nth.htm b/docsrc/xlisp/xlisp-doc/reference/nth.htm new file mode 100644 index 0000000..fee31f5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/nth.htm @@ -0,0 +1,74 @@ +<html><head><title>XLISP nth</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>nth</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(nth <i>expr list-expr</i>)</dt>
+<dd><i>expr</i> - an integer expression<br>
+<i>list-expr</i> - a list or list expression<br>
+returns - the nth element or <a href="nil.htm">NIL</a> if the
+list isn't that long</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>'nth' returns the 'expr'-th element of 'list-expr'. If the 'list-expr' is
+shorter than 'expr', a <a href="nil.htm">NIL</a> is returned. The
+counting sequence is base zero, the first element is the 0th element.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(nth 4 '(0 1 2 3 4 5 6)) <font color="#008844">; returns 4</font>
+(nth 3 '(a b)) <font color="#008844">; returns NIL</font>
+
+(nth 4 'a) <font color="#008844">; error: bad argument type</font>
+(nth 3 "abcdefg") <font color="#008844">; error: bad argument type</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#nth">nth</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/nthcdr.htm b/docsrc/xlisp/xlisp-doc/reference/nthcdr.htm new file mode 100644 index 0000000..fa41dac --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/nthcdr.htm @@ -0,0 +1,75 @@ +<html><head><title>XLISP nthcdr</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>nthcdr</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(nthcdr <i>expr list-expr</i>)</dt>
+<dd><i>expr</i> - an integer expression<br>
+<i>list-expr</i> - a list or list expression<br>
+returns - the <a href="nth.htm">nth</a>
+<a href="cdr.htm">cdr</a> or
+<a href="nil.htm">NIL</a> if the list isn't that long</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>'nthcdr' returns the 'expr'-th <a href="cdr.htm">cdr</a>
+of 'list-expr'. If the 'list-expr' is shorter than 'exp',
+a <a href="nil.htm">NIL</a> is returned. The counting sequence
+is base zero, the first element is the 0th element.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(nthcdr 4 '(0 1 2 3 4 5 6)) <font color="#008844">; returns (4 5 6)</font>
+(nthcdr 3 '(a b)) <font color="#008844">; returns NIL</font>
+
+(nthcdr 4 'a) <font color="#008844">; error: bad argument type</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#nthcdr">nthcdr</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/null.htm b/docsrc/xlisp/xlisp-doc/reference/null.htm new file mode 100644 index 0000000..e683053 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/null.htm @@ -0,0 +1,80 @@ +<html><head><title>XLISP null</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>null</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(null <i>expr</i>)</dt>
+<dd><i>expr</i> - the expression to check<br>
+returns - <a href="t.htm"> T </a> if the list is
+empty, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'null' predicate function checks 'expr' for an empty list.
+<a href="t.htm"> T </a> is returned if the list is
+empty, <a href="nil.htm">NIL</a> is returned otherwise. The
+'expr' does not have to be a valid list, but if it is not a list then
+<a href="nil.htm">NIL</a> is returned as the result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(null '()) <font color="#008844">; returns T - empty list</font>
+(null ()) <font color="#008844">; returns T - still empty</font>
+(setq a NIL) <font color="#008844">; set up a variable</font>
+(null a) <font color="#008844">; returns T - value = empty list</font>
+
+(null "a") <font color="#008844">; returns NIL - not a list</font>
+(null 'a) <font color="#008844">; returns NIL - not a list</font>
+</pre>
+
+<p><b>Note:</b> The 'null' predicate function is the same function as the
+<a href="not.htm">not</a> predicate function.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#null">null</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/number-equal.htm b/docsrc/xlisp/xlisp-doc/reference/number-equal.htm new file mode 100644 index 0000000..7316d17 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/number-equal.htm @@ -0,0 +1,87 @@ +<html><head><title>XLISP =</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>=</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(= <i>expr1 expr2</i> ...)</nobr></dt>
+<dd><i>exprN</i> - a numeric expression<br>
+returns - <a href="t.htm"> T </a> if the results of
+comparing the expressions are all true,
+<a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The <nobr>'=' [equality]</nobr> function takes an arbitrary number of
+numeric arguments. <nobr>It checks</nobr> to see if all the numbers are
+equal. <a href="t.htm"> T </a> is returned if all of the arguments
+are numerically equal to each other, <a href="nil.htm">NIL</a> is returned
+otherwise.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(= 1 1) => T
+(= 1 2) => NIL
+(= 1 1.0) => T
+(= 1 1.0 1 (+ 0 1)) => T
+(= 1 1.0 1.00001) => NIL
+(= "a" "b") => <font color="#AA0000">error: bad argument type</font>
+(setq a 1 b 1.0) => 1.0 <font color="#008844">; set up A and B with values</font>
+(= a b) => T
+</pre>
+
+<p>See <a href="setq.htm">setq</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/number-greaterp.htm b/docsrc/xlisp/xlisp-doc/reference/number-greaterp.htm new file mode 100644 index 0000000..a4cfe28 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/number-greaterp.htm @@ -0,0 +1,90 @@ +<html><head><title>XLISP ></title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>></h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(> <i>expr1 expr2</i> ...)</nobr></dt>
+<dd><i>exprN</i> - a numeric expression<br>
+returns - <a href="t.htm"> T </a> if the results of
+comparing the expressions are all true,
+<a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The <nobr>'>' [greater-than]</nobr> function takes an arbitrary number
+of numeric arguments. <nobr>It checks</nobr> to see if all the numbers are
+monotonically decreasing. <a href="t.htm"> T </a> is returned if
+the arguments are numerically, and monotonically decreasing,
+<a href="nil.htm">NIL</a> is returned otherwise. <nobr>For two</nobr>
+arguments, this has the effect of testing if 'expr1' is greater than
+'expr2'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(> 1 1) => NIL
+(> 1 2) => NIL
+(> 2.0 1.99) => T
+(> 3 2 1) => T
+(> 3 2 2) => NIL
+(> "aa" "aa") => <font color="#AA0000">error: bad argument type</font>
+(setq a 12 b 99.9) => 99.9 <font color="#008844">; set up A and B with values</font>
+(> a b) => NIL
+(> b a) => T
+</pre>
+
+<p>See <a href="setq.htm">setq</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/number-lessp.htm b/docsrc/xlisp/xlisp-doc/reference/number-lessp.htm new file mode 100644 index 0000000..d1ba84a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/number-lessp.htm @@ -0,0 +1,90 @@ +<html><head><title>XLISP <</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1><</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(< <i>expr1 expr2</i> ...)</nobr></dt>
+<dd><i>exprN</i> - a numeric expression<br>
+returns - <a href="t.htm"> T </a> if the results of
+comparing the expressions are all true,
+<a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The <nobr>'<' [less-than]</nobr> function takes an arbitrary number
+of numeric arguments. It checks to see if all the numbers are monotonically
+increasing. <a href="t.htm"> T </a> is returned if
+the arguments are numerically, and monotonically increasing,
+<a href="nil.htm">NIL</a> is returned otherwise. In the case of
+two arguments, this has the effect of testing if 'expr1' is less than
+'expr2'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(< 1 2) => T
+(< 1 1) => NIL
+(< -1.5 -1.4) => T
+(< 1 2 3 4) => T
+(< 1 2 3 2) => NIL
+(< "a" "b") => <font color="#AA0000">error: bad argument type</font>
+(setq a 12 b 13.99) => 13.99 <font color="#008844">; set up A and B with values</font>
+(< a b) => T
+(< b a) => NIL
+</pre>
+
+<p>See <a href="setq.htm">setq</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/number-not-equal.htm b/docsrc/xlisp/xlisp-doc/reference/number-not-equal.htm new file mode 100644 index 0000000..595836b --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/number-not-equal.htm @@ -0,0 +1,101 @@ +<html><head><title>XLISP /=</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>/=</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(/= <i>expr1</i> <i>expr2</i> ...)</nobr></dt>
+<dd><i>exprN </i> - a numeric expression<br>
+returns - <a href="t.htm"> T </a> if the results of
+comparing the expressions are all true,
+<a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The <nobr>'/=' [not-equal]</nobr> function takes an arbitrary number of
+numeric arguments. It checks to see if all the numeric arguments are
+different. <a href="t.htm"> T </a> is returned if
+the arguments are numerically not equivalent,
+<a href="nil.htm">NIL</a> is returned otherwise.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(/= 1 1) => NIL
+(/= 1 2) => T
+(/= 1 1.0) => NIL
+(/= 1 2 3) => T
+(/= 1 2 2) => NIL
+(/= "a" "b") => <font color="#AA0000">error: bad argument type</font>
+(setq a 1 b 12.4) => 12.4 <font color="#008844">; set up A and B with values</font>
+(/= a b) => NIL
+</pre>
+
+<p>See <a href="setq.htm">setq</a>.</p>
+
+<p><div class="box">
+
+<p><b>XLISP Bug</b></p>
+
+<pre class="example">
+(/= 1 2 3) => T <font color="#008844">; OK</font>
+(/= 1 2 3 2 1) => T <font color="#AA0000">; wrong</font>
+</pre>
+
+<p>This is only a problem for the '/=' function. <nobr>The bug</nobr> can be
+reproduced with <nobr>Nyquist 3.03</nobr> <nobr>in November 2010</nobr>.</p>
+
+</div></p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/number-not-greaterp.htm b/docsrc/xlisp/xlisp-doc/reference/number-not-greaterp.htm new file mode 100644 index 0000000..c9401a4 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/number-not-greaterp.htm @@ -0,0 +1,91 @@ +<html><head><title>XLISP <=</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1><=</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<= <i>expr1 expr2</i> ...)</nobr></dt>
+<dd><i>exprN</i> - a numeric expression<br>
+returns - <a href="t.htm"> T </a> if the results of
+comparing the expressions are all true,
+<a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The <nobr>'<=' [less-than-or-equal]</nobr> function takes an arbitrary
+number of numeric arguments. <nobr>It checks</nobr> to see if all the
+numbers are monotonically <nobr>non-decreasing</nobr>.
+<a href="t.htm"> T </a> is returned if the arguments
+are numerically, and monotonically <nobr>non-decreasing</nobr>,
+<a href="nil.htm">NIL</a> is returned otherwise. <nobr>For two</nobr>
+arguments, this has the effect of testing if 'expr1' is less than or equal
+<nobr>to 'expr2'</nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(<= 1 1) => T
+(<= 1 2) => T
+(<= 2.0 1.99) => NIL
+(<= 1 2 3 3) => T
+(<= 1 2 3 3 2) => NIL
+(<= "aa" "aa") => <font color="#AA0000">error: bad argument type</font>
+(setq a 12 b 99.9) => 99.9 <font color="#008844">; set up A and B with values</font>
+(<= a b) => T
+(<= b a) => NIL
+</pre>
+
+<p>See <a href="setq.htm">setq</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/number-not-lessp.htm b/docsrc/xlisp/xlisp-doc/reference/number-not-lessp.htm new file mode 100644 index 0000000..c9626d8 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/number-not-lessp.htm @@ -0,0 +1,92 @@ +<html><head><title>XLISP >=</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>>=</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(>= <i>expr1 expr2</i> ...)</nobr></dt>
+<dd><i>exprN</i> - a numeric expression<br>
+returns - <a href="t.htm"> T </a> if the results of
+comparing the expressions are all true,
+<a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The <nobr>'>=' [greater-than-or-equal]</nobr> function takes an
+arbitrary number of numeric arguments. <nobr>It checks</nobr> to see if all
+the numbers are monotonically <nobr>non-increasing</nobr>.
+<a href="t.htm"> T </a> is returned if 'expr1' is the arguments
+are numerically, and monotonically <nobr>non-increasing</nobr>,
+<a href="nil.htm">NIL</a> is returned otherwise. <nobr>For two</nobr>
+arguments, this has the effect of testing if 'expr1' is greater than or
+equal <nobr>to 'expr2'</nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(>= 1 2) => NIL
+(>= 1 1) => T
+(>= -1.5 -1.4) => NIL
+(>= 3 2 1) => T
+(>= 3 2 2) => T
+(>= 3 2 3) => NIL
+(>= "aa" "abc") => <font color="#AA0000">error: bad argument type</font>
+(setq a 12 b 13.9) => 13.9 <font color="#008844">; set up A and B with values</font>
+(>= a b) => NIL
+(>= b a) => T
+</pre>
+
+<p>See <a href="setq.htm">setq</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/numberp.htm b/docsrc/xlisp/xlisp-doc/reference/numberp.htm new file mode 100644 index 0000000..37e994f --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/numberp.htm @@ -0,0 +1,78 @@ +<html><head><title>XLISP numberp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>numberp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(numberp <i>expr</i>)</dt>
+<dd><i>expr</i> - the expression to check<br>
+returns - <a href="t.htm"> T </a> if the expression
+is a number, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'numberp' predicate function checks if an 'expr' is a number.
+<a href="t.htm"> T </a> is returned if 'expr' is an
+integer or floating point number, <a href="nil.htm">NIL</a> is
+returned otherwise.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(numberp 1) <font color="#008844">; returns T - integer</font>
+(numberp 1.2) <font color="#008844">; returns T - float</font>
+(numberp '1) <font color="#008844">; returns T - still an integer</font>
+(numberp #x034) <font color="#008844">; returns T - the readmacro produces an integer</font>
+
+(numberp 'a) <font color="#008844">; returns NIL - symbol</font>
+(numberp #\a) <font color="#008844">; returns NIL - character</font>
+(numberp NIL) <font color="#008844">; returns NIL - NIL</font>
+(numberp #(0 1 2)) <font color="#008844">; returns NIL - array</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#numberp">numberp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/object.htm b/docsrc/xlisp/xlisp-doc/reference/object.htm new file mode 100644 index 0000000..5c6ede3 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/object.htm @@ -0,0 +1,120 @@ +<html><head><title>XLISP object</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>object</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>object</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlobj.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> object</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>'object' is an object <a href="class.htm">class</a>. An object
+is a composite structure that contains internal state information, methods
+[which respond to messages], a pointer to the object's
+<a href="class.htm">class</a> and a pointer to the object's
+super-class. XLISP contains two built in objects: 'object' and
+<a href="class.htm">class</a>. 'object' is the superclass for the
+<a href="class.htm">class</a> object.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(send object :show) <font color="#008844">; look at the object definition</font>
+
+ <font color="#008844">; example use of objects</font>
+(setq my-class (send class :new '(state))) <font color="#008844">; new class MY-CLASS with STATE</font>
+
+(send my-class :answer :isnew '() <font color="#008844">; set up initialization</font>
+ '((setq state nil) self))
+
+(send my-class :answer :set-it '(value) <font color="#008844">; create :SET-IT message</font>
+ '((setq state value)))
+
+(setq my-obj (send my-class :new)) <font color="#008844">; create MY-OBJ out of MY-CLASS</font>
+(send my-obj :set-it 5) <font color="#008844">; STATE is set to 5</font>
+</pre>
+
+<p><b>Object definition:</b> The internal definition of the 'object' object
+instance is:</p>
+
+<pre class="example">
+Object is #<Object: #23fd8>, Class is #<Object: #23fe2>
+ MESSAGES = ((:SHOW . #<Subr-: #23db2>)
+ (:CLASS . #<Subr-: #23dee>)
+ (:ISNEW . #<Subr-: #23e2a>))
+ IVARS = NIL
+ CVARS = NIL
+ CVALS = NIL
+ SUPERCLASS = NIL
+ IVARCNT = 0
+ IVARTOTAL = 0
+#<Object: #23fd8>
+</pre>
+
+<p>The <a href="class.htm">class</a> of 'object' is
+<a href="class.htm">class</a>. There is no superclass of 'object'.
+Remember that the location information [like #23fd8] varies from system to
+system, yours will probably look different.</p>
+
+<p><b>Built-in methods:</b> The built in methods in XLISP include:</p>
+
+<ul>
+<li><nobr><a href="keyword-answer.htm">:answer</a> - add a method to an object</nobr></li>
+<li><nobr><a href="keyword-class.htm">:class</a> - return the object's <a href="class.htm">class</a></nobr></li>
+<li><nobr><a href="keyword-isnew.htm">:isnew</a> - run initialization code on object</nobr></li>
+<li><nobr><a href="keyword-new.htm">:new</a> - create a new object [instance or <a href="class.htm">class</a>]</nobr></li>
+<li><nobr><a href="keyword-show.htm">:show</a> - show the internal state of the object</nobr></li>
+</ul>
+
+<p><b>Message structure:</b> The normal XLISP convention for a 'message' is
+to have a valid symbol preceeded by a colon like
+<a href="keyword-isnew.htm">:isnew</a> or ':my-message'. However, it is
+possible to define a 'message' that is a symbol without a colon, but this
+makes the code less readable.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-010.htm#object">object</a>
+class in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/objectp.htm b/docsrc/xlisp/xlisp-doc/reference/objectp.htm new file mode 100644 index 0000000..22ea9b9 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/objectp.htm @@ -0,0 +1,72 @@ +<html><head><title>XLISP objectp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>objectp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(objectp expr)</dt>
+<dd><i>expr</i> - the expression to check<br>
+returns - <a href="t.htm"> T </a> if the expression
+is an object, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'objectp' predicate function checks if the 'expr' is an object.
+<a href="t.htm"> T </a> is returned if 'expr' is
+an object, <a href="nil.htm">NIL</a> is returned otherwise.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(objectp object) <font color="#008844">; returns T</font>
+(objectp class) <font color="#008844">; returns T</font>
+(objectp NIL) <font color="#008844">; returns NIL</font>
+(objectp '(a b)) <font color="#008844">; returns NIL</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#objectp">objectp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/oddp.htm b/docsrc/xlisp/xlisp-doc/reference/oddp.htm new file mode 100644 index 0000000..fa71431 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/oddp.htm @@ -0,0 +1,92 @@ +<html><head><title>XLISP oddp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>oddp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(oddp <i>expr</i>)</dt>
+<dd><i>expr</i> - the integer numeric expression to check<br>
+returns - <a href="t.htm"> T </a> if the integer is
+odd, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'oddp' predicate function checks to see if the number 'expr' is odd.
+<a href="t.htm"> T </a> is returned if the number is
+odd, <a href="nil.htm">NIL</a> is returned otherwise.</p>
+
+<p>An error is generated if the 'expr' is not a numeric expression:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument type</font>
+</pre>
+
+<p>An error is generated if the 'expr' is a floating point number:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad floating point operation</font>
+</pre>
+
+<p>Zero is an even number.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(oddp 0) <font color="#008844">; returns NIL</font>
+(oddp 1) <font color="#008844">; returns T</font>
+(oddp 2) <font color="#008844">; returns NIL</font>
+(oddp -1) <font color="#008844">; returns T</font>
+(oddp -2) <font color="#008844">; returns NIL</font>
+
+(oddp 13.0) <font color="#008844">; error: bad floating point operation</font>
+(oddp 'a) <font color="#008844">; error: bad argument type</font>
+(setq a 3) <font color="#008844">; set value of A to 3</font>
+(oddp a) <font color="#008844">; returns T</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#oddp">oddp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/open-binary.htm b/docsrc/xlisp/xlisp-doc/reference/open-binary.htm new file mode 100644 index 0000000..1707407 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/open-binary.htm @@ -0,0 +1,103 @@ +<html><head><title>XLISP open-binary</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>open-binary</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(open-binary <i>file</i> [:direction <i>in-out</i>])</dt>
+<dd><i>file</i> - a string expression or symbol<br>
+<i>in-out</i> - an optional keyword symbol that must be either ':input' or
+':output'. The default is ':input'.<br>
+returns - a stream</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The '<nobr>open-binary</nobr>' function opens the 'file' for binary input
+or output. The 'file' may be a string expression or a symbol. Following the
+'file', there is an optional keyword, ':direction'. The argument following
+this is either ':input' or ':output' which specifies the direction of the
+file. <nobr>If no</nobr> ':direction' is specified, the default is ':input'.
+When 'file' is a string, you may specify a complete file location or
+extensions like "/usr/local/bin/myfile.lsp" or
+"A:\LISP\TIM.BAT". <nobr>If the</nobr> file open was successful,
+then a file pointer of the following form is returned as the result:</p>
+
+<pre class="example">
+#<File: #99999>
+</pre>
+
+<p>If the file open was not successful, a <a href="nil.htm">NIL</a> is
+returned. <nobr>For an</nobr> input file, the file has to exist, or an error
+will be signaled.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p>This will create a file named FOO-FILE, because XLISP uppercases its
+symbols:</p>
+
+<pre class="example">
+(open-binary 'foo-file :direction :output)
+</pre>
+
+<p>This will create a file named 'foo-file' because UNIX doesn't
+uppercase its file names:</p>
+
+<pre class="example">
+(open-binary "foo-file" :direction :output)
+</pre>
+
+<p>So, if you are having trouble with opening and accessing files, check to
+make sure the file name is in the proper case.</p>
+
+<p>See also <a href="bigendianp.htm">bigendianp</a>,
+<nobr><a href="read-int.htm">read-int</a></nobr>,
+<nobr><a href="write-int.htm">write-int</a></nobr>,
+<nobr><a href="read-float.htm">read-float</a></nobr>,
+<nobr><a href="write-float.htm">write-float</a></nobr>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/open.htm b/docsrc/xlisp/xlisp-doc/reference/open.htm new file mode 100644 index 0000000..fe2a925 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/open.htm @@ -0,0 +1,117 @@ +<html><head><title>XLISP open</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>open</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(open <i>file</i> [:direction <i>in-out</i>])</dt>
+<dd><i>file</i> - a string expression or symbol<br>
+<i>in-out</i> - an optional keyword symbol that must be either ':input' or
+':output'. The default is ':input'.<br>
+returns - a stream</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'open' function opens the 'file' for input or output. The 'file' may
+be a string expression or a symbol. Following the 'file', there is an
+optional keyword, ':direction'. The argument following this is either
+':input' or ':output' which specifies the direction of the file. If no
+':direction' is specified, the default is ':input'. When 'file' is a string,
+you may specify a complete file location or extensions like
+"/usr/local/bin/myfile.lsp" or "A:\LISP\TIM.BAT". If
+the file open was successful, then a file pointer of the following form is
+returned as the result:</p>
+
+<pre class="example">
+#<File: #99999>
+</pre>
+
+<p>If the file open was not successful, a
+<a href="nil.htm">NIL</a> is returned. For an input file, the
+file has to exist, or an error will be signaled.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq f (open 'mine :direction :output)) <font color="#008844">; create file named MINE</font>
+(print "hi" f) <font color="#008844">; returns "hi"</font>
+(close f) <font color="#008844">; file contains "hi" <newline></font>
+(setq f (open 'mine :direction :input)) <font color="#008844">; open MYFILE for input</font>
+(read f) <font color="#008844">; returns "hi"</font>
+(close f) <font color="#008844">; close it</font>
+</pre>
+
+<p><b>File names:</b> In the PC and DOS world, all file names and extensions
+["foo.bat"] are automatically made uppercase. In using XLISP, this
+means you don't have to worry about whether the name is "foo.bat",
+"FOO.BAT" or even "FoO.bAt", they will all work.
+However, in other file systems [UNIX in particular], uppercase and lowercase
+do make a difference:</p>
+
+<p>This will create a file named FOO-FILE in UNIX, because XLISP uppercases
+its symbols:</p>
+
+<pre class="example">
+(open 'foo-file :direction :output)
+</pre>
+
+<p>This will create a file named 'foo-file' because UNIX doesn't
+uppercase its file names:</p>
+
+<pre class="example">
+(open "foo-file" :direction :output)
+</pre>
+
+<p>So, if you are having trouble with opening and accessing files, check to
+make sure the file name is in the proper case.</p>
+
+<p><b>Common Lisp:</b> Common Lisp supports bidirectional files. So, porting
+Common Lisp code may be difficult to port if it uses these other file
+types.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-029.htm#open">open</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/or.htm b/docsrc/xlisp/xlisp-doc/reference/or.htm new file mode 100644 index 0000000..9900bdd --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/or.htm @@ -0,0 +1,87 @@ +<html><head><title>XLISP or</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>or</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(or [<i>expr1</i> ... ])</dt>
+<dd><i>exprN</i> - an expression<br>
+returns - <a href="nil.htm">NIL</a> if all expressions evaluate
+to <nobr><a href="nil.htm">NIL</a> ,</nobr> otherwise the value
+of the first non-<a href="nil.htm">NIL</a> expression<br>
+<b>Note:</b> evaluation of expressions stops after the first expression
+that does not evaluate to <a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'or' special form evaluates a sequence of expressions and returns the
+effect of a logical 'inclusive-or' operation on the expressions. If all of
+the expressions are <nobr><a href="nil.htm">NIL</a> ,</nobr>
+<a href="nil.htm">NIL</a> is returned as the result. Evaluation
+of the expressions will stop when an expression evaluates to something other
+than <nobr><a href="nil.htm">NIL</a> ,</nobr> none of the
+subsequent expressions will be evaluated. If there are no expressions, 'or'
+returns <a href="nil.htm">NIL</a> as its result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(or NIL NIL NIL) <font color="#008844">; returns NIL</font>
+(or NIL T NIL) <font color="#008844">; returns T</font>
+(or NIL (princ "hi") (princ "ho")) <font color="#008844">; prints hi and returns "hi"</font>
+(or T T T) <font color="#008844">; returns T</font>
+(or) <font color="#008844">; returns NIL</font>
+
+(setq a 5) (setq b 6) <font color="#008844">; set up A and B</font>
+(if (or (< a b) (< b a)) <font color="#008844">; if</font>
+ (print "not equal") <font color="#008844">; then</font>
+ (print "equal")) <font color="#008844">; else</font>
+ <font color="#008844">; prints "not equal"</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-019.htm#or">or</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/peek-char.htm b/docsrc/xlisp/xlisp-doc/reference/peek-char.htm new file mode 100644 index 0000000..8111cf4 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/peek-char.htm @@ -0,0 +1,105 @@ +<html><head><title>XLISP peek-char</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>peek-char</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(peek-char [<i>skip-flag</i> [<i>source</i>]])</dt>
+<dd><i>skip-flag</i> - an optional expression, default is
+<a href="nil.htm">NIL</a><br>
+<i>source</i> - an optional source, must be a file pointer or stream, default
+is <a href="global-standard-input.htm">*standard-input*</a><br>
+returns - the character</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'peek-char' function looks at a single character from the specified
+'source'. The character looked-at is returned as an integer value for the
+result. If the 'skip-flag' expression is
+<nobr><a href="nil.htm">NIL</a> ,</nobr> then the next character
+will be looked-at, without advancing the position within the file. If the
+'skip-flag' expression is <nobr>non-<a href="nil.htm">NIL</a>
+,</nobr> then the next non-white-space character will be looked-at. This
+skipping does advance the position within the file. White-space characters
+include 'blank', 'tab' and 'new-line' characters. If 'skip-flag' is not
+used, no skipping will occur. The 'source' may be a file pointer or a
+stream. If there is no 'source',
+<a href="global-standard-input.htm">*standard-input*</a> is the default. If an
+end-of-file is encountered in the 'source', then
+<a href="nil.htm">NIL</a> will be returned as the result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq fp (open "f" :direction :output)) <font color="#008844">; create file "f"</font>
+(print 12 fp)
+(princ " 34" fp)
+(terpri fp)
+(close fp)
+
+(setq fp (open "f" :direction :input)) <font color="#008844">; open "f" for reading</font>
+(peek-char NIL fp) <font color="#008844">; returns #\1</font>
+(peek-char NIL fp) <font color="#008844">; returns #\1 - didn't advance</font>
+(read-char fp) <font color="#008844">; returns #\1 - force advance</font>
+(peek-char NIL fp) <font color="#008844">; returns #\2</font>
+(read-char fp) <font color="#008844">; returns #\2 - force advance</font>
+(peek-char NIL fp) <font color="#008844">; returns #\Newline</font>
+(peek-char T fp) <font color="#008844">; returns #\3 - skipped blanks</font>
+(read-line fp) <font color="#008844">; returns "34"</font>
+(close fp)
+</pre>
+
+<p><b>Common Lisp:</b> The XLISP and Common Lisp 'peek-char' functions are
+compatible for simple cases. They both allow for the optional 'skip-flag'
+and 'source'. However, in Common Lisp, there are additional parameters which
+occur right after 'source' that support various end-of-file operations and
+recursive calls. So, when porting from Common Lisp to XLISP, remember there
+are additional arguments in Common Lisp's 'peek-char' that are not supported
+in XLISP.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-029.htm#peek-char">peek-char</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/peek.htm b/docsrc/xlisp/xlisp-doc/reference/peek.htm new file mode 100644 index 0000000..58e2cec --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/peek.htm @@ -0,0 +1,86 @@ +<html><head><title>XLISP peek</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>peek</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlsys.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(peek <i>address</i>)</dt>
+<dd><i>address</i> - an integer expression<br>
+returns - the value at the specified address as an integer</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'peek' function returns the internal memory value at the 'address'.
+The returned value is an integer.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq var 0) <font color="#008844">; set up VAR with 0</font>
+(address-of var) <font color="#008844">; returns 123224</font>
+(address-of 'var) <font color="#008844">; returns 161922</font>
+(peek (address-of var)) <font color="#008844">; returns 83951616</font>
+(peek (1+ (address-of var))) <font color="#008844">; returns 16777216</font>
+(peek (+ 2 (address-of var))) <font color="#008844">; returns 0 <-- value of VAR</font>
+(setq var 14) <font color="#008844">; change the value to 14</font>
+(peek (+ 2 (address-of var))) <font color="#008844">; returns 14</font>
+(setq var 99) <font color="#008844">; change the value to 99</font>
+(peek (+ 2 (address-of var))) <font color="#008844">; returns 99</font>
+</pre>
+
+<p><b>Caution:</b> Be careful when modifying the internal state of XLISP. If
+you have modified it, it would be a good idea to exit XLISP and re-enter
+before doing any work you really want to retain.</p>
+
+<p><b>Caution:</b> It is possible to 'peek' and
+<a href="poke.htm">poke</a> not just XLISP's memory put other
+parts of your computer's memory. Be very careful when doing this. Also, in
+some computers, just looking at a memory location can cause things to
+happen, I/O locations fall in this category.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-031.htm#peek">peek</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/pi.htm b/docsrc/xlisp/xlisp-doc/reference/pi.htm new file mode 100644 index 0000000..9be3a2a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/pi.htm @@ -0,0 +1,66 @@ +<html><head><title>XLISP rrandom</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>rrandom</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>dspprims.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><b>pi</b></dt>
+<dd>returns - a floating point value of 3.14159265358979</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'pi' variable returns a floating point approximation of the
+<nobr>number 'pi'</nobr>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+pi => 3.14159265358979
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/plus.htm b/docsrc/xlisp/xlisp-doc/reference/plus.htm new file mode 100644 index 0000000..b5e3984 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/plus.htm @@ -0,0 +1,75 @@ +<html><head><title>XLISP + (variable)</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>+ <font color="#444444">(variable)</font></h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>variable</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.c, xlisp.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt> +</dt>
+<dd>returns - the most recent input expression</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The '+' variable is set to the most recent input expression.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq hi 'there) => THERE
++ => (SETQ HI (QUOTE THERE))
++ => +
+</pre>
+
+<p>See <a href="setq.htm">setq</a>.</p>
+
+<p><b>Note:</b> The '+' variable is for interactive programming. <nobr>It
+is</nobr> not recommended to use the '+' variable in program code.</p>
+
+<p>See also the
+<nobr><a href="../manual/xlisp.htm#command-loop">XLISP Command Loop</a></nobr>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/poke.htm b/docsrc/xlisp/xlisp-doc/reference/poke.htm new file mode 100644 index 0000000..336ca39 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/poke.htm @@ -0,0 +1,88 @@ +<html><head><title>XLISP poke</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>poke</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlsys.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(poke <i>address expr</i>)</dt>
+<dd><i>address</i> - an integer expression<br>
+<i>expr</i> - an integer expression<br>
+returns - the value</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'poke' function writes the 'expr' at the internal memory value at the
+specified 'address'. The returned value is 'expr'. Be very careful with this
+function.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq var 0) <font color="#008844">; set up VAR with 0</font>
+(address-of var) <font color="#008844">; returns 123224</font>
+(address-of 'var) <font color="#008844">; returns 161922</font>
+(peek (address-of var)) <font color="#008844">; returns 83951616</font>
+(peek (1+ (address-of var))) <font color="#008844">; returns 16777216</font>
+(peek (+ 2 (address-of var))) <font color="#008844">; returns 0 <-- value of VAR</font>
+(setq var 14) <font color="#008844">; change the value to 14</font>
+(peek (+ 2 (address-of var))) <font color="#008844">; returns 14</font>
+(poke (+ 2 (address-of var)) 1023) <font color="#008844">; POKE the value to 1023</font>
+(print var) <font color="#008844">; prints 1023</font>
+</pre>
+
+<p><b>Caution:</b> Be careful when modifying the internal state of XLISP. If
+you have modified it, it would be a good idea to exit XLISP and re-enter
+before doing any work you really want to retain.</p>
+
+<p><b>Caution:</b> It is possible to <a href="peek.htm">peek</a>
+and 'poke' not just XLISP's memory put other parts of your computer's
+memory. Be very careful when doing this. Also, in some computers, just
+looking at a memory location can cause things to happen, I/O locations fall
+in this category.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-031.htm#poke">poke</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/pop.htm b/docsrc/xlisp/xlisp-doc/reference/pop.htm new file mode 100644 index 0000000..73165ca --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/pop.htm @@ -0,0 +1,85 @@ +<html><head><title>XLISP pop</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>pop</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp macro</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>misc.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>pop</b> <i>list</i>)</dt>
+<dd><i>list</i> - a list<br>
+returns - the first element from the list</dd>
+</dl>
+
+</div></p>
+
+<p>'pop' is implemented as a Lisp macro:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">pop</font> (lis)
+ `(prog1 (car ,lis)
+ (setf ,lis (cdr ,lis))))
+</pre>
+
+<h2>Description</h2>
+
+<p>The 'pop' macro reads, removes and returns the first element from the
+list.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq stack '(a b c)) => (A B C)
+(pop stack) => A
+stack => (B C)
+(pop stack) => B
+stack => (C)
+(pop stack) => C
+stack => NIL
+(pop stack) => NIL
+stack => NIL
+</pre>
+
+<p>See <a href="setq.htm">setq</a>. See also the <a href="push.htm">push</a> macro.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/power.htm b/docsrc/xlisp/xlisp-doc/reference/power.htm new file mode 100644 index 0000000..6df1216 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/power.htm @@ -0,0 +1,77 @@ +<html><head><title>XLISP power</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>power</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp function (closure)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>misc.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>power</b> <i>x y</i>)</nobr></dt>
+<dd><i>x</i>, <i>y</i> - two integer or floating point numbers<br>
+returns - <i>x</i> raised to the <i>y</i> power as a floating point number</dd>
+</dl>
+
+</div></p>
+
+<p>In Nyquist, 'power' is implemented as a Lisp function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">power</font> (x y)
+ (exp (* (log (float x)) y)))
+</pre>
+
+<h2>Description</h2>
+
+<p>The 'power' function returns 'x' raised to the 'y' power as a floating
+point number.</nobr>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(power 2 8) => 256
+(power 4 .5) => 2.0
+</pre>
+
+<p>See also <a href="expt.htm">expt</a>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/pprint.htm b/docsrc/xlisp/xlisp-doc/reference/pprint.htm new file mode 100644 index 0000000..7ab7021 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/pprint.htm @@ -0,0 +1,94 @@ +<html><head><title>XLISP pprint</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>pprint</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlpp.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(pprint <i>expr</i> [<i>dest</i>])</dt>
+<dd><i>expr</i> - an expression to be pretty printed<br>
+<i>dest</i> - an optional destination, must be a file pointer or
+stream, default is <a href="global-standard-output.htm">*standard-output*</a><br>
+returns - always returns <a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'pprint' function produces a pretty looking version of the 'expr' and
+prints it to the specified 'destination'. If 'expr' is an atom like a
+string, a symbol, a number, etc., 'pprint' will print it like
+<a href="print.htm">print</a>. If 'expr' is a list, it will perform
+indenting, as necessary. <a href="nil.htm">NIL</a> is always
+returned as the result of 'pprint'. The 'destination' may be a file pointer
+or a stream. If there is no 'destination' or it is
+<nobr><a href="nil.htm">NIL</a> ,</nobr>
+<a href="global-standard-output.htm">*standard-output*</a> is the default.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(pprint 'a) <font color="#008844">; prints A returns NIL</font>
+(pprint "abcd") <font color="#008844">; prints "abcd" returns NIL</font>
+
+(pprint '(a-very-long-name (first list) (second list)))
+
+ <font color="#008844">; prints (A-VERY-LONG-NAME (FIRST LIST)</font>
+ <font color="#008844">; (SECOND LIST))</font>
+ <font color="#008844">; returns NIL</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp specifies that 'pprint' with a
+'destination' of <a href="nil.htm">NIL</a> will go to
+<a href="global-standard-output.htm">*standard-output*</a>. XLISP does not send the
+output to <a href="global-standard-output.htm">*standard-output*</a> with a
+'destination' of <a href="nil.htm">NIL</a>. Common Lisp also
+specifies that a 'destination' of
+<a href="t.htm"> T </a> will be sent to
+*terminal-io*, which is not defined in XLISP by default. XLISP does not
+allow <a href="t.htm"> T </a> as a valid argument
+for 'destination'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-027.htm#pprint">pprint</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/prin1.htm b/docsrc/xlisp/xlisp-doc/reference/prin1.htm new file mode 100644 index 0000000..c0b8a7c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/prin1.htm @@ -0,0 +1,94 @@ +<html><head><title>XLISP prin1</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>prin1</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c, xlprin.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(prin1 <i>expr</i> [<i>dest</i>])</dt>
+<dd><i>expr</i> - an expression<br>
+<i>dest</i> - an optional destination, must be a file pointer or
+stream, default is <a href="global-standard-output.htm">*standard-output*</a><br>
+returns - the expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'prin1' function prints the 'expr' to the specified 'destination'.
+The 'expr' is printed without a 'newline' character. If 'expr' is a string,
+it will be printed with quotes around the string. The 'expr' is returned as
+the result. The 'destination' may be a file pointer or a stream. If there is
+no 'destination', <a href="global-standard-output.htm">*standard-output*</a> is the
+default. The <a href="terpri.htm">terpri</a> function is used to
+terminate the print lines produced.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(prin1 'a) <font color="#008844">; prints A without #\Newline</font>
+(prin1 '(a b)) <font color="#008844">; prints (A B) without #\Newline</font>
+(prin1 2.5) <font color="#008844">; prints 2.5 without #\Newline</font>
+(prin1 "hi") <font color="#008844">; prints "hi" without #\Newline</font>
+
+(setq f (open "f" :direction :output)) <font color="#008844">; create file</font>
+(prin1 "hi" f) <font color="#008844">; returns "hi"</font>
+(prin1 1234 f) <font color="#008844">; returns 1234</font>
+(prin1 "he" f) <font color="#008844">; returns "he"</font>
+(close f) <font color="#008844">; file contains "hi"1234"he"</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp specifies that 'pprint' with a
+'destination' of <a href="nil.htm">NIL</a> will go to
+<a href="global-standard-output.htm">*standard-output*</a>. XLISP does not send the
+output to <a href="global-standard-output.htm">*standard-output*</a> with a
+'destination' of <a href="nil.htm">NIL</a>. Common Lisp also
+specifies that a 'destination' of
+<a href="t.htm"> T </a> will be sent to
+*terminal-io*, which is not defined in XLISP by default. XLISP does not
+allow <a href="t.htm"> T </a> as a valid argument
+for 'destination'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-027.htm#prin1">prin1</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/princ.htm b/docsrc/xlisp/xlisp-doc/reference/princ.htm new file mode 100644 index 0000000..a3a095f --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/princ.htm @@ -0,0 +1,94 @@ +<html><head><title>XLISP princ</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>princ</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c, xlprin.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(princ <i>expr</i> [<i>dest</i>])</dt>
+<dd><i>expr</i> - an expression<br>
+<i>dest</i> - an optional destination, must be a file pointer or
+stream, default is <a href="global-standard-output.htm">*standard-output*</a><br>
+returns - the expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'princ' function prints the 'expr' to the specified 'destination'.
+The 'expr' is printed without a 'newline' character. If 'expr' is a string,
+it will not be printed with quotes around the string. The 'expr' is returned
+as the result. The 'destination' may be a file pointer or a stream. If there
+is no 'destination', <a href="global-standard-output.htm">*standard-output*</a> is
+the default. The <a href="terpri.htm">terpri</a> function is used to
+terminate the print lines produced.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(princ 'a) <font color="#008844">; prints A without #\Newline</font>
+(princ '(a b)) <font color="#008844">; prints (A B) without #\Newline</font>
+(princ 99) <font color="#008844">; prints 99 without #\Newline</font>
+(princ "hi") <font color="#008844">; prints hi without #\Newline</font>
+
+(setq f (open "f" :direction :output)) <font color="#008844">; create file</font>
+(princ "hi" f) <font color="#008844">; returns "hi"</font>
+(princ 727 f) <font color="#008844">; returns 727</font>
+(princ "ho" f) <font color="#008844">; returns "ho"</font>
+(close f) <font color="#008844">; file contains hi727ho</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp specifies that 'pprint' with a
+'destination' of <a href="nil.htm">NIL</a> will go to
+<a href="global-standard-output.htm">*standard-output*</a>. XLISP does not send the
+output to <a href="global-standard-output.htm">*standard-output*</a> with a
+'destination' of <a href="nil.htm">NIL</a>. Common Lisp also
+specifies that a 'destination' of
+<a href="t.htm"> T </a> will be sent to
+*terminal-io*, which is not defined in XLISP by default. XLISP does not
+allow <a href="t.htm"> T </a> as a valid argument
+for 'destination'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-027.htm#princ">princ</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/print.htm b/docsrc/xlisp/xlisp-doc/reference/print.htm new file mode 100644 index 0000000..d714844 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/print.htm @@ -0,0 +1,95 @@ +<html><head><title>XLISP print</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>print</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c, xlprin.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(print <i>expr</i> [<i>dest</i>])</dt>
+<dd><i>expr</i> - an expression<br>
+<i>dest</i> - an optional destination, must be a file pointer or
+stream, default is <a href="global-standard-output.htm">*standard-output*</a><br>
+returns - the expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'print' function prints the 'expr' to the specified 'destination'.
+The 'expr' is printed followed by a 'newline' character. If 'expr' is a
+string, it will be printed with quotes around the string. The 'expr' is
+returned as the result. The 'destination' may be a file pointer or a stream.
+If there is no 'destination',
+<a href="global-standard-output.htm">*standard-output*</a> is the default.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(print 'a) <font color="#008844">; prints A with #\Newline</font>
+(print '(a b)) <font color="#008844">; prints (A B) with #\Newline</font>
+(print 99) <font color="#008844">; prints 99 with #\Newline</font>
+(print "hi") <font color="#008844">; prints "hi" with #\Newline</font>
+
+(setq f (open "f" :direction :output)) <font color="#008844">; create file</font>
+(print "hi" f) <font color="#008844">; returns "hi"</font>
+(print 727 f) <font color="#008844">; returns 727</font>
+(print "ho" f) <font color="#008844">; returns "ho"</font>
+(close f) <font color="#008844">; file contains "hi"#\Newline</font>
+ <font color="#008844">; 727#\Newline</font>
+ <font color="#008844">; "ho"#\Newline</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp specifies that 'pprint' with a
+'destination' of <a href="nil.htm">NIL</a> will go to
+<a href="global-standard-output.htm">*standard-output*</a>. XLISP does not send the
+output to <a href="global-standard-output.htm">*standard-output*</a> with a
+'destination' of <a href="nil.htm">NIL</a>. Common Lisp also
+specifies that a 'destination' of
+<a href="t.htm"> T </a> will be sent to
+*terminal-io*, which is not defined in XLISP by default. XLISP does not
+allow <a href="t.htm"> T </a> as a valid argument
+for 'destination'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-027.htm#print">print</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/profile.htm b/docsrc/xlisp/xlisp-doc/reference/profile.htm new file mode 100644 index 0000000..0c3cf6a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/profile.htm @@ -0,0 +1,85 @@ +<html><head>
+
+<title>Profiling</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>profile</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlsys.c, xleval.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<a name="profile"></a>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>profile</b> <i>flag</i>) - turn profiling on or off</dt>
+<dd><i>flag</i> - NIL turns profiling off, otherwise on<br>
+returns - the previous state of profiling</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The <nobr>Xlisp 2.0</nobr> release has been extended with a profiling
+facility, which counts how many times and where <a href="eval.htm">eval</a>
+is executed. <nobr>A separate</nobr> count is maintained for each named
+function, closure, or macro, and a count indicates an
+<a href="eval.htm">eval</a> in the immediately [lexically] enclosing named
+function, closure, or macro. Thus, the count gives an indication of the
+amount of time spent in a function, not counting nested function calls.</p>
+
+<p>The list of all functions executed is maintained on the global *profile*
+variable. These functions in turn have *profile* properties, which maintain
+the counts. The profile system merely increments counters and puts symbols
+on the *profile* list. <nobr>It is</nobr> up to the user to initialize data
+and gather results. Profiling is turned on or off with the 'profile'
+function.</p>
+
+<p>Unfortunately, methods cannot be profiled with this facility.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/reference/prog-star.htm b/docsrc/xlisp/xlisp-doc/reference/prog-star.htm new file mode 100644 index 0000000..98ba7b1 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/prog-star.htm @@ -0,0 +1,101 @@ +<html><head><title>XLISP prog*</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>prog*</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(prog* ([<i>binding</i> ... ]) [<i>expr</i> ... ])</dt>
+<dd><i>binding</i> - a variable binding which is can take one of
+<dl><dd><i>symbol</i><br>
+(<i>symbol init-expr</i>)</dd>
+<dl><dd><i>symbol</i> - a symbol<br>
+<i>init-expr</i> - an initialization expression for <i>symbol</i></dd></dl></dl>
+<i>expr</i> - expressions comprising the body of the loop which may contain
+<a href="return.htm">return</a>s,
+<a href="go.htm">go</a>s or tags for
+<a href="go.htm">go</a><br>
+returns - <a href="nil.htm">NIL</a> or the argument passed to
+the <a href="return.htm">return</a> function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'prog*' special form is basically a 'block' construct that contains
+symbols with optional initializations and a block of code [expressions] to
+evaluate. The 'prog*' special form evaluates its initializations in
+sequential order as opposed to <a href="">prog</a> which does it in no
+specified order. The first form after the 'prog*' is the 'binding' form. It
+contains a series of 'symbols' or 'bindings'. The 'binding' is a 'symbol'
+followed by an initialization expression 'init-expr'. If there is no
+'init-expr', the 'symbol' will be initialized to
+<a href="nil.htm">NIL</a>. The order of execution of the bindings
+is sequential. If a <a href="return.htm">return</a> form is
+evaluated, its value will be returned. Otherwise,
+<a href="nil.htm">NIL</a> is returned. When the 'prog*' is
+finished execution, the 'symbols' that were defined will no longer exist or
+retain their values.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(prog* (i j) <font color="#008844">; PROG* with vars I and J</font>
+ (print i) (print j)) <font color="#008844">; prints NIL NIL returns NIL</font>
+
+(prog* ((i 1) (j 2)) <font color="#008844">; PROG* with vars I and J</font>
+ (print i) (print j)
+ (return (+ i j))) <font color="#008844">; prints 1 2 returns 3</font>
+
+(prog* () (print "hello")) <font color="#008844">; prints "hello" returns NIL</font>
+
+(prog ((i 1) (j (+ i 1))) <font color="#008844">; PROG won't work due to order</font>
+ (print (+ i j)) ) <font color="#008844">; error: unbound variable - I</font>
+
+(prog* ((i 1) (j (+ i 1))) <font color="#008844">; PROG* will work due to order</font>
+ (print (+ i j)) ) <font color="#008844">; prints 3 returns NIL</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-021.htm#prog*">prog*</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/prog.htm b/docsrc/xlisp/xlisp-doc/reference/prog.htm new file mode 100644 index 0000000..ea1d29c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/prog.htm @@ -0,0 +1,96 @@ +<html><head><title>XLISP prog</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>prog</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(prog ([<i>binding</i> ... ]) [<i>expr</i> ... ])</dt>
+<dd><i>binding</i> - a variable binding which is can take one of
+<dl><dd><i>symbol</i><br>
+(<i>symbol init-expr</i>)</dd>
+<dl><dd><i>symbol</i> - a symbol<br>
+<i>init-expr</i> - an initialization expression for <i>symbol</i></dd></dl></dl>
+<i>expr</i> - expressions comprising the body of the loop which may contain
+<a href="return.htm">return</a>s,
+<a href="go.htm">go</a>s or tags for
+<a href="go.htm">go</a><br>
+returns - <a href="nil.htm">NIL</a> or the argument passed to
+the <a href="return.htm">return</a> function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'prog' special form is basically a 'block' construct that contains
+symbols with optional initializations and a block of code [expressions] to
+evaluate. The 'prog' special form evaluates its initializations in no
+specified order, as opposed to <a href="prog-star.htm">prog*</a> which
+does it sequential order. The first form after the 'prog' is the 'binding'
+form. It contains a series of 'symbols' or 'bindings'. The 'binding' is a
+'symbol' followed by an initialization expression 'init-expr'. If there is
+no 'init-expr', the 'symbol' will be initialized to
+<a href="nil.htm">NIL</a>. There is no specification as to the
+order of execution of the bindings or the step expressions, except that they
+happen all together. If a <a href="return.htm">return</a> form is
+evaluated, its value will be returned. Otherwise,
+<a href="nil.htm">NIL</a> is returned. When 'prog' is finished
+execution, the 'symbols' that were defined will no longer exist or retain
+their values.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(prog () (print "hello")) <font color="#008844">; prints "hello" returns NIL</font>
+
+(prog (i j) <font color="#008844">; PROG with vars I and J</font>
+ (print i) (print j)) <font color="#008844">; prints NIL NIL returns NIL</font>
+
+(prog ((i 1) (j 2)) <font color="#008844">; PROG with vars I and J</font>
+ (print i) (print j)
+ (return (+ i j))) <font color="#008844">; prints 1 2 returns 3</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-021.htm#prog">prog</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/prog1.htm b/docsrc/xlisp/xlisp-doc/reference/prog1.htm new file mode 100644 index 0000000..d56a1f0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/prog1.htm @@ -0,0 +1,80 @@ +<html><head><title>XLISP prog1</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>prog1</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(<i>prog1</i> [<i>expr1 expr2</i> ... ])</dt>
+<dd><i>exprN</i> - expressions comprising the body of the loop<br>
+returns - the value of the first expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'prog1' special form is basically a 'block' construct that contains a
+block of code [expressions] to evaluate. The value of the first expression
+'expr1' will be returned as the result of 'prog1'. If there is no 'expr1',
+<a href="nil.htm">NIL</a> is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(prog1 (print "hi") (print "ho")) <font color="#008844">; prints "hi" "ho" returns "hi"</font>
+(prog1) <font color="#008844">; returns NIL</font>
+(prog1 'a) <font color="#008844">; returns A</font>
+(prog1 "hey" (print "ho")) <font color="#008844">; prints "ho" returns "hey"</font>
+</pre>
+
+<p><b>Note:</b> 'prog1',
+<nobr><a href="prog2.htm">prog2</a> ,</nobr>
+<a href="progn.htm">progn</a> and
+<a href="progv.htm">progv</a> do not allow the use of
+<a href="return.htm">return</a> or
+<a href="go.htm">go</a> or tags for
+<a href="go.htm">go</a>.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-021.htm#prog1">prog1</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/prog2.htm b/docsrc/xlisp/xlisp-doc/reference/prog2.htm new file mode 100644 index 0000000..8ed5592 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/prog2.htm @@ -0,0 +1,82 @@ +<html><head><title>XLISP prog2</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>prog2</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(<i>prog2</i> [<i>expr1 expr2</i> ... ])</dt>
+<dd><i>exprN</i> - expressions comprising the body of the loop<br>
+returns - the value of the second expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'prog2' special form is basically a 'block' construct that contains a
+block of code [expressions] to evaluate. The value of the second expression
+'expr2' will be returned as the result of 'prog2'. If there is no 'expr2',
+'expr1' is returned. If there is no 'expr1',
+<a href="nil.htm">NIL</a> is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(prog2 (print "hi") (print "ho")) <font color="#008844">; prints "hi" "ho" returns "ho"</font>
+(prog2) <font color="#008844">; returns NIL</font>
+(prog2 (print "hi")) <font color="#008844">; prints "hi" returns "hi"</font>
+(prog2 (print "ho") "hey") <font color="#008844">; prints "ho" returns "hey"</font>
+(prog2 'a 'b 'c) <font color="#008844">; returns B</font>
+</pre>
+
+<p><b>Note:</b> <nobr><a href="prog1.htm">prog1</a> ,</nobr>
+'prog2',
+<a href="progn.htm">progn</a> and
+<a href="progv.htm">progv</a> do not allow the use of
+<a href="return.htm">return</a> or
+<a href="go.htm">go</a> or tags for
+<a href="go.htm">go</a>.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-021.htm#prog2">prog2</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/progn.htm b/docsrc/xlisp/xlisp-doc/reference/progn.htm new file mode 100644 index 0000000..9cb28a3 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/progn.htm @@ -0,0 +1,81 @@ +<html><head><title>XLISP progn</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>progn</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c, xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(progn [expr1 expr2 ... ])</dt>
+<dd><i>exprN</i> - expressions comprising the body of the loop<br>
+returns - the value of the last expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'progn' special form is basically a 'block' construct that contains a
+block of code [expressions] to evaluate. The value of the last expression
+'exprN' will be returned as the result of 'progn'. If there are no 'exprs',
+<a href="nil.htm">NIL</a> is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(progn (print "hi") (print "ho")) <font color="#008844">; prints "hi" "ho" returns "ho"</font>
+(progn) <font color="#008844">; returns NIL</font>
+(progn "hey" (print "ho")) <font color="#008844">; prints "ho" returns "ho"</font>
+(progn 'a) <font color="#008844">; returns A</font>
+(progn 'a 'b 'c) <font color="#008844">; returns C</font>
+</pre>
+
+<p><b>Note:</b> <nobr><a href="prog1.htm">prog1</a> ,</nobr>
+<nobr><a href="prog2.htm">prog2</a> ,</nobr>
+'progn' and
+<a href="progv.htm">progv</a> do not allow the use of
+<a href="return.htm">return</a> or
+<a href="go.htm">go</a> or tags for
+<a href="go.htm">go</a>.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-021.htm#progn">progn</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/progv.htm b/docsrc/xlisp/xlisp-doc/reference/progv.htm new file mode 100644 index 0000000..47ccd84 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/progv.htm @@ -0,0 +1,133 @@ +<html><head><title>XLISP progv</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>progv</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>progv</b> <i>symbols values</i> [<i>expr1 expr2</i> ... ])</dt>
+<dd><i>symbols</i> - a list of symbols to be bound<br>
+<i>values</i> - a list of values to be bound to symbols<br>
+<i>exprN</i> - expressions for the body of the loop<br>
+returns - the value of the last expression</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'progv' special form is basically a 'block' construct that contains a
+block of code [expressions] to evaluate. 'progv' is different from
+<nobr><a href="prog1.htm">prog1</a></nobr>, <a href="prog2.htm">prog2</a>
+and <a href="progn.htm">progn</a> in that it contains a pair of lists,
+'symbols' and 'values'. Before evaluating the expressions, 'progv'
+will dynamically bind the 'values' to the corresponding 'symbols'.
+<nobr>If there</nobr> are too many 'symbols' for the 'values', the 'symbols'
+with no corresponding 'values' will be bound to <a href="nil.htm">NIL</a>.
+<nobr>The variables</nobr> will be unbound after the execution of 'progv'.
+<nobr>The value</nobr> of the last 'expr' will be returned as the result of
+'progv'. <nobr>If there</nobr> are no 'exprs',
+<a href="nil.htm">NIL</a> is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+> (progv '(var) '(2)
+ (print var)
+ (print "two"))
+2 <font color="#008844">; output of PRINT</font>
+"two" <font color="#008844">; output of PRINT</font>
+"two" <font color="#008844">; return value</font>
+
+> (setq a "beginning") <font color="#008844">; initialize A</font>
+"beginning"
+
+> (progv '(a) '(during) <font color="#008844">; bind A to a new value</font>
+ (print a))
+DURING <font color="#008844">; output of PRINT</font>
+DURING <font color="#008844">; return value restore A the original value</font>
+
+> (print a)
+"beginning" <font color="#008844">; prints the original value</font>
+"beginning"
+
+> (progv '(no-way) '(no-how))
+NIL
+
+> (progv)
+<font color="#AA0000">error: too few arguments</font>
+</pre>
+
+<p><b>Note:</b> 'progv' is different from
+<nobr><a href="prog.htm">prog</a></nobr>, which allows symbols and
+initialization forms, in that 'progv' allows its 'symbols' and 'values' to
+be evaluated. This allows you to pass in forms that generate the 'symbols'
+and their 'values'.</p>
+
+<p><b>Note:</b> <nobr><a href="prog1.htm">prog1</a></nobr>,
+<nobr><a href="prog2.htm">prog2</a></nobr>, <a href="progn.htm">progn</a>
+and 'progv' do not allow the use of <a href="return.htm">return</a> or
+<a href="go.htm">go</a> or tags for <a href="go.htm">go</a>.</p>
+
+<p><b>Important:</b> In contrast to all other binding constructs, 'progv'
+binds global variables and not lexical variables, so 'progv' behaves
+like:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">progv</font> (symbols values &rest body) <font color="#008844">; this function does</font>
+ (push symbol-values <font color="#AA5500">*internal-stack*</font>) <font color="#008844">; not really work,</font>
+ (setq symbols values) <font color="#008844">; it only demonstates</font>
+ (prog1 <font color="#008844">; the principle</font>
+ (eval body)
+ (setq symbol-values (pop <font color="#AA5500">*internal-stack*</font>))))
+</pre>
+
+<p>Variables bound by 'progv' can be manipulated by global functions
+including <nobr><a href="symbol-value.htm">symbol-value</a></nobr>.
+<nobr>All changes</nobr> to the 'progv' variables by other functions, called
+in the 'progv' body, will be lost after 'progv' is finished, because the
+original value from the beginning of 'progv' will be restored. This can be
+good or bad, depending on the situation.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/psetq.htm b/docsrc/xlisp/xlisp-doc/reference/psetq.htm new file mode 100644 index 0000000..dea8f74 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/psetq.htm @@ -0,0 +1,78 @@ +<html><head><title>XLISP psetq</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>psetq</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(psetq [symbol expr] ... )</dt>
+<dd><i>symbol</i> - un-evaluated symbol<br>
+<i>expr</i> - value for <i>symbol</i><br>
+returns - the value from the last <i>expr</i></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>'psetq' sets 'expr' as the value of 'symbol'. There can be several pairs
+of assignment. 'psetq' performs these assignments in parallel, the 'symbols'
+are not assigned new values until all the 'exprs' have been evaluated.
+'psetq' returns the value from the last 'expr' as it's result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(psetq a 1) <font color="#008844">; symbol A gets value 1</font>
+(psetq b '(a b c)) <font color="#008844">; symbol B gets value (A B C)</font>
+(psetq mynum (+ 3 4)) <font color="#008844">; symbol MYNUM gets value 7</font>
+
+(setq goo 'ber) <font color="#008844">; returns BER</font>
+(setq num 1) <font color="#008844">; returns 1</font>
+(psetq goo num num goo) <font color="#008844">; returns BER</font>
+(print goo) <font color="#008844">; returns 1</font>
+(print num) <font color="#008844">; returns BER</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-013.htm#psetq">psetq</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/push.htm b/docsrc/xlisp/xlisp-doc/reference/push.htm new file mode 100644 index 0000000..d649432 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/push.htm @@ -0,0 +1,83 @@ +<html><head><title>XLISP push</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>push</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp macro</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>misc.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>push</b> <i>expr list</i>)</dt>
+<dd><i>expr</i> - an expression<br>
+<i>list</i> - a list<br>
+returns - the new value of <i>list</i></dd>
+</dl>
+
+</div></p>
+
+<p>'push' is implemented as a Lisp macro:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">push</font> (val lis)
+ `(setf ,lis (cons ,val ,lis)))
+</pre>
+
+<h2>Description</h2>
+
+<p>The 'push' macro stores the value of the expression to the front of the
+list and returns the list.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq lst nil) => NIL
+(push 1 lst) => (1)
+lst => (1)
+(push 2 lst) => (2 1)
+lst => (2 1)
+(push 3 lst) => (3 2 1)
+lst => (3 2 1)
+</pre>
+
+<p>See <a href="setq.htm">setq</a>. See also the <a href="pop.htm">pop</a> macro.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/putprop.htm b/docsrc/xlisp/xlisp-doc/reference/putprop.htm new file mode 100644 index 0000000..7711bf2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/putprop.htm @@ -0,0 +1,108 @@ +<html><head><title>XLISP putprop</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>putprop</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(putprop <i>symbol value property</i>)</dt>
+<dd><i>symbol</i> - the symbol with a property list<br>
+<i>value</i> - the value to be assigned to the property<br>
+<i>property</i> - the property name being changed or added<br>
+returns - the property value</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'putprop' function sets the value of the 'property' in the 'symbol'.
+If the 'property' does not exist, the 'property' is added to the property
+list. The 'symbol' must be an existing symbol. The 'value' may be a single
+value or a list.</p>
+
+<p>Property lists are lists attached to any user defined variables. The
+lists are in the form of:</p>
+
+<pre class="example">
+(<font color="#008844"><i>name1 val1 name2 val2</i></font> ... )
+</pre>
+
+<p>Any number of properties may be attached to a single variable.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq person 'bobby) <font color="#008844">; create a var with a value</font>
+(putprop person 'boogie 'last-name) <font color="#008844">; add a LAST-NAME property</font>
+(putprop person 'disc-jockey 'job) <font color="#008844">; add a JOB property</font>
+
+(get person 'last-name) <font color="#008844">; retrieve LAST-NAME - boogie</font>
+(get person 'job) <font color="#008844">; retrieve JOB - disc-jockey</font>
+(get person 'height) <font color="#008844">; non-existant - returns NIL</font>
+
+(putprop person '(10 20 30) 'stats) <font color="#008844">; add STATS - a list</font>
+(get person 'stats) <font color="#008844">; retrieve STATS - (10 20 30)</font>
+</pre>
+
+<p><b>Note:</b> You can set a property to the value
+<a href="nil.htm">NIL</a>. However, this
+<a href="nil.htm">NIL</a> value is indistinguishable from the
+<a href="nil.htm">NIL</a> returned when a property does not
+exist.</p>
+
+<p><b>Common Lisp:</b> Common LISP does not have a 'putprop' function. It
+uses <a href="setf.htm">setf</a> to achieve this functionality.
+Porting from Common Lisp to XLISP will work fine since XLISP supports the <a
+href="setf.htm">setf</a> modifications of property lists as well
+as the <a href="get.htm">get</a> function to retrieve property
+values from symbol names. Porting from XLISP to Common Lisp will require
+translating 'putprop' into <a href="setf.htm">setf</a> forms.</p>
+
+<p><b>Caution:</b> In XLISP, the order of 'putprop' arguments is 'symbol',
+'value', 'property'. This is different from many other Lisps which normally
+use 'symbol', 'property', 'value'. Be careful when porting existing Lisp
+code.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-014.htm#putprop">putprop</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/quit.htm b/docsrc/xlisp/xlisp-doc/reference/quit.htm new file mode 100644 index 0000000..1710d92 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/quit.htm @@ -0,0 +1,69 @@ +<html><head><title>XLISP quit</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>quit</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlsys.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(quit)</dt>
+<dd>returns - never returns</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'quit' function causes the current XLISP session to be terminated.
+<nobr>It never</nobr> returns.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(quit) <font color="#008844">; never returns</font>
+</pre>
+
+<p><b>Note:</b> When XLISP is exited, any
+<a href="dribble.htm">dribble</a> transcript file is automatically
+closed. However, other open files are not closed, and so may lose some
+information.</p>
+
+<p>See also <a href="quit.htm">exit</a>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/quote.htm b/docsrc/xlisp/xlisp-doc/reference/quote.htm new file mode 100644 index 0000000..8a84180 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/quote.htm @@ -0,0 +1,84 @@ +<html><head><title>XLISP quote</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>quote</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(quote <i>expr</i>)</dt>
+<dl><i>expr</i> - an expression<br>
+returns - the unevaluated expression</dl>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'quote' function returns the 'expr' unevaluated.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+my-var <font color="#008844">; error: unbound variable</font>
+(quote my-var) <font color="#008844">; returns MY-VAR</font>
+my-var <font color="#008844">; still error: unbound variable</font>
+(set (quote my-var) 111) <font color="#008844">; give MY-VAR a value, make it exist</font>
+my-var <font color="#008844">; returns 111</font>
+(quote my-var) <font color="#008844">; returns MY-VAR</font>
+
+<font color="#008844">;; Same as above but using the ' read macro for quote</font>
+
+new-var <font color="#008844">; error: unbound variable</font>
+'new-var <font color="#008844">; returns NEW-VAR</font>
+new-var <font color="#008844">; still error: unbound variable</font>
+(setq new-var 222) <font color="#008844">; give NEW-VAR a value, make it exist</font>
+new-var <font color="#008844">; returns 222</font>
+'new-var <font color="#008844">; returns NEW-VAR</font>
+</pre>
+
+<p><b>Read macro:</b> XLISP supports the
+<nobr><a href="../manual/xlisp-man-008.htm#quote">read macro</a></nobr>
+of a single quote as a short-hand method of writing the 'quote' function.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-012.htm#quote">quote</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/random.htm b/docsrc/xlisp/xlisp-doc/reference/random.htm new file mode 100644 index 0000000..d697135 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/random.htm @@ -0,0 +1,86 @@ +<html><head><title>XLISP random</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>random</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(random <i>expr</i>)</dt>
+<dd><i>expr</i> - integer number or expression<br>
+returns - a random number between 0 and <nobr><i>expr</i> - 1.</nobr></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'random' function generates and returns a random number between 0 and
+<nobr>'expr' - 1.</nobr> If 'expr' is negative, the number range is forced
+to be positive.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(random 100) <font color="#008844">; returns 7</font>
+(random 100) <font color="#008844">; returns 49</font>
+(random 100) <font color="#008844">; returns 73</font>
+(random -100) <font color="#008844">; returns 58</font>
+(random 100.01) <font color="#008844">; error: bad floating point operation</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp allows an optional 'state' parameter,
+which is not supported in XLISP. Also, Common LISP allows floating point
+numbers, which XLISP does not support.</p>
+
+<p><b>Note:</b> This function is an extension of the XLISP system. It is
+provided in the 'msstuff.c' source code file. If your XLISP system is built
+for an IBM PC and compatibles, this function will work. If your system is
+built on UNIX or some other operating system, it will need the code in the
+corresponding 'stuff.c' file.</p>
+
+<p><b>Nyquist:</b> As far as I know the Nyquist 'random' function works on
+all systems. See also the Nyquist
+<a href="xlisp-man-033.htm#rrandom">rrandom</a> function.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-023.htm#random">random</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/read-byte.htm b/docsrc/xlisp/xlisp-doc/reference/read-byte.htm new file mode 100644 index 0000000..4047ae6 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/read-byte.htm @@ -0,0 +1,100 @@ +<html><head><title>XLISP read-byte</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>read-byte</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(read-byte [<i>source</i>])</dt>
+<dd><i>source</i> - an optional source, must be a file pointer or stream,
+default is <a href="global-standard-input.htm">*standard-input*</a><br>
+returns - the byte as an integer</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'read-byte' function reads a single character from the specified
+'source'. The character read is returned as an integer value for the result.
+The 'source' may be a file pointer or a stream. If there is no 'source',
+<a href="global-standard-input.htm">*standard-input*</a> is the default. If an
+end-of-file is encountered in the 'source', then
+<a href="nil.htm">NIL</a> will be returned as the result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq fp (open "f" :direction :output)) <font color="#008844">; set up file</font>
+(print 12.34 fp)
+(close fp)
+
+(setq fp (open "f" :direction :input)) <font color="#008844">; now read the file</font>
+(read-byte fp) <font color="#008844">; returns 49 - equals "1"</font>
+(read-byte fp) <font color="#008844">; returns 50 - equals "2"</font>
+(read-byte fp) <font color="#008844">; returns 46 - equals "."</font>
+(read-byte fp) <font color="#008844">; returns 51 - equals "3"</font>
+(read-byte fp) <font color="#008844">; returns 52 - equals "4"</font>
+(read-byte fp) <font color="#008844">; returns 10 - equals "\n"</font>
+(read-byte fp) <font color="#008844">; returns NIL - empty</font>
+(close fp)
+</pre>
+
+<p><b>Common Lisp:</b> The XLISP and Common Lisp 'read-byte' functions are
+compatible for simple cases. They both allow for the optional 'source'.
+However, in Common Lisp, there are additional parameters which occur right
+after 'source'. So, when porting from Common Lisp to XLISP, remember there
+are additional arguments in Common Lisp's 'read-byte' function.</p>
+
+<p><b>Common Lisp:</b> Common Lisp specifies that 'read' operations with a
+'source' of <a href="nil.htm">NIL</a> will come from
+<a href="global-standard-input.htm">*standard-input*</a>. XLISP does not read the
+input from <a href="global-standard-input.htm">*standard-input*</a> with a
+'source' of <a href="nil.htm">NIL</a>. Common Lisp also
+specifies that a 'source' of <a href="t.htm"> T </a>
+will read from *terminal-io* which is not defined in XLISP by default. XLISP
+does not allow <a href="t.htm"> T </a> as a valid
+argument for 'source'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-029.htm#read-byte">read-byte</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/read-char.htm b/docsrc/xlisp/xlisp-doc/reference/read-char.htm new file mode 100644 index 0000000..476763b --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/read-char.htm @@ -0,0 +1,100 @@ +<html><head><title>XLISP read-char</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>read-char</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(read-char [<i>source</i>])</dt>
+<dd><i>source</i> - an optional source, must be a file pointer or stream,
+default is <a href="global-standard-input.htm">*standard-input*</a><br>
+returns - the character</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'read-char' function reads a single character from the specified
+'source'. The character read is returned as a single character value for
+the result. The 'source' may be a file pointer or a stream. If there is no
+'source', <a href="global-standard-input.htm">*standard-input*</a> is the default.
+If an end-of-file is encountered in the 'source', then
+<a href="nil.htm">NIL</a> will be returned as the result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq fp (open "f" :direction :output)) <font color="#008844">; set up file</font>
+(print 12.34 fp)
+(close fp)
+
+(setq fp (open "f" :direction :input)) <font color="#008844">; now read the file</font>
+(read-char fp) <font color="#008844">; returns #\1</font>
+(read-char fp) <font color="#008844">; returns #\2</font>
+(read-char fp) <font color="#008844">; returns #\.</font>
+(read-char fp) <font color="#008844">; returns #\3</font>
+(read-char fp) <font color="#008844">; returns #\4</font>
+(read-char fp) <font color="#008844">; returns #\Newline</font>
+(read-char fp) <font color="#008844">; returns NIL - empty</font>
+(close fp)
+</pre>
+
+<p><b>Common Lisp:</b> The XLISP and Common Lisp 'read-char' functions are
+compatible for simple cases. They both allow for the optional 'source'.
+However, in Common Lisp, there are addition parameters which occur right
+after 'source'. So, when porting from Common Lisp to XLISP, remember there
+are additional arguments in Common Lisp's 'read-char' function.</p>
+
+<p><b>Common Lisp:</b> Common Lisp specifies that 'read' operations with a
+'source' of <a href="nil.htm">NIL</a> will come from
+<a href="global-standard-input.htm">*standard-input*</a>. XLISP does not read the
+input from <a href="global-standard-input.htm">*standard-input*</a> with a
+'source' of <a href="nil.htm">NIL</a>. Common Lisp also
+specifies that a 'source' of <a href="t.htm"> T </a>
+will read from *terminal-io* which is not defined in XLISP by default. XLISP
+does not allow <a href="t.htm"> T </a> as a valid
+argument for 'source'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-029.htm#read-char">read-char</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/read-float.htm b/docsrc/xlisp/xlisp-doc/reference/read-float.htm new file mode 100644 index 0000000..44b52e7 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/read-float.htm @@ -0,0 +1,79 @@ +<html><head><title>XLISP read-float</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>read-float</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(read-float [<i>stream</i> [<i>length</i>]])</dt>
+<dd><i>stream</i> - the input stream (default is standard input)<br>
+<i>length</i> - the length of the float in bytes [default is 4,
+legal values are -4, -8, 4, and 8]<br>
+returns - the float</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The '<nobr>read-float</nobr>' function reads a binary floating point
+number from an input stream, created by the
+<nobr><a href="open-binary.htm">open-binary</a></nobr> function.</p>
+
+<p><b>Note:</b> Integers and floats are assumed to be
+<nobr>big-endian</nobr> [<nobr>high-order</nobr> byte first] and signed,
+regardless of the platform. <nobr>To read</nobr> <nobr>little-endian</nobr>
+format, use a negative number for the length, e.g. '-4' indicates a
+<nobr>4-bytes</nobr>, <nobr>low-order</nobr> byte first. The file should be
+opened in binary mode.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p>See also <nobr><a href="read-int.htm">read-int</a></nobr>,
+<nobr><a href="write-int.htm">write-int</a></nobr>,
+<nobr><a href="write-float.htm">write-float</a></nobr>,
+<nobr><a href="bigendianp.htm">bigendianp</a></nobr>,
+<nobr><a href="open-binary.htm">open-binary</a></nobr>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/read-int.htm b/docsrc/xlisp/xlisp-doc/reference/read-int.htm new file mode 100644 index 0000000..15aa9d5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/read-int.htm @@ -0,0 +1,78 @@ +<html><head><title>XLISP read-int</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>read-int</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(<b>read-int</b> [<i>stream</i> [<i>length</i>]])</dt>
+<dd><i>stream</i> - the input stream [default is standard input]<br>
+<i>length</i> - the length of the integer in bytes [default is 4]<br>
+returns - the integer</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The '<nobr>read-int</nobr>' function reads an integer from a binary input
+stream, created by the
+<nobr><a href="open-binary.htm">open-binary</a></nobr> function.</p>
+
+<p><b>Note:</b> Integers and floats are assumed to be
+<nobr>big-endian</nobr> [<nobr>high-order</nobr> byte first] and signed,
+regardless of the platform. <nobr>To read</nobr> <nobr>little-endian</nobr>
+format, use a negative number for the length, e.g. '-4' indicates a
+<nobr>4-bytes</nobr>, <nobr>low-order</nobr> byte first. The file should be
+opened in binary mode.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p>See also <nobr><a href="write-int.htm">write-int</a></nobr>,
+<nobr><a href="read-float.htm">read-float</a></nobr>,
+<nobr><a href="write-float.htm">write-float</a></nobr>,
+<nobr><a href="bigendianp.htm">bigendianp</a></nobr>,
+<nobr><a href="open-binary.htm">open-binary</a></nobr>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/read-line.htm b/docsrc/xlisp/xlisp-doc/reference/read-line.htm new file mode 100644 index 0000000..e6860d4 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/read-line.htm @@ -0,0 +1,97 @@ +<html><head><title>XLISP read-line</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>read-line</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(read-line [<i>source</i>])</dt>
+<dd><i>source</i> - an optional source, must be a file pointer or stream,
+default is <a href="global-standard-input.htm">*standard-input*</a><br>
+returns - the line as a string</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'read-line' function reads a single line from the specified 'source'.
+The line read is returned as a string value for the result. The 'source' may
+be a file pointer or a stream. If there is no 'source',
+<a href="global-standard-input.htm">*standard-input*</a> is the default. If an
+end-of-file is encountered in the 'source', then
+<a href="nil.htm">NIL</a> will be returned as the result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq fp (open "f" :direction :output)) <font color="#008844">; set up file</font>
+(print "fe fi" fp)
+(print 12.34 fp)
+(close fp)
+
+(setq fp (open "f" :direction :input)) <font color="#008844">; now read the file</font>
+(read-line fp) <font color="#008844">; returns ""fe fi""</font>
+(read-line fp) <font color="#008844">; returns "12.34"</font>
+(read-line fp) <font color="#008844">; returns NIL</font>
+(close fp)
+</pre>
+
+<p><b>Common Lisp:</b> The XLISP and Common Lisp 'read-line' functions are
+compatible for simple cases. They both allow for the optional 'source'.
+However, in Common Lisp, there are additional parameters which occur right
+after 'source'. So, when porting from Common Lisp to XLISP, remember there
+are additional arguments in Common Lisp's 'read-line' function.</p>
+
+<p><b>Common Lisp:</b> Common Lisp specifies that 'read' operations with a
+'source' of <a href="nil.htm">NIL</a> will come from
+<a href="global-standard-input.htm">*standard-input*</a>. XLISP does not read the
+input from <a href="global-standard-input.htm">*standard-input*</a> with a
+'source' of <a href="nil.htm">NIL</a>. Common Lisp also
+specifies that a 'source' of <a href="t.htm"> T </a>
+will read from *terminal-io* which is not defined in XLISP by default. XLISP
+does not allow <a href="t.htm"> T </a> as a valid
+argument for 'source'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-029.htm#read-line">read-line</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/read.htm b/docsrc/xlisp/xlisp-doc/reference/read.htm new file mode 100644 index 0000000..7e7e339 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/read.htm @@ -0,0 +1,125 @@ +<html><head><title>XLISP read</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>read</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c, xlread.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(<i>read</i> [<i>source</i> [<i>eof-result</i> [<i>recursive-flag</i>]]])</dt>
+<dd><i>source</i> - an optional source, must be a file pointer or stream, the
+default is <a href="global-standard-input.htm">*standard-input*</a><br>
+<i>eof-result</i> - an optional expression, default is
+<a href="nil.htm">NIL</a><br>
+<i>recursive-flag</i> - an optional expression,
+<a href="nil.htm">NIL</a> or
+non-<a href="nil.htm">NIL</a><br>
+returns - the expression read</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'read' function reads an expression from the specified 'source'. The
+expression read is a normal XLISP expression, not necessarily a line. This
+means that white space is removed, where 'white space' is blanks, empty
+lines and comment lines. Read-macro expansions will occur. The expression
+needs to be an atom [numeric, string or symbol] or a valid list. It can span
+several lines. The expression read is returned as the result. The 'source'
+may be a file pointer or a stream. If there is no 'source',
+<a href="global-standard-input.htm">*standard-input*</a> is the default. If an
+end-of-file is encountered in the 'source', then the 'eof-result' value will
+be returned as the result.</p>
+
+<p>If you wish to read just lines or characters, refer to the
+<a href="read-line.htm">read-line</a> or
+<a href="read-char.htm">read-char</a> functions.</p>
+
+<p>The 'recursive-flag' is intended for use with embedded calls to 'read'.
+This is useful in read-macro and read-table uses. If 'recursive-flag' is
+<nobr>non-<a href="nil.htm">NIL</a> ,</nobr> 'read' does not
+expect itself to be at a 'top-level', but recursively executing within
+another 'read' that is in progress.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq fp (open "f" :direction :output)) <font color="#008844">; set up file</font>
+(print "hello" fp) <font color="#008844">; and fill it with stuff</font>
+(print 12.34 fp)
+(princ "'(a b" fp) (terpri fp)
+(princ "; comment" fp) (terpri fp)
+(princ " c d)" fp )
+(close fp)
+
+(setq fp (open "f" :direction :input)) <font color="#008844">; now read the file</font>
+(read fp "done") <font color="#008844">; returns "hello"</font>
+(read fp "done") <font color="#008844">; returns 12.34</font>
+(read fp "done") <font color="#008844">; returns (QUOTE (A B C D))</font>
+ <font color="#008844">; note the macro expansion of QUOTE</font>
+ <font color="#008844">; note that "; comment" is gone</font>
+(read fp "done") <font color="#008844">; returns "done"</font>
+(close fp)
+</pre>
+
+<p><b>Common Lisp:</b> The XLISP and Common Lisp 'read' functions are
+similar. They both allow for 'source', 'eof-result' and 'recursive-flag'.
+However, in Common LISP, there is an additional end-of-file error parameter.
+This parameter occurs right after 'source' and specifies whether or not to
+flag an error on end-of-file. So, when porting, remember there is one
+additional argument in Common Lisp's 'read' function. You need to be
+concerned about this if you use more than just a 'source' argument, going
+either from XLISP to Common LISP or vice versa.</p>
+
+<p><b>Common Lisp:</b> Common Lisp specifies that 'read' operations with a
+'source' of <a href="nil.htm">NIL</a> will come from
+<a href="global-standard-input.htm">*standard-input*</a>. XLISP does not read the
+input from <a href="global-standard-input.htm">*standard-input*</a> with a
+'source' of <a href="nil.htm">NIL</a>. Common Lisp also
+specifies that a 'source' of <a href="t.htm"> T </a>
+will read from *terminal-io* which is not defined in XLISP by default. XLISP
+does not allow <a href="t.htm"> T </a> as a valid
+argument for 'source'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-027.htm#read">read</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/real-random.htm b/docsrc/xlisp/xlisp-doc/reference/real-random.htm new file mode 100644 index 0000000..d3438a8 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/real-random.htm @@ -0,0 +1,82 @@ +<html><head><title>XLISP real-random</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>real-random</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp function (closure)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>misc.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>real-random</b> <i>from to</i>)</nobr></dt>
+<dd><i>from</i>, <i>to</i> - the limits as integer or floating point numbers<br>
+returns - a random floating point number between <i>from</i> and <i>to</i></dd>
+</dl>
+
+</div></p>
+
+<p>In Nyquist, '<nobr>real-random</nobr>' is implemented as a Lisp
+function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">real-random</font> (from to)
+ (+ (* (rrandom) (- to from)) from))
+</pre>
+
+<h2>Description</h2>
+
+<p>The '<nobr>real-random</nobr>' function returns a random floating point
+number between 'from' and 'to'. <nobr>See also</nobr> <a
+href="rrandom.htm">rrandom</a>, which is <nobr>equivalent to:</nobr>
+
+<pre class="example">
+(real-random 0 1))
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p>See also <a href="rrandom.htm">rrandom</a>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/reference-copyright.htm b/docsrc/xlisp/xlisp-doc/reference/reference-copyright.htm new file mode 100644 index 0000000..854f384 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/reference-copyright.htm @@ -0,0 +1,50 @@ +<html><head><title>Copyright</title></head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Copyright</h1>
+
+<hr>
+
+<p>This XLISP language reference is a re-work of a 'XLISPREF.DOC' document
+with the following copyright:</p>
+
+<p>XLISP 2.0 Language Reference by Tim I Mikkelsen - December 11, 1989</p>
+
+<blockquote>
+<p>Copyright (c) 1989 by Tim I. Mikkelsen. All Rights Reserved. No part of this
+document may be copied, reproduced or translated for commercial use without
+prior written consent of the author. Permission is granted for non-commercial
+use as long as this notice is left intact.</p>
+
+<p>This document is intended to serve as a reference for the XLISP 2.0 dialect
+of LISP. It includes a description of each symbol, function, special form and
+keyword available in XLISP. This reference is not a complete and extensive
+introduction to LISP programming.</p>
+
+<p>If you find problems with the reference or find that I have left something
+out, drop me a line. If you find this useful, I would be interested in hearing
+that as well. If you are into 'pretty' looking documents (as opposed to plain
+ASCII text), I have a TeX version of the reference.</p>
+</blockquote>
+
+<p>Tim Mikkelsen, 4316 Picadilly Drive, Fort Collins, Colorado 80526</p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
+
diff --git a/docsrc/xlisp/xlisp-doc/reference/reference-format.htm b/docsrc/xlisp/xlisp-doc/reference/reference-format.htm new file mode 100644 index 0000000..140d2c0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/reference-format.htm @@ -0,0 +1,83 @@ +<html><head><title>Entry Format</title> + +<link rel="stylesheet" type="text/css" href="reference.css"> + +</head> + +<body> + +<a href="../start.htm">Nyquist / XLISP 2.0</a> - +<a href="../manual/contents.htm">Contents</a> | +<a href="../tutorials/tutorials.htm">Tutorials</a> | +<a href="../examples/examples.htm">Examples</a> | +<a href="reference-index.htm">Reference</a> + +<hr> + +<h1>Entry Format</h1> + +<hr> + +<p>Each entry is a symbol of some variety that the XLISP system will +recognize. The parts of each reference entry include:</p> + +<ol> + +<li><p>The <b>Headline</b> of the page gives the name or symbol of the +entry.</p></li> + +<li><p>The <b>Reference</b> section below the headline gives infomations in +the following order:</p></li> + +<ul> + +<li><p><b>Type</b> may be one of the following:</p></li> + +<ul> +<li><nobr>function (subr)</nobr></li> +<li><nobr>predicate function (subr)</nobr></li> +<li><nobr>special form (fsubr)</nobr></li> +<li><nobr>reader expansion</nobr></li> +<li><nobr>system variable</nobr></li> +<li><nobr>system constant</nobr></li> +<li><nobr>keyword</nobr></li> +<li><nobr>object</nobr></li> +<li><nobr>message selector</nobr></li> +</ul> + +<li><p><b>Source</b> specifies the source file where the routine or code +associated with the entry resides. [Please not that I have copied the +source file locations out of the Tim I Mikkelsen manual without checking, +so some of them may be wrong.]</p></li> + +</ul> + +<li><p><b>Syntax</b> defines the syntax or usage of the entry. It is also +used to specify the arguments. Items written in <i>italics</i> are +arguments. Items enclosed between square brackets like '[' and ']' are +optional entries. Items that have '...' [ellipses] indicate that there can +be one or many of the item. Items enclosed between '{' and '}' which are +separated by '|' indicate that one of the items should be included.</p></li> + +<li><p><b>Description</b> defines the entry, necessary conditions, results, +defaults, etc.</p></li> + +<li><p><b>Examples</b> shows example uses of the entry.</p></li> + +<li><p>The <b>Comments</b> section after the examples includes additional +information such as compatibility notes, bugs, usage notes, potential +problems, keystroke equivalences, etc.</p></li> + +</ol> + +<p><nobr> <a href="#top">Back to Top</a></nobr></p> + +<hr> + +<a href="../start.htm">Nyquist / XLISP 2.0</a> - +<a href="../manual/contents.htm">Contents</a> | +<a href="../tutorials/tutorials.htm">Tutorials</a> | +<a href="../examples/examples.htm">Examples</a> | +<a href="reference-index.htm">Reference</a> + +</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/reference-index.htm b/docsrc/xlisp/xlisp-doc/reference/reference-index.htm new file mode 100644 index 0000000..a50ea90 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/reference-index.htm @@ -0,0 +1,2468 @@ +<html><head><title>Language Reference</title></head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+Reference
+
+<hr>
+
+<h1>Nyquist / XLISP 2.0 Language Reference</h1>
+
+<hr>
+
+<p><nobr>
+<a href="#num"> <i>#</i> </a> |
+<a href="#a"> <i>a</i> </a> |
+<a href="#b"> <i>b</i> </a> |
+<a href="#c"> <i>c</i> </a> |
+<a href="#d"> <i>d</i> </a> |
+<a href="#e"> <i>e</i> </a> |
+<a href="#f"> <i>f</i> </a> |
+<a href="#g"> <i>g</i> </a> |
+<a href="#h"> <i>h</i> </a> |
+<a href="#i"> <i>i</i> </a> |
+<a href="#k"> <i>k</i> </a> |
+<a href="#l"> <i>l</i> </a> |
+<a href="#m"> <i>m</i> </a> |
+<a href="#n"> <i>n</i> </a> |
+<a href="#o"> <i>o</i> </a> |
+<a href="#p"> <i>p</i> </a> |
+<a href="#q"> <i>q</i> </a> |
+<a href="#r"> <i>r</i> </a> |
+<a href="#s"> <i>s</i> </a> |
+<a href="#t"> <i>t</i> </a> |
+<a href="#u"> <i>u</i> </a> |
+<a href="#v"> <i>v</i> </a> |
+<a href="#w"> <i>w</i> </a> |
+<a href="#z"> <i>z</i> </a>
+</nobr></p>
+
+<ul>
+<li><nobr><a href="reference-copyright.htm">Copyright</a></nobr></li>
+<li><nobr><a href="reference-format.htm">Entry Format</a></nobr></li>
+</ul>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td><nobr><a href="../manual/xlisp.htm#command-loop"> * </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">variable</font>
+ - most recent result</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="../manual/xlisp.htm#command-loop"> ** </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">variable</font>
+ - second recent result</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="../manual/xlisp.htm#command-loop"> *** </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">variable</font>
+ - third recent result</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="../manual/xlisp.htm#command-loop"> + </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">variable</font>
+ - most recent input expression</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="../manual/xlisp.htm#command-loop"> ++ </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">variable</font>
+ - second recent input expression</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="../manual/xlisp.htm#command-loop"> +++ </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">variable</font>
+ - third recent input expression</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="../manual/xlisp.htm#command-loop"> − </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">variable</font>
+ - the expression currently being evaluated</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="num"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="addition.htm"> + </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - add one or several numbers</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="subtraction.htm"> − </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - negate one number or subtract several numbers</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="multiplication.htm"> * </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - multiply one or several numbers</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="division.htm"> / </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - divide one or several numbers</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="number-lessp.htm"> < </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if numbers are monotonically increasing</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="number-not-greaterp.htm"> <= </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if numbers are monotonically non-decreasing</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="number-equal.htm"> = </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test numbers for equality</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="number-not-equal.htm"> /= </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test numbers for non-equality</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="number-greaterp.htm"> > </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if numbers are monotonically decreasing</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="number-not-lessp.htm"> >= </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if numbers are monotonically non-increasing</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="increment.htm"> 1+ </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - increment a number by one</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="decrement.htm"> 1− </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - decrement a number by one</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="a"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="abs.htm">abs</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the absolute value of a number</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="acos.htm">acos</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the arccosine of a floating point number</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="address-of.htm">address-of</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - get the address of an xlisp node</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="alloc.htm">alloc</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - change the number of nodes to allocate in each segment</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="alphanumericp.htm">alphanumericp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - is this an alphabetic or a digit character?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="and.htm">and</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - the logical 'and' of an arbitrary number of expressions</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="keyword-answer.htm">:answer</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">message selector</font>
+ - add a message to a class</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="append.htm">append</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - append lists</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="apply.htm">apply</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - apply a function to a list of arguments</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-applyhook.htm">*applyhook*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - returns <a href="nil.htm">NIL</a> [hook not implemented]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="aref.htm">aref</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - array accessor for the nth element of an array</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="arrayp.htm">arrayp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this an array?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="asin.htm">asin</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the arcsine of a floating point number</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="assoc.htm">assoc</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - find an expression in an association list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="atan.htm">atan</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the arctangent of a floating point number</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="atom.htm">atom</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this an atom?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="lambda-keyword-aux.htm">&aux</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">keyword</font>
+ - define auxiliary variables</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="b"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="backquote.htm">backquote</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - fill in a template</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="baktrace.htm">baktrace</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - print n levels of trace back information</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="bigendianp.htm">bigendianp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - is this a bigendian machine?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="block.htm">block</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - define a named block</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="both-case-p.htm">both-case-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this an uppercase or lowercase alphabetic character?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="boundp.htm">boundp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is a variable value bound to this symbol in the <a href="global-obarray.htm">*obarray*</a>?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="break.htm">break</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - enter a <a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-breakenable.htm">*breakenable*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - define if the <a href="../manual/xlisp.htm#break-loop">Break Loop</a> shall be entered on errors</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="c"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="car.htm">car</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessor for the <a href="first.htm">first</a> element of a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="caar.htm">caar cadr</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessors for a sequence of <a href="car.htm">car</a> and
+ <a href="cdr.htm">cdr</a> operations</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="caaar.htm">caaar...caddr</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessors for a sequence of <a href="car.htm">car</a> and
+ <a href="cdr.htm">cdr</a> operations</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="caaaar.htm">caaaar...cadddr</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessors for a sequence of <a href="car.htm">car</a> and
+ <a href="cdr.htm">cdr</a> operations</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="case.htm">case</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - select by case</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="catch.htm">catch</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - evaluate expressions and catch <a href="throw.htm">throw</a>s</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="cdr.htm">cdr</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessor for the tail of a list with the
+ <a href="first.htm">first</a> element removed</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="cddr.htm">cdar cddr</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessors for a sequence of <a href="car.htm">car</a> and
+ <a href="cdr.htm">cdr</a> operations</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="cdddr.htm">cdaar...cdddr</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessors for a sequence of <a href="car.htm">car</a> and
+ <a href="cdr.htm">cdr</a> operations</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="cddddr.htm">cdaaar...cddddr</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessors for a sequence of <a href="car.htm">car</a> and
+ <a href="cdr.htm">cdr</a> operations</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="cerror.htm">cerror</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - signal a correctable error</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char.htm">char</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - extract a character from a string</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-not-equal-s.htm">char/=</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if characters are not equal, case is significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-lessp-s.htm">char<</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if characters are monotonically increasing, case is significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-not-greaterp-s.htm">char<=</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if characters are monotonically non-decreasing, case is significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-equal-s.htm">char=</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if characters are equivalent, case is significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-greaterp-s.htm">char></a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if characters are monotonically decreasing, case is significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-not-lessp-s.htm">char>=</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if characters are monotonically non-increasing, case is significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="characterp.htm">characterp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this a character?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-code.htm">char-code</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - get the ASCII code of a character</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-downcase.htm">char-downcase</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - convert a character to lower case</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-equal-i.htm">char-equal</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if characters are equivalent, case is not significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-greaterp-i.htm">char-greaterp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - test if characters are monotonically decreasing, case is not significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-int.htm">char-int</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - convert a character to an integer</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-lessp-i.htm">char-lessp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - test if characters are monotonically increasing, case is not significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-not-equal-i.htm">char-not-equal</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if characters are different values, case is not significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-not-greaterp-i.htm">char-not-greaterp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - test if characters are monotonically non-decreasing, case is not significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-not-lessp-i.htm">char-not-lessp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - test if characters are monotonically non-increasing, case is not significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="char-upcase.htm">char-upcase</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - convert a character to upper case</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="class.htm">class</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">object</font>
+ - the built-in object class</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="keyword-class.htm">:class</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">message selector</font>
+ - return the class of an object</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="clean-up.htm">clean-up</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - clean-up after an error</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="close.htm">close</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - close a file stream</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="code-char.htm">code-char</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - get the character with a specified ASCII code</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="backquote.htm">comma</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">reader expansion</font>
+ - comma evaluates expressions in a <a href="backquote.htm">backquote</a> form</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="backquote.htm">comma-at</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">reader expansion</font>
+ - splices a list into a expression in a <a href="backquote.htm">backquote</a> form</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="cond.htm">cond</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - evaluate conditionally</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="cons.htm">cons</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - construct a new list node</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="consp.htm">consp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this a non-empty list?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="keyword-constituent.htm">:constituent</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">keyword</font>
+ - readtable entry to specify a character to be used as is</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="continue.htm">continue</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - continue from a correctable error</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="cos.htm">cos</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the cosine of a floating point number</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="d"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-debug-io.htm">*debug-io*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - file pointer for debug input and output</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="decf.htm">decf</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">macro</font>
+ - decrement a variable</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="defmacro.htm">defmacro</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - define a Lisp macro</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="defun.htm">defun</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - define a Lisp function</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="delete.htm">delete</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - delete elements from a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="delete-if.htm">delete-if</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - delete elements from a list that pass a test</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="delete-if-not.htm">delete-if-not</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - delete elements from a list that fail a test</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="digit-char.htm">digit-char</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - convert a decimal digit to a character</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="digit-char-p.htm">digit-char-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - convert a character to a decimal digit, if possible</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="do.htm">do</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - loop with local 'let' bindings</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="do-star.htm">do*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - loop with local 'let*' bindings</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="dolist.htm">dolist</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - loop through a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="dotimes.htm">dotimes</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - loop a given number of times</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="dribble.htm">dribble</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - create a file with a transcript of a Nyquist/ XLISP session</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="e"></a></td>
+</tr>
+</tr>
+<tr>
+ <td><nobr><a href="echoenabled.htm">echoenabled</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - turn the console input echo on or off</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="endp.htm">endp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this the end of a list?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="eq.htm">eq</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - equality test comparing memory pointers, may fail on numbers</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="eql.htm">eql</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - same as 'eq', but works with all symbols and numbers</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="equal.htm">equal</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - equality test by comparing printed values</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="error.htm">error</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - signal a non-correctable error</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-error-output.htm">*error-output*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - file pointer for error input and output</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="errset.htm">errset</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - trapping errors</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="eval.htm">eval</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - evaluate a Lisp expression</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="evalhook.htm">evalhook</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - evaluate with hooks</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-evalhook.htm">*evalhook*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - user substitute for the evaluator function</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="evenp.htm">evenp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this integer even?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="exit.htm">exit</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - exit XLISP</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="exp.htm">exp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute 'e' to the 'x' power</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="expand.htm">expand</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - expand memory by adding segments</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="expt.htm">expt</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute 'x' to the 'y' power</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="f"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="fboundp.htm">fboundp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is a function value bound to this symbol in the <a href="global-obarray.htm">*obarray*</a>??</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="filep.htm">filep</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - is this a file?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="find-in-xlisp-path.htm">find-in-xlisp-path</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - searches the XLISP path for a filename</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-file-separator.htm">*file-separator*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">variable</font>
+ - the operating system's file separator character</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="first.htm">first</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessor for the first element of a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="flatc.htm">flatc</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - length of printed representation using <a href="princ.htm">princ</a></nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="flatsize.htm">flatsize</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - length of printed representation using <a href="prin1.htm">prin1</a></nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="flet.htm">flet</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - define local Lisp functions</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="float.htm">float</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - convert an integer to a floating point number</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-float-format.htm">*float-format*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - format for printing floating point numbers</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="floatp.htm">floatp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this number a floating point number?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="format.htm">format</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - do formatted output</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="fourth.htm">fourth</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessor for the fourth element of a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="funcall.htm">funcall</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - call a function with arguments</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="function.htm">function</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - get the functional value of a symbol or lambda expression</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="g"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="gc.htm">gc</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - call the garbage collector</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="gcd.htm">gcd</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the greatest common divisor</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-gc-flag.htm">*gc-flag*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - controls the printing of 'gc' messages</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-gc-hook.htm">*gc-hook*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - function to call after garbage collection</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="gensym.htm">gensym</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - generate an unique Lisp symbol</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="get.htm">get</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessor for property lists</nobr></td>
+</tr>
+ <tr>
+ <td><nobr><a href="get-env.htm">get-env</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - get the value of an environment variable</nobr></td>
+ </tr>
+<tr>
+ <td colspan="4" width="100%">
+ <table cellpadding="0" cellspacing="0"><tbody>
+ <tr>
+ <td><nobr><a href="get-lambda-keyword-key.htm">get-key</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - get a single key stroke from the keyboard</nobr></td>
+ </tr>
+ <tr>
+ <td><nobr><a href="get-lambda-expression.htm">get-lambda-expression</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - get the Lisp code of a lambda or macro expression as a list</nobr></td>
+ </tr>
+ <tr>
+ <td><nobr><a href="get-output-stream-list.htm">get-output-stream-list</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - empty a stream and return it's data as a list</nobr></td>
+ </tr>
+ <tr>
+ <td><nobr><a href="get-output-stream-string.htm">get-output-stream-string</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - empty a stream and return it's data as a single string</nobr></td>
+ </tr>
+ <tr>
+ <td><nobr><a href="get-temp-path.htm">get-temp-path</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - get a path where a temporary file can be created</nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+</tr>
+<tr>
+ <td><nobr><a href="get-user.htm">get-user</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - get the current user name</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="go.htm">go</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - go to a tag within a 'tagbody' or 'prog'</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="h"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="hash.htm">hash</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the hash index for a symbol</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="i"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="if.htm"> if </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - evaluate expressions conditionally</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="incf.htm">incf</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">macro</font>
+ - increment a variable</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="info.htm">info</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - show information about memory usage</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="int-char.htm">int-char</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - convert an integer to a character</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-integer-format.htm">*integer-format*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - format for printing integer numbers</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="integerp.htm">integerp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this number an integer?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="intern.htm">intern</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - create a new interned symbol</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="interpolate.htm">interpolate</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the 'y' coordinate value corresponding to 'x'</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="intersection.htm">intersection</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the intersection of two lists</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="keyword-isa.htm">:isa</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">message selector</font>
+ - test if object inherits from class</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="keyword-isnew.htm">:isnew</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">message selector</font>
+ - cause an instance to run its initialization method</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="k"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="keywordp.htm">keywordp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - is this a keyword?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="lambda-keyword-key.htm">&key</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">lambda list keyword</font>
+ - define keyword arguments</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="l"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="labels.htm">labels</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - define local Lisp functions in a mutually recursive manner</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="lambda.htm">lambda</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - define a unnamed function</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="last.htm">last</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessor for the last element of a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="length.htm">length</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - returns the length of a list, vector or string</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="let.htm">let</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - define local bindings, evaluated in no specific order</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="let-star.htm">let*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - define local bindings, evaluated in sequencial order</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="list.htm">list</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - create a list of values</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="listdir.htm">listdir</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - get a list of all filenames in a directory</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="listp.htm">listp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this a list?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="load.htm">load</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - load a source file</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="log.htm">log</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - the natural logarithm of a floating-point number</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="logand.htm">logand</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - the bitwise 'and' of one or several numbers</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="logior.htm">logior</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - the bitwise 'inclusive or' of one or several numbers</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="lognot.htm">lognot</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - the bitwise 'exclusive or' of one or several numbers</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="logxor.htm">logxor</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - the bitwise 'not' of a number</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="loop.htm">loop</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - basic looping form</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="lower-case-p.htm">lower-case-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this a lowercase character?</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="m"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="macroexpand.htm">macroexpand</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - expand macro definitions recursively</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="macroexpand-1.htm">macroexpand-1</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - expand the first level of a macro definition</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="macrolet.htm">macrolet</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - define a local macro</nobr></td>
+</tr>
+<tr>
+ <td colspan="4" width="100%">
+ <table cellpadding="0" cellspacing="0"><tbody>
+ <tr>
+ <td><nobr><a href="make-array.htm">make-array</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - create an array of specified size</nobr></td>
+ </tr>
+ <tr>
+ <td><nobr><a href="make-string-input-stream.htm">make-string-input-stream</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - create an unnamed stream from a string expression</nobr></td>
+ </tr>
+ <tr>
+ <td><nobr><a href="make-string-output-stream.htm">make-string-output-stream</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - create and return an unnamed output stream</nobr></td>
+ </tr>
+ <tr>
+ <td><nobr><a href="make-symbol.htm">make-symbol</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - create a temporary, uninterned symbol</nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+</tr>
+<tr>
+ <td><nobr><a href="mapc.htm">mapc</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - apply a function to successive 'car's, return the first list of arguments</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="mapcar.htm">mapcar</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - apply a function to successive 'car's, return a list of the values</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="mapl.htm">mapl</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - apply a function to successive 'cdr's, return the first list of arguments</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="maplist.htm">maplist</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - apply a function to successive 'cdr's, return a list of the values</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="max.htm">max</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - return the largest of one or several numbers</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="member.htm">member</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if an expression is contained in a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="keyword-mescape.htm">:mescape</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">keyword</font>
+ - readtable entry specifying a character to be used as a multiple escape character</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="min.htm">min</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - return the smallest of one or several numbers</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="minusp.htm">minusp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this number negative?</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="n"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="nconc.htm">nconc</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - destructively concatenate lists</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="keyword-new.htm">:new</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">message selector</font>
+ - create a new instance of a class</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="nil.htm">nil</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system constant</font>
+ - representing the empty list as well as the false value</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="keyword-nmacro.htm">:nmacro</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">keyword</font>
+ - readtable entry to specify a character to be used as the start of a non-terminating read macro</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="not.htm">not</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this expression false?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="nstring-downcase.htm">nstring-downcase</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - destructively convert a string or a part of it to lower case</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="nstring-upcase.htm">nstring-upcase</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - destructively convert a string or a part of it to upper case</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="nth.htm">nth</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessor for the nth element of a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="nthcdr.htm">nthcdr</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessor for the nth tail of a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="null.htm">null</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this an empty list?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="numberp.htm">numberp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this a number?</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="o"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-obarray.htm">*obarray*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - the system symbol table</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="object.htm">object</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">object</font>
+ - the build-in object class</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="objectp.htm">objectp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this an object?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="oddp.htm">oddp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this integer number odd?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="open.htm">open</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - open a file for character or byte i/o</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="open-binary.htm">open-binary</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - open a file for multi-byte i/o</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="lambda-keyword-optional.htm">&optional</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">lambda list keyword</font>
+ - define optional arguments</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="or.htm">or</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - the logical 'or' of an arbitrary number of expressions</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="p"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="peek.htm">peek</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - accessor for an internal computer memory value</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="peek-char.htm">peek-char</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - look at a single character from a specified source</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="pi.htm">pi</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">variable</font>
+ - floating point approximation of the number 'pi'</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="plusp.htm">plusp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this number positive?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="poke.htm">poke</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - write a value to the internal computer memory</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="pop.htm">pop</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">macro</font>
+ - pop a value from a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="power.htm">power</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute 'x' raised to the 'y' power</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="pprint.htm">pprint</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - print a pretty looking version of an expression</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="prin1.htm">prin1</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - print an expression without a newline</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="princ.htm">princ</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - print an expression without quoting and without a newline</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="print.htm">print</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - print an expression on a new line</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-print-case.htm">*print-case*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - specifies how symbols are printed</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="profile.htm">profile</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - turn profiling on or off</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="prog.htm">prog</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - a 'block' with local 'let' bindings</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="prog-star.htm">prog*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - a 'block' with local 'let*' bindings</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="prog1.htm">prog1</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - a 'block' returning the value of the first expression</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="prog2.htm">prog2</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - a 'block' returning the value of the second expression</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="progn.htm">progn</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - a 'block' returning the value of the last expression</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="progv.htm">progv</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - a 'block' with local bindings, created out of two lists</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="psetq.htm">psetq</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - perform 'setq' assignments in parallel</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="push.htm">push</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">macro</font>
+ - push a value to the front of a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="putprop.htm">putprop</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - put a property onto a symbol's property list</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="q"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="quit.htm">quit</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - quit XLISP</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="quote.htm">quote</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - return an expression unevaluated</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="r"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="random.htm">random</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute an integer random number between 0 and n-1 inclusive</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="read.htm">read</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - read a Lisp expression</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="read-byte.htm">read-byte</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - read a byte from a stream</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="read-char.htm">read-char</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - read a character from a stream</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="read-float.htm">read-float</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - read a binary floating point number from a stream</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="read-int.htm">read-int</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - read a binary integer number from a stream</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="read-line.htm">read-line</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - read a line from a stream, returned as a string</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-readtable.htm">*readtable*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - contains data structures relating to the processing of characters</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="real-random.htm">real-random</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute a floating point random number in an arbitrary range</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="rem.htm">rem</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the remainder of one or several numbers</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="remove.htm">remove</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - remove elements from a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="remove-if.htm">remove-if</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - remove elements from a list that pass a test</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="remove-if-not.htm">remove-if-not</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - remove elements from a list that fail a test</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="remprop.htm">remprop</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - remove a property from a symbol's property list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="rest.htm">rest</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessor for the tail of a list, identical to 'cdr'</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="lambda-keyword-rest.htm">&rest</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">lambda list keyword</font>
+ - define 'rest' arguments, to be collected in a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="restore.htm">restore</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - restore a XLISP workspace from a file</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="return.htm">return</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - return from a 'block' construct</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="return-from.htm">return-from</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - return from a named block</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="reverse.htm">reverse</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - reverse a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="room.htm">room</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - show memory allocation statistics</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="round.htm">round</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - round a number to the next integer value</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="rplaca.htm">rplaca</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - replace the first element of a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="rplacd.htm">rplacd</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - replace the tail of a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="rrandom.htm">rrandom</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute a random floating point number between 0 and 1 inclusive</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-rslt.htm">*rslt*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - used to store multiple return values</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="s"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="save.htm">save</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - save a XLISP workspace to a file</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="second.htm">second</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessor for the second element of a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="self.htm">self</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">symbol</font>
+ - evaluates to the current object when used within a message context</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="send.htm">send</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - send a message to an object</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="send-super.htm">send-super</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - send a message to the superclass of an object</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="keyword-sescape.htm">:sescape</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">keyword</font>
+ - readtable entry specifying a character to be used as a single escape character</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="set.htm">set</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - set the value of a symbol</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="set-difference.htm">set-difference</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the set-difference of two lists</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="setdir.htm">setdir</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - set a new working directory</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="setf.htm">setf</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - set the value of a place</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="setq.htm">setq</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - set the value of a quoted symbol</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="setup-console.htm">setup-console</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - set default console attributes</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="keyword-show.htm">:show</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">message selector</font>
+ - show an object's instance variables</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="sin.htm">sin</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the sine of a floating point number</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="sort.htm">sort</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - destructively sort a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="soundp.htm">soundp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - is this a sound?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="sqrt.htm">sqrt</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the square root of a floating point number</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-standard-input.htm">*standard-input*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - file pointer for standard input</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-standard-output.htm">*standard-output*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - file pointer for standard output</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="strcat.htm">strcat</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - concatenate strings</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="streamp.htm">streamp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this a stream?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string.htm">string</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - make a string from a symbol, character or string</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-not-equal-s.htm">string/=</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if string1 is not equal to string2, case is significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-lessp-s.htm">string<</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if string1 is less than string2, case is significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-not-greaterp-s.htm">string<=</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if string1 is less than or equal to string2, case is significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-equal-s.htm">string=</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if the string arguments have the same values, case is significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-greaterp-s.htm">string></a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if string1 is greater than string2, case is significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-not-lessp-s.htm">string>=</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if string1 is greater than or equal to string2, case is significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="stringp.htm">stringp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this a string?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-downcase.htm">string-downcase</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - convert a string to lower case</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-equal-i.htm">string-equal</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if string1 equal to string2, case is not significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-greaterp-i.htm">string-greaterp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - test if string1 is greater than string2, case is not significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-left-trim.htm">string-left-trim</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - trim the left end of a string</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-lessp-i.htm">string-lessp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - test if string1 is less than string2, case is not significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-not-equal-i.htm">string-not-equal</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if string1 is not equal to string2, case is not significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-not-greaterp-i.htm">string-not-greaterp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - test if string1 is less than or equal to string2, case is not significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-not-lessp-i.htm">string-not-lessp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - test if string1 is greater than or equal to string2, case is not significant</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-right-trim.htm">string-right-trim</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - trim the right end of a string</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-search.htm">string-search</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - search for a pattern in a string</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-trim.htm">string-trim</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - trim both ends of a string</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="string-upcase.htm">string-upcase</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - convert a string to upper case</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="sublis.htm">sublis</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - substitute expressions by using an association list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="subseq.htm">subseq</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - extract a substring</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="subsetp.htm">subsetp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - test if a list is a subset of another list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="subst.htm">subst</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - substitute expressions</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="symbol-function.htm">symbol-function</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - get the functional value of a symbol</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="symbol-name.htm">symbol-name</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - get the print name of a symbol</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="symbol-plist.htm">symbol-plist</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - get the property list of a symbol</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="symbol-value.htm">symbol-value</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - get the value of a symbol</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="symbolp.htm">symbolp</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this a symbol?</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="system.htm">system</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - execute a command of the operating system</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="t"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="t.htm"> t </a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system constant</font>
+ - represents 'true'</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="tagbody.htm">tagbody</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - a 'block' form with labels</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="tan.htm">tan</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the tangent of a floating point number</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="terpri.htm">terpri</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - terminate printing, prints a newline character</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="third.htm">third</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - list accessor for the third element of a list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="throw.htm">throw</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - throw to a 'catch', allows non-local exits and traps</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="keyword-tmacro.htm">:tmacro</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">keyword</font>
+ - readtable entry to specify a character to be used as the start of a terminating read macro</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="top-level.htm">top-level</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - clean-up after an error and return to the top level</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="trace.htm">trace</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - add a function to the trace list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-tracelimit.htm">*tracelimit*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - the number of forms printed on entry to the <a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-tracelist.htm">*tracelist*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - a list of the current functions being traced</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-tracenable.htm">*tracenable*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - controls whether or not the <a href="../manual/xlisp.htm#break-loop">Break Loop</a> prints any back trace information on entry</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-trace-output.htm">*trace-output*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system variable</font>
+ - file pointer for trace output</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="truncate.htm">truncate</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - truncates a number to an integer</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="type-of.htm">type-of</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the type of a Lisp expression</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="u"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="global-unbound.htm">*unbound*</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">system constant</font>
+ - used to indicate when a symbol has no value</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="union.htm">union</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - compute the union of two lists</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="unless.htm">unless</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - evaluate only when a condition is false</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="untrace.htm">untrace</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - remove a function from the trace list</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="unwind-protect.htm">unwind-protect</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - allows the trapping of all forms of exit from a protected form</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="upper-case-p.htm">upper-case-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this an uppercase character?</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="v"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="vector.htm">vector</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - create an initialized vector [one-dimensional array]</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+</tbody></table>
+
+<table cellpadding="0" cellspacing="0" style="margin-left:5px"><tbody>
+<tr>
+ <td style="height:10px"><a name="w"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="when.htm">when</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">special form</font>
+ - evaluate only when a condition is true</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="while.htm">while</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">macro</font>
+ - loop while a condition is met</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="keyword-white-space.htm">:white-space</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">keyword</font>
+ - readtable entry to specifying a character that may be skipped over</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="write-byte.htm">write-byte</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - write a byte to a stream</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="write-char.htm">write-char</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - write a character to a stream</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="write-float.htm">write-float</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - write a binary floating point number to a stream</nobr></td>
+</tr>
+<tr>
+ <td><nobr><a href="write-int.htm">write-int</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">function</font>
+ - write a binary integer number to a stream</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td><nobr> [
+ <a href="#top"><font color="#444444">Back to Top</font></a> ]
+ </nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"><a name="z"></a></td>
+</tr>
+<tr>
+ <td><nobr><a href="zerop.htm">zerop</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><font color="#444444">predicate function</font>
+ - is this number zero?</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+</tbody></table>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+Reference
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/reference.css b/docsrc/xlisp/xlisp-doc/reference/reference.css new file mode 100644 index 0000000..964dca2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/reference.css @@ -0,0 +1,34 @@ +.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+
diff --git a/docsrc/xlisp/xlisp-doc/reference/rem.htm b/docsrc/xlisp/xlisp-doc/reference/rem.htm new file mode 100644 index 0000000..e17717c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/rem.htm @@ -0,0 +1,88 @@ +<html><head><title>XLISP rem</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>rem</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(rem <i>expr1</i> ... )</dt>
+<dd><i>exprN</i> - integer number or expression<br>
+returns - the result of the remainder operation</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'rem' function takes the first pair of expressions and determines
+what is the remainder from dividing the first by the second expression. If
+there are no other arguments, this value is returned. If there are
+additional arguments, the remainder of the first pair is applied to the next
+and then the next and so on. In other words:</p>
+
+<pre class="example">
+(REM A B C D)
+</pre>
+
+<p>is equivalent to:</p>
+
+<pre class="example">
+(REM (REM (REM A B) C) D)
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(rem 1) <font color="#008844">; returns 1</font>
+(rem 1 2) <font color="#008844">; returns 1</font>
+(rem 13 8) <font color="#008844">; returns 5</font>
+(rem 13 8 3) <font color="#008844">; returns 2</font>
+(rem 13.5 8) <font color="#008844">; error: bad floating point operation</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp only allows two arguments. XLISP supports
+an arbitrary number of arguments. Also, Common Lisp allows for floating
+point expressions where XLISP does not support this.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-023.htm#rem">rem</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/remove-if-not.htm b/docsrc/xlisp/xlisp-doc/reference/remove-if-not.htm new file mode 100644 index 0000000..cffc53e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/remove-if-not.htm @@ -0,0 +1,80 @@ +<html><head><title>XLISP remove-if-not</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>remove-if-not</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(remove-if-not test list-expr)</dt>
+<dd><i>test</i> - the test function to be performed<br>
+<i>list-expr</i> - the list to remove from<br>
+returns - a copy of <i>list-expr</i> with non-matching elements removed</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'remove-if-not' function searches through 'list-expr' and removes any
+elements that fail the 'test'. Note that this operation is non-destructive,
+it does not modify or affect 'list-expr' directly, it creates a modified
+copy.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq mylist '(1 2 3 4 5 6 7 8)) <font color="#008844">; set up a list</font>
+(remove-if-not 'oddp mylist) <font color="#008844">; returns (1 3 5 7)</font>
+(remove-if-not 'evenp mylist) <font color="#008844">; returns (2 4 6 8)</font>
+(print mylist) <font color="#008844">; prints (1 2 3 4 5 6 7 8)</font>
+ <font color="#008844">; note that MYLIST is not affected</font>
+
+(setq mylist '(a nil b nil c)) <font color="#008844">; set up a list</font>
+(remove-if-not 'null mylist) <font color="#008844">; returns (NIL NIL)</font>
+</pre>
+
+<p><b>Common Lisp:</b> XLISP does not support the ':from-end', ':start',
+':end', ':count' and ':key' keywords which Common Lisp does.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#remove-if-not">remove-if-not</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/remove-if.htm b/docsrc/xlisp/xlisp-doc/reference/remove-if.htm new file mode 100644 index 0000000..0bcbfdb --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/remove-if.htm @@ -0,0 +1,80 @@ +<html><head><title>XLISP remove-if</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>remove-if</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(remove-if <i>test list-expr</i>)</dt>
+<dd><i>test</i> - the test function to be performed<br>
+<i>list-expr</i> - the list to remove from<br>
+returns - copy of list with matching elements removed</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'remove-if' function searches through 'list-expr' and removes any
+elements that pass the 'test'. Note that this operation is non-destructive,
+it does not modify or affect 'list-expr' directly, it creates a modified
+copy.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq mylist '(1 2 3 4 5 6 7 8)) <font color="#008844">; set up a list</font>
+(remove-if 'oddp mylist) <font color="#008844">; returns (2 4 6 8)</font>
+(remove-if 'evenp mylist) <font color="#008844">; returns (1 3 5 7)</font>
+(print mylist) <font color="#008844">; prints (1 2 3 4 5 6 7 8)</font>
+ <font color="#008844">; note that MYLIST is not affected</font>
+
+(setq mylist '(a nil b nil c)) <font color="#008844">; set up a list</font>
+(remove-if 'null mylist) <font color="#008844">; returns (A B C)</font>
+</pre>
+
+<p><b>Common Lisp:</b> XLISP does not support the ':from-end', ':start',
+':end', ':count' and ':key' keywords which Common Lisp does.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#remove-if">remove-if</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/remove.htm b/docsrc/xlisp/xlisp-doc/reference/remove.htm new file mode 100644 index 0000000..e9108e5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/remove.htm @@ -0,0 +1,100 @@ +<html><head><title>XLISP remove</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>remove</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(remove <i>expr list-expr</i> [{:test | :test-not} <i>test</i>])</dt>
+<dd><i>expr</i> - the expression to remove, an atom or list<br>
+<i>list-expr</i> - the list to remove from<br>
+<i>test</i> - optional test function, default is
+<a href="eql.htm">eql</a><br>
+returns - a copy of <i>list-expr</i> with matching expressions removed</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'remove' function searches through 'list-expr' for 'expr'. If 'expr'
+is found, 'remove' returns the list with the 'expr' deleted. All occurances
+of 'expr' are deleted. If 'expr' is not found, then the 'list-expr' is
+returned unaltered. You may specify your own test with the ':test' and
+':test-not' keywords followed by the test you which to perform. Note that
+this operation is non-destructive, it does not modify or affect 'list-expr'
+directly, it creates a modified copy.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq mylist '(a b c d it e f)) <font color="#008844">; set up a list</font>
+(remove 'it mylist) <font color="#008844">; returns (A B C D E F)</font>
+(print mylist) <font color="#008844">; prints (A B C D IT E F)</font>
+ <font color="#008844">; note that MYLIST is not affected</font>
+
+(setq mylist '(a b c b d b)) <font color="#008844">; change list to include duplicates</font>
+(remove 'b mylist) <font color="#008844">; returns (A C D)</font>
+
+(setq alist '( (a) (b) (it) (c))) <font color="#008844">; set up another list</font>
+(remove '(it) alist) <font color="#008844">; returns ((A) (B) (IT) (C))</font>
+ <font color="#008844">; the EQ test doesn't work for lists</font>
+(remove '(it) alist :test 'equal) <font color="#008844">; returns ((A) (B) (C))</font>
+
+(setq slist '( "a" "b" "it" "c")) <font color="#008844">; set up yet another list</font>
+(remove "it" slist) <font color="#008844">; returns ("a" "b" "c")</font>
+(remove "it" slist :test-not 'equal) <font color="#008844">; returns ("it")</font>
+ <font color="#008844">; REMOVE takes away everything but IT</font>
+</pre>
+
+<p><b>Note:</b> The 'remove' function can work with a list or string as the
+'expr'. However, the default <a href="eql.htm">eql</a> test does
+not work with lists or strings, only symbols and numbers. To make this work,
+you need to use the ':test' keyword along with
+<a href="equal.htm">equal</a> for 'test'.</p>
+
+<p><b>Common Lisp:</b> XLISP does not support the ':from-end', ':start',
+':end', ':count' and ':key' keywords which Common Lisp does.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#remove">remove</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/remprop.htm b/docsrc/xlisp/xlisp-doc/reference/remprop.htm new file mode 100644 index 0000000..8b98b92 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/remprop.htm @@ -0,0 +1,94 @@ +<html><head><title>XLISP remprop</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>remprop</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(remprop <i>symbol property</i>)</dt>
+<dd><i>symbol</i> - the symbol with a property list<br>
+<i>property</i> - the property name being removed<br>
+returns - the property value</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'remprop' function removes the 'property' from the 'symbol'. The
+function returns a <a href="nil.htm">NIL</a>. If the 'property'
+does not exist, there is no error generated. The 'symbol' must be an
+existing symbol. Property lists are lists attached to any user defined
+variables. The lists are in the form of:</p>
+
+<pre class="example">
+(<font color="#008844"><i>name1 val1 name2 val2</i></font> ... )
+</pre>
+
+<p>Any number of properties may be attached to a single variable.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq person 'bobby) <font color="#008844">; create a var with a value</font>
+(putprop person 'boogie 'last-name) <font color="#008844">; add a LAST-NAME property</font>
+(putprop person 'disc-jockey 'job) <font color="#008844">; add a JOB property</font>
+
+(get person 'last-name) <font color="#008844">; retrieve LAST-NAME - boogie</font>
+(get person 'job) <font color="#008844">; retrieve JOB - disc-jockey</font>
+(get person 'height) <font color="#008844">; non-existant - returns NIL</font>
+
+(remprop person 'job) <font color="#008844">; remove JOB</font>
+(remprop person 'height) <font color="#008844">; remove non-existant</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp does not have a 'remprop' function. It
+uses <a href="setf.htm">setf</a> to achieve this functionality.
+Porting from Common Lisp to XLISP will work fine since XLISP supports the
+<a href="setf.htm">setf</a> modifications of property lists and
+the <a href="get.htm">get</a> function to retrieve property
+values from symbol names. Porting from XLISP to Common LISP will require
+translating 'remprop' into <a href="setf.htm">setf</a> forms.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-014.htm#remprop">remprop</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/rest.htm b/docsrc/xlisp/xlisp-doc/reference/rest.htm new file mode 100644 index 0000000..1937471 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/rest.htm @@ -0,0 +1,80 @@ +<html><head><title>XLISP rest</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>rest</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(rest <i>expr</i>)</dt>
+<dd><i>expr</i> - a list or list expression<br>
+returns - <i>expr</i> with the first element removed</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'rest' function returns the remainder of a list or list expression
+after first element of the list is removed. If the list is
+<nobr><a href="nil.htm">NIL</a> ,</nobr>
+<a href="nil.htm">NIL</a> is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(rest '(a b c)) <font color="#008844">; returns (B C)</font>
+(rest '((a b) c d)) <font color="#008844">; returns (C D)</font>
+(rest NIL) <font color="#008844">; returns NIL</font>
+(rest 'a) <font color="#008844">; error: bad argument type</font>
+(rest '(a)) <font color="#008844">; returns NIL</font>
+
+(setq sisters '(virginia vicki cindy)) <font color="#008844">; set up variable SISTERS</font>
+(first sisters) <font color="#008844">; returns VIRGINIA</font>
+(rest sisters) <font color="#008844">; returns (VICKI CINDY)</font>
+</pre>
+
+<p><b>Note:</b> The 'rest' function is set to the same code as the
+<a href="cdr.htm">cdr</a> function.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#rest">rest</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/restore.htm b/docsrc/xlisp/xlisp-doc/reference/restore.htm new file mode 100644 index 0000000..577cfc1 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/restore.htm @@ -0,0 +1,112 @@ +<html><head><title>XLISP restore</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>restore</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xldmem.c, xlimage.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(restore <i>file</i>)</dt>
+<dd><i>file</i> - a string or symbol for the name of the file<br>
+returns - <a href="nil.htm">NIL</a> on failure, otherwise never
+returns</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'restore' function restores the previously
+<a href="save.htm">save</a>d XLISP workspace [system state] from
+the specified file. The 'file' may be a string or a symbol. If the 'file'
+does not include a '.wks' suffix, it will be extended to be called
+'file.wks'. If successful, 'restore' will print a message saying:</p>
+
+<pre class="example">
+[ returning to the top level ]
+</pre>
+
+<p>and will not return any value. If 'restore' fails, it will return
+<a href="nil.htm">NIL</a>. There can be several saved workspaces.
+These workspaces can be restored as often as desired.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq myvar 5) <font color="#008844">; set MYVAR to value 5</font>
+myvar <font color="#008844">; returns 5</font>
+
+(save 'farp) <font color="#008844">; save workspace in FARP.wks</font>
+
+(setq myvar "garp") <font color="#008844">; change MYVAR to "garp"</font>
+myvar <font color="#008844">; returns "garp"</font>
+
+(restore 'farp) <font color="#008844">; restore workspace</font>
+myvar <font color="#008844">; returns 5</font>
+</pre>
+
+<p><b>File names:</b> In the PC and DOS world, all file names and extensions
+["foo.bat"] are automatically made uppercase. In using XLISP, this
+means you don't have to worry about whether the name is "foo.bat",
+"FOO.BAT" or even "FoO.bAt", they will all work.
+However, in other file systems [UNIX in particular], uppercase and lowercase
+do make a difference:</p>
+
+<p>This will create a file named FOO-FILE in UNIX, because XLISP uppercases
+its symbols:</p>
+
+<pre class="example">
+(open 'foo-file :direction :output)
+</pre>
+
+<p>This will create a file named 'foo-file' because UNIX doesn't
+uppercase its file names:</p>
+
+<pre class="example">
+(open "foo-file" :direction :output)
+</pre>
+
+<p>So, if you are having trouble with opening and accessing files, check to
+make sure the file name is in the proper case.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-031.htm#restore">restore</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/return-from.htm b/docsrc/xlisp/xlisp-doc/reference/return-from.htm new file mode 100644 index 0000000..ea00206 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/return-from.htm @@ -0,0 +1,89 @@ +<html><head><title>XLISP return-from</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>return-from</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(return-from <i>name</i> [<i>expr</i>])</dt>
+<dd><i>name</i> - an unevaluated symbol for the block name<br>
+<i>expr</i> - an expression<br>
+returns - never returns</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'return-from' special form allows the return of an arbitrary value at
+arbitrary times within a 'named-<a href="block.htm">block</a>'
+construct of the specified 'name'. The 'expr' will be returned by the
+<a href="block.htm">block</a> construct. A
+<a href="nil.htm">NIL</a> will be returned by the <a
+href="block.htm">block</a> construct if there is no 'expr'
+specified.</p>
+
+<p>If 'return-from' is used without being within a valid
+<a href="block.htm">block</a> construct, an error is generated:</p>
+
+<pre class="example">
+<font color="#AA0000">error: no target for RETURN</font>
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(block out <font color="#008844">; outer BLOCK</font>
+ (print "outer")
+ (block in <font color="#008844">; inner BLOCK</font>
+ (print "inner")
+ (return-from out "all done")
+ (print "won't get here"))) <font color="#008844">; prints "outer"</font>
+ <font color="#008844">; prints "inner"</font>
+ <font color="#008844">; returns "all done"</font>
+
+(return-from nobody 9) <font color="#008844">; error: no target for RETURN</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-021.htm#return-from">return-from</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/return.htm b/docsrc/xlisp/xlisp-doc/reference/return.htm new file mode 100644 index 0000000..9e52426 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/return.htm @@ -0,0 +1,93 @@ +<html><head><title>XLISP return</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>return</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(return [<i>expr</i>])</dt>
+<dd><i>expr</i> - an expression<br>
+returns - never returns</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'return' special form allows the return of an arbitrary value at
+arbitrary times within 'block' constructs like
+<nobr><a href="do.htm">do</a> ,</nobr>
+<nobr><a href="do-star.htm">do*</a> ,</nobr>
+<nobr><a href="dolist.htm">dolist</a> ,</nobr>
+<nobr><a href="dotimes.htm">dotimes</a> ,</nobr>
+<nobr><a href="loop.htm">loop</a> ,</nobr>
+<a href="prog.htm">prog</a> and
+<a href="prog-star.htm">prog*</a>. The 'expr' will be returned by the
+outer 'block' construct. A <a href="nil.htm">NIL</a> will be
+returned by the outer 'block' construct if there is no 'expr' specified.</p>
+
+<p>If 'return' is used without being within a valid 'block' construct, an
+error is generated:</p>
+
+<pre class="example">
+<font color="#AA0000">error: no target for RETURN</font>
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(prog (i) <font color="#008844">; PROG form</font>
+ (print i) (RETURN "foo") (print j)) <font color="#008844">; prints NIL returns "foo"</font>
+
+(dotimes (i 10)
+ (if (eql i 5) (RETURN 20)
+ (princ i))) <font color="#008844">; prints 01234 returns 20</font>
+
+(prog1 (print "hi") (RETURN "foo")) <font color="#008844">; prints "hi"</font>
+ <font color="#008844">; error: no target for RETURN</font>
+
+(return 9) <font color="#008844">; error: no target for RETURN</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-021.htm#return">return</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/reverse.htm b/docsrc/xlisp/xlisp-doc/reference/reverse.htm new file mode 100644 index 0000000..f7132cc --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/reverse.htm @@ -0,0 +1,73 @@ +<html><head><title>XLISP reverse</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>reverse</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(reverse list-expr)</dt>
+<dd><i>list-expr</i> - a list or list expression<br>
+returns - a new list in the reverse order</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'reverse' function reverses the 'list-expr'. The reversed list is the
+returned value. The reversal process only occurs on the 'top-level' of the
+'list-expr'. If there are nested sub-lists, these are left intact.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(reverse NIL) <font color="#008844">; returns NIL</font>
+(reverse 'a) <font color="#008844">; error: bad argument type</font>
+(reverse '(a)) <font color="#008844">; returns (A)</font>
+(reverse '(a b c)) <font color="#008844">; returns (C B A)</font>
+(reverse '((a b) (c d) (e f))) <font color="#008844">; returns ((E F) (C D) (A B))</font>
+(reverse (list (+ 1 2) (+ 3 4))) <font color="#008844">; returns (7 3)</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#reverse">reverse</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/room.htm b/docsrc/xlisp/xlisp-doc/reference/room.htm new file mode 100644 index 0000000..79c5d78 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/room.htm @@ -0,0 +1,90 @@ +<html><head><title>XLISP room</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>room</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xldmem.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(room [<i>info</i>])</dt>
+<dd><i>info</i> - an optional, unused expression<br>
+returns - <a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'room' function prints the current memory statistics to
+<a href="global-standard-output.htm">*standard-output*</a>.
+<a href="nil.htm">NIL</a> is always returned. The message shows
+the statistics for:</p>
+
+<ul>
+<li><nobr>total nodes</nobr></li>
+<li><nobr>current free nodes</nobr></li>
+<li><nobr>current number of allocated memory segments</nobr></li>
+<li><nobr>node size of the allocated memory segments</nobr></li>
+<li><nobr>total memory in bytes</nobr></li>
+<li>total number of garbage collections that have occured
+since this session of XLISP started</li>
+</ul>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(room) <font color="#008844">; prints Nodes: 4000</font>
+ <font color="#008844">; Free nodes: 1723</font>
+ <font color="#008844">; Segments: 4</font>
+ <font color="#008844">; Allocate: 1000</font>
+ <font color="#008844">; Total: 52566</font>
+ <font color="#008844">; Collections: 8</font>
+ <font color="#008844">; returns NIL</font>
+</pre>
+
+<p><b>Common Lisp:</b> In Common LISP, the 'info' argument controls the
+amount of information that is printed. In Common Lisp, the form of and
+information provided by the 'room' output is implementation dependent. For
+portability, you should not count on this information or form.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-031.htm#room">room</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/round.htm b/docsrc/xlisp/xlisp-doc/reference/round.htm new file mode 100644 index 0000000..11c84b1 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/round.htm @@ -0,0 +1,81 @@ +<html><head><title>XLISP round</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>round</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp function (closure)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>fileio.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>round</b> <i>number</i>)</nobr></dt>
+<dd><i>number</i> - an integer or floating point numbers<br>
+returns - the number, rounded to the next integer value</dd>
+</dl>
+
+</div></p>
+
+<p>In Nyquist, 'round' is implemented as a Lisp function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">round</font> (x)
+ (cond ((> x 0) (truncate (+ x 0.5)))
+ ((= (- x 0.5) (truncate (- x 0.5))) (truncate x))
+ (t (truncate (- x 0.5)))))
+</pre>
+
+<h2>Description</h2>
+
+<p>The 'round' function rounds a number to the next integer value. This is
+tricky because <a href="truncate.htm">truncate</a> rounds toward zero as
+<nobr>does C</nobr> in other words, rounding is down for positive numbers
+and up for negative numbers. <nobr>You can</nobr> convert rounding up to
+rounding down by subtracting one, but this fails on the integers, so we need
+a special test if <nobr>(- x 0.5)</nobr> is an integer.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(round .5) => 1
+(round -.5) => 0
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/rplaca.htm b/docsrc/xlisp/xlisp-doc/reference/rplaca.htm new file mode 100644 index 0000000..3b6ca54 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/rplaca.htm @@ -0,0 +1,99 @@ +<html><head><title>XLISP rplaca</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>rplaca</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(rplaca <i>list expr</i>)</dt>
+<dd><i>list</i> - the list to destructively modify<br>
+<i>expr</i> - the expression to replace <a href="car.htm">car</a>
+of <i>list</i><br>
+returns - the list node after updating the
+<a href="car.htm">car</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'rplaca' function destructively modifies the
+<a href="car.htm">car</a> of 'list' and replaces it with the
+'expr'. The destructive aspect of this operation means that the actual
+symbol value is used in the list-modifying operations, not a copy. 'list'
+must evaluate to a valid list.</p>
+
+<p>An atom or <a href="nil.htm">NIL</a> for 'list' will result in
+an error:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument type</font>
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq a '(1 2 3)) <font color="#008844">; make A with value (1 2 3)</font>
+(setq b '(1 2 3)) <font color="#008844">; make B with value (1 2 3)</font>
+(setq c a) <font color="#008844">; make C point to A's value</font>
+(rplaca a 'new) <font color="#008844">; returns (NEW 2 3)</font>
+
+(print a) <font color="#008844">; prints (NEW 2 3)</font>
+ <font color="#008844">; note that A is modified</font>
+
+(print b) <font color="#008844">; prints (1 2 3)</font>
+ <font color="#008844">; note that B is not modified</font>
+
+(print c) <font color="#008844">; prints (NEW 2 3)</font>
+ <font color="#008844">; note that C is modified too</font>
+
+(setq a '(1 2 3)) <font color="#008844">; reset A to value (1 2 3)</font>
+(rplaca a '(the sub list)) <font color="#008844">; returns ((THE SUB LIST) 2 3)</font>
+(rplaca '(1 2 3) 'more) <font color="#008844">; returns (MORE 2 3)</font>
+
+(rplaca 'a 'b) <font color="#008844">; error: bad argument type</font>
+(rplaca NIL 'b) <font color="#008844">; error: bad argument type</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-017.htm#rplaca">rplaca</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/rplacd.htm b/docsrc/xlisp/xlisp-doc/reference/rplacd.htm new file mode 100644 index 0000000..11b80c5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/rplacd.htm @@ -0,0 +1,89 @@ +<html><head><title>XLISP rplacd</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>rplacd</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(rplacd list expr)</dt>
+<dd><i>list</i> - the list to destructively modify<br>
+<i>expr</i> - the expression to replace the
+<a href="cdr.htm">cdr</a> of <i>list</i><br>
+returns - the list node after updating the
+<a href="cdr.htm">cdr</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'rplacd' function destructively modifies the
+<a href="cdr.htm">cdr</a> of 'list' and replaces it with the
+'expr'. The destructive aspect of this operation means that the actual
+symbol value is used in the list-modifying operations, not a copy. 'list'
+must evaluate to a valid list.</p>
+
+<p>An atom or <a href="nil.htm">NIL</a> for 'list' will result in
+an error:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument type</font>
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq a '(1 2 3)) <font color="#008844">; set up A with (1 2 3)</font>
+(rplacd a 'new) <font color="#008844">; returns (1 . NEW)</font>
+
+(print a) <font color="#008844">; prints (1 . NEW)</font>
+ <font color="#008844">; note that A is modified</font>
+
+(rplacd a '(a new list)) <font color="#008844">; returns (1 A NEW LIST)</font>
+(rplacd '(1 2 3) '(more)) <font color="#008844">; returns (1 MORE)</font>
+
+(rplacd 'a 'b) <font color="#008844">; error: bad argument type</font>
+(rplacd NIL 'b) <font color="#008844">; error: bad argument type</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-017.htm#rplacd">rplacd</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">XLISP</a> >
+<a href="../manual/xlisp-man-index.htm">XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> -
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/rrandom.htm b/docsrc/xlisp/xlisp-doc/reference/rrandom.htm new file mode 100644 index 0000000..5735287 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/rrandom.htm @@ -0,0 +1,66 @@ +<html><head><title>XLISP rrandom</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>rrandom</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c, xlisp.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>rrandom</b>)</nobr></dt>
+<dd>returns - a random floating point number between 0 and 1 inclusive</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'random' function returns a random floating point number between 0
+and 1 inclusive.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/save.htm b/docsrc/xlisp/xlisp-doc/reference/save.htm new file mode 100644 index 0000000..8b7aba3 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/save.htm @@ -0,0 +1,124 @@ +<html><head><title>XLISP save</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>save</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr> xldmem.c, xlimage.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(save <i>file</i>)</dt>
+<dd><i>file</i> - a string or symbol for the name of the file<br>
+returns - <a href="t.htm"> T </a> if workspace was
+written, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'save' function saves the current XLISP workspace [system state] to
+the specified file. The 'file' may be a string or a symbol. If the 'file'
+does not include a '.wks' suffix, it will be extended to be called
+'file.wks'. The function returns
+<a href="t.htm"> T </a> if the workspace was properly
+created and saved, <a href="nil.htm">NIL</a> is returned
+otherwise. There can be several saved workspaces. These workspaces can be
+restored as often as desired.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq myvar 5) <font color="#008844">; set MYVAR to value 5</font>
+myvar <font color="#008844">; returns 5</font>
+
+(save 'farp) <font color="#008844">; save workspace in FARP.wks</font>
+
+(setq myvar "garp") <font color="#008844">; change MYVAR to "garp"</font>
+myvar <font color="#008844">; returns "garp"</font>
+
+(restore 'farp) <font color="#008844">; restore workspace</font>
+myvar <font color="#008844">; returns 5</font>
+</pre>
+
+<p><b>Bug:</b> The 'save' function generates a system error if the 'file'
+being created already exists. This 'file' will be modified and will not be
+restorable after restarting XLISP. [I still haven't tested this with
+Nyquist.]</p>
+
+<p><b>Note:</b> The saved workspace size is implementation dependent, but
+can be fairly large.</p>
+
+<p><b>File names:</b> In the PC and DOS world, all file names and extensions
+["foo.bat"] are automatically made uppercase. In using XLISP, this
+means you don't have to worry about whether the name is "foo.bat",
+"FOO.BAT" or even "FoO.bAt", they will all work.
+However, in other file systems [UNIX in particular], uppercase and lowercase
+do make a difference:</p>
+
+<p>This will create a file named FOO-FILE in UNIX, because XLISP uppercases
+its symbols:</p>
+
+<pre class="example">
+(open 'foo-file :direction :output)
+</pre>
+
+<p>This will create a file named 'foo-file' because UNIX doesn't
+uppercase its file names:</p>
+
+<pre class="example">
+(open "foo-file" :direction :output)
+</pre>
+
+<p>So, if you are having trouble with opening and accessing files, check to
+make sure the file name is in the proper case.</p>
+
+<p><b>Common Lisp:</b> The XLISP 'save' function is similar in use to the
+'save-world' function in Common Lisp. The primarily difference is that
+'save-world' allows you to restart everything since it creates an executable
+file. The 'save' function requires you to start XLISP up first and then do a
+<a href="restore.htm">restore</a>. Depending on the operating system
+that you are using, it is possible to write a 'save-world' equivalent using
+'save', <a href="restore.htm">restore</a> and system.htm
+functions.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-031.htm#save">save</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/second.htm b/docsrc/xlisp/xlisp-doc/reference/second.htm new file mode 100644 index 0000000..1b1c3e0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/second.htm @@ -0,0 +1,81 @@ +<html><head><title>XLISP second</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>second</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(second <i>expr</i>)</dt>
+<dd><i>expr</i> - a list or list expression<br>
+returns - the second element of <i>expr</i></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'second' function returns the second element of a list or list
+expression. If the list is
+<nobr><a href="nil.htm">NIL</a> ,</nobr>
+<a href="nil.htm">NIL</a> is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(second '(1 2 3)) <font color="#008844">; returns 2</font>
+(second NIL) <font color="#008844">; returns NIL</font>
+
+(setq carol '(a b c)) <font color="#008844">; set up variable CAROL</font>
+(first carol) <font color="#008844">; returns A</font>
+(second carol) <font color="#008844">; returns B</font>
+(rest carol) <font color="#008844">; returns (B C)</font>
+
+(setq children '(amanda ben)) <font color="#008844">; set up variable CHILDREN</font>
+(second children) <font color="#008844">; returns BEN</font>
+</pre>
+
+<p><b>Note:</b> This function is set to the same code as the
+<a href="caar.htm">cadr</a> function.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#second">second</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/self.htm b/docsrc/xlisp/xlisp-doc/reference/self.htm new file mode 100644 index 0000000..83ca806 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/self.htm @@ -0,0 +1,81 @@ +<html><head><title>XLISP self</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>self</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>symbol</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlobj.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> self</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'self' symbol evaluates to the current object when used within a
+message context.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq my-class (send class :new '(state))) <font color="#008844">; create MY-CLASS with STATE</font>
+
+(send my-class :answer :isnew '() <font color="#008844">; set up initialization</font>
+ '((setq state nil) SELF)) <font color="#008844">; returning SELF</font>
+
+(send my-class :answer :set-it '(value) <font color="#008844">; create :SET-IT message</font>
+ '((setq state value)))
+
+(setq my-obj (send my-class :new)) <font color="#008844">; create MY-OBJ of MY-CLASS</font>
+(send my-obj :set-it 5) <font color="#008844">; STATE is set to 5</font>
+</pre>
+
+<p><b>Context:</b> 'self' does not exist except within the context of a
+method and it's execution.</p>
+
+<p><b>Note:</b> In the previous example, there is a 'self' in the line that
+creates the ':set-it' message. What this does is to return the object as the
+last operation when you do an <a href="keyword-isnew.htm">:isnew</a>.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-010.htm#10-3">self</a>
+symbol in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/send-super.htm b/docsrc/xlisp/xlisp-doc/reference/send-super.htm new file mode 100644 index 0000000..c29d01f --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/send-super.htm @@ -0,0 +1,87 @@ +<html><head><title>XLISP send-super</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>send-super</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlobj.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(send-super <i>message</i> [<i>args</i>])</dt>
+<dd><i>message</i> - the message selector<br>
+<i>args</i> - the optional message arguments<br>
+returns - the result of sending the message</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'send-super' function sends the specified arguments 'args' to the
+'message' specified method of the superclass. It is necessary for
+'send-super' to be executed from within a method being performed on an
+<a href="object.htm">object</a>. It will return the result of
+sending the message. If 'send-super' is performed outside of a method an
+error will result.</p>
+
+<pre class="example">
+<font color="#AA0000">error: not in a method</font>
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq a-class (send class :new '())) <font color="#008844">; create A-CLASS</font>
+
+(send a-class :answer :show '() <font color="#008844">; set up special SHOW method</font>
+ '((print "nobody here") self))
+
+(setq an-obj (send a-class :new)) <font color="#008844">; create AN-OBJ of A-CLASS</font>
+(send an-obj :show) <font color="#008844">; prints "nobody here"</font>
+
+(send a-class :answer :myshow '() <font color="#008844">; set up MYSHOW method which</font>
+ '((send-super :show ))) <font color="#008844">; calls :SHOW in superclass</font>
+
+(send an-obj :myshow) <font color="#008844">; prints Object is ...</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-010.htm#10-4">send-super</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/send.htm b/docsrc/xlisp/xlisp-doc/reference/send.htm new file mode 100644 index 0000000..8874399 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/send.htm @@ -0,0 +1,96 @@ +<html><head><title>XLISP send</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>send</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlobj.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(send object message [args])</dt>
+<dd><i>object</i> - an <a href="object.htm">object</a><br>
+<i>message</i> - message selector for <i>object</i><br>
+<i>arg</i> - parameter sent to <i>object</i> method<br>
+returns - the <i>object</i></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'send' function is the mechanism used to send a 'message' to an
+<a href="object.htm">object</a>. The 'message' is the message
+selector symbol that is used to select a particular action [method] from
+the <a href="object.htm">object</a>.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq myclass (send class :new '(var))) <font color="#008844">; create MYCLASS with VAR</font>
+
+(send myclass :answer :isnew '() <font color="#008844">; set up initialization</font>
+ '((setq var nil) self))
+
+(send myclass :answer :set-it '(value) <font color="#008844">; create :SET-IT message</font>
+ '((setq var value)))
+
+(setq my-obj (send myclass :new)) <font color="#008844">; create MY-OBJ of MYCLASS</font>
+(send my-obj :set-it 5) <font color="#008844">; VAR is set to 5</font>
+</pre>
+
+<p><b>Built-in methods:</b> The built in methods in XLISP include:</p>
+
+<ul>
+<li><nobr><a href="keyword-answer.htm">:answer</a> - add a method to an object</nobr></li>
+<li><nobr><a href="keyword-class.htm">:class</a> - return the object's <a href="class.htm">class</a></nobr></li>
+<li><nobr><a href="keyword-isnew.htm">:isnew</a> - run initialization code on object</nobr></li>
+<li><nobr><a href="keyword-new.htm">:new</a> - create a new object [instance or <a href="class.htm">class</a>]</nobr></li>
+<li><nobr><a href="keyword-show.htm">:show</a> - show the internal state of the object</nobr></li>
+</ul>
+
+<p><b>Message structure:</b> The normal XLISP convention for a 'message' is
+to have a valid symbol preceeded by a colon like
+<a href="keyword-isnew.htm">:isnew</a> or ':my-message'. However, it is
+possible to define a 'message' that is a symbol without a colon, but this
+makes the code less readable.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-010.htm#10-2">send</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/set-difference.htm b/docsrc/xlisp/xlisp-doc/reference/set-difference.htm new file mode 100644 index 0000000..731ecb7 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/set-difference.htm @@ -0,0 +1,75 @@ +<html><head><title>XLISP set-difference</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>set-difference</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp function (closure)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xm.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>set-difference</b> <i>list1 list2</i>)</nobr></dt>
+<dd><i>listN</i> - a list of symbols or numbers<br>
+returns - the set-difference of <i>list1</i> and <i>list2</i></dd>
+</dl>
+
+</div></p>
+
+<p>In Nyquist, '<nobr>set-difference</nobr>' is implemented as a Lisp function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">set-difference</font> (a b)
+ (remove-if (lambda (elem) (member elem b)) a))
+</pre>
+
+<h2>Description</h2>
+
+<p>The '<nobr>set-difference</nobr>' function computes the
+<nobr>set-difference</nobr> of two lists. <nobr>The result</nobr> is a list
+containing all elements that appear in only one of both lists.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/set.htm b/docsrc/xlisp/xlisp-doc/reference/set.htm new file mode 100644 index 0000000..e67abb0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/set.htm @@ -0,0 +1,83 @@ +<html><head><title>XLISP set</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>set</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(set <i>symbol expr</i>)</dt>
+<dd><i>symbol</i> - expression that evaluates to a symbol name [if the
+expression is quoted, no evaluation occurs]<br>
+<i>expr</i> - an expression, which will be the new value<br>
+returns - the new value</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'set' function evaluates 'symbol' and sets 'expr' as it's value. If
+the 'symbol' value is quoted via the <a href="quote.htm">quote</a>
+special form or read-macro expansion, the 'symbol' is not evaluated. 'set'
+returns the value from 'expr' as it's result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(set 'a 2) <font color="#008844">; sets symbol A to value 2</font>
+(set 'value a) <font color="#008844">; sets symbol VALUE to value 2</font>
+(print value) <font color="#008844">; show the value - prints 2</font>
+
+(set 'name 'myvar) <font color="#008844">; set symbol NAME to value MYVAR</font>
+(set name 12345) <font color="#008844">; set symbol which is the value</font>
+ <font color="#008844">; of NAME (MYVAR) to 12345</font>
+
+(print name) <font color="#008844">; prints MYVAR</font>
+(print myvar) <font color="#008844">; prints 12345</font>
+
+(set notsymbol 1) <font color="#008844">; error: unbound variable</font>
+(set name notvalue) <font color="#008844">; error: unbound variable</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-013.htm#set">set</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/setdir.htm b/docsrc/xlisp/xlisp-doc/reference/setdir.htm new file mode 100644 index 0000000..8e820ec --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/setdir.htm @@ -0,0 +1,65 @@ +<html><head><title>XLISP setdir</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>setdir</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>sys/unix/osstuff.c, sys/win/msvc/winfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(setdir <i>path</i>) - set current directory</dt>
+<dd><i>path</i> - the path of the new directory<br>
+returns - the resulting full path or NIL if an error occurs</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'setdir' function sets current directory, e.g. <nobr>(setdir
+".")</nobr> gets the current working directory.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p>See also <a href="listdir.htm">listdir</a>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/setf.htm b/docsrc/xlisp/xlisp-doc/reference/setf.htm new file mode 100644 index 0000000..72845bf --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/setf.htm @@ -0,0 +1,273 @@ +<html><head><title>XLISP setf</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>setf</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(setf [<i>place1 expr1</i> ... ])</dt>
+<dd><i>placeN</i> - a field specifier which may be one of:<br>
+<dl><dd><i>symbol</i> - set value of a symbol<br>
+(<a href="car.htm">car</a> <i>expr</i>) - set <a href="caar.html">car</a> of a cons node<br>
+(<a href="cdr.htm">cdr</a> <i>expr</i>) - set <a href="cddr.html">cdr</a> of a cons node<br>
+(<a href="nth.htm">nth</a> <i>n expr</i>) - set <a href="or.html">nth</a> car of a list<br>
+(<a href="aref.htm">aref</a> <i>expr n</i>) - set nth element of an array<br>
+(<a href="get.htm">get</a> <i>symbol property</i>) - set value of a property<br>
+(<a href="symbol-value.htm">symbol-value</a> <i>symbol</i>) - set value of a symbol<br>
+(symbol-function <i>symbol</i>) - set functional value of a symbol<br>
+(<a href="symbol-plist.htm">symbol-plist</a> <i>symbol</i>) - set property list of a symbol</dd></dl>
+<i>exprN</i> - an expression, which will be the new value<br>
+returns - the new value</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'setf' special form evaluates the field 'placeN' and sets 'exprN' as
+it's value. This is a generalized tool that allows you to set the value of
+the various data types of the system. 'setf' returns the value from 'exprN'
+as it's result. The specific action of 'setf' depends on the 'placeN' field.
+A more detailed explanation follows below the examples.</p>
+
+<h2>Examples</h2>
+
+
+<pre class="example">
+<font color="#008844">:; setf symbols</font>
+
+(setf a 123) <font color="#008844">; set a symbol A to value 123</font>
+</pre>
+
+<pre class="example">
+<font color="#008844">;; setf symbol-values</font>
+
+(setq x 'y) <font color="#008844">; make symbol X with value Y</font>
+(setf (symbol-value x) 'z) <font color="#008844">; set symbol that X contains (Y) to value Z</font>
+</pre>
+
+<pre class="example">
+<font color="#008844">;; setf list elements</font>
+
+(setq mylist '(a b c d)) <font color="#008844">; MYLIST with value (A B C D)</font>
+
+(setf (car mylist) 'x) <font color="#008844">; change CAR of MYLIST to X</font>
+ <font color="#008844">; MYLIST now is (X B C D)</font>
+
+(setf (cdr mylist) '(y z da-end)) <font color="#008844">; change CDR of MYLIST to (Y Z DA-END)</font>
+ <font color="#008844">; MYLIST now is (X Y Z DA-END)</font>
+
+(setf (nth 3 mylist) 'here-i-am) <font color="#008844">; change 3rd of MYLIST to HERE-I-AM</font>
+ <font color="#008844">; MYLIST now is (X Y Z HERE-I-AM)</font>
+</pre>
+
+<pre class="example">
+<font color="#008844">;; setf arrays</font>
+
+(setq myarray (make-array 5)) <font color="#008844">; make MYARRAY</font>
+(aref myarray 2) <font color="#008844">; get value of element 2 = NIL</font>
+(setf (aref myarray 2) 'new-value) <font color="#008844">; set value of element 2 to value NEW-VALUE</font>
+(print myarray) <font color="#008844">; prints #(NIL NIL NEW-VALUE NIL NIL)</font>
+</pre>
+
+<pre class="example">
+<font color="#008844">;; setf properties</font>
+
+(setq person 'joe-bob) <font color="#008844">; make PERSON with value JOE-BOB</font>
+(putprop person 'critic 'profession) <font color="#008844">; set PROFESSION property to value CRITIC</font>
+(setf (get person 'profession) <font color="#008844">; change PROFESSION to value TEXAS-CRITIC</font>
+(setf (get person 'home) 'texas) <font color="#008844">; add property HOME with value TEXAS</font>
+
+(symbol-plist person) <font color="#008844">; returns property list:</font>
+ <font color="#008844">; (HOME TEXAS</font>
+ <font color="#008844">; PROFESSION TEXAS-CRITIC)</font>
+
+(setf (symbol-plist person) <font color="#008844">; change the property list</font>
+ '(home on-the-range
+ profession movie-critic))
+
+(get person 'profession) <font color="#008844">; now returns MOVIE-CRITIC</font>
+(get person 'home) <font color="#008844">; now returns ON-THE-RANGE</font>
+</pre>
+
+<h2>Operations</h2>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(setf <i>sym exprN</i>)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">Sets the value of 'symbol' to the value of 'exprN'.
+ This is equivalent to <nobr>(<a href="setq.htm">setq</a>
+ <i>sym exprN</i>)</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(setf (<a href="car.htm">car</a> <i>expr</i>) <i>exprN</i>)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">Sets the first element of the 'expr' list to 'exprN'.
+ 'expr' must be a list. This is equivalent to
+ <nobr>(<a href="rplaca.htm">rplaca</a> <i>expr exprN</i>)</nobr>
+ except that 'setf' will return 'exprN' as the value.</td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(setf (<a href="cdr.htm">cdr</a> <i>expr</i>) <i>exprN</i>)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">Sets the tail of the 'expr' list to 'exprN'. 'expr' must
+ be a list. This is equivalent to
+ <nobr>(<a href="rplacd.htm">rplacd</a> <i>expr exprN</i>)</nobr>
+ except that 'setf' will return 'exprN' as the value.</td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(setf (<a href="nth.htm">nth</a> <i>n expr</i>) <i>exprN</i>)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">Sets the <a href="nth.htm">nth</a> element of
+ the 'expr' list to 'exprN'. 'expr' must be a list. This allows you to
+ set an arbitrary element of a list to an arbitrary value. Note that the
+ list is numbered from the 0th element <nobr>(0, 1, 2, 3,
+ ...).</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(setf (<a href="aref.htm">aref</a> <i>expr n</i>) <i>exprN</i>)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">Sets the nth element of the 'expr' array to 'exprN'.
+ 'expr' must be an array. This allows you to set an arbitrary element of
+ an array to an arbitrary value. Note that the list is numbered from the
+ 0th element <nobr>(0, 1, 2, 3, ...).</nobr> Note also that this is the
+ intended way to set the value of an array element.</td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(setf (<a href="get.htm">get</a> <i>sym prop</i>) <i>exprN</i>)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">Sets the 'property' of 'symbol' to the value 'exprN'.
+ If 'symbol' does not have the 'property', one will be created. This is
+ equivalent to <nobr>(<a href="putprop.htm">putprop</a> <i>sym
+ exprN prop</i>)</nobr>.</td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(setf (<a href="symbol-value.htm">symbol-value</a> <i>sym</i>) <i>exprN</i>)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">Sets the symbol's value to contain 'exprN'. 'symbol' is
+ an expression that must evaluate to a valid symbol, it doesn't have to
+ exist before the 'setf' function is applied, it just has to be a valid
+ symbol. This is equivalent to <nobr>(<a
+ href="set.htm">set</a> <i>symbol exprN</i>).</nobr></td>
+</tr>
+<tr>
+ <td style="height:10px"></td>
+</tr>
+<tr>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(setf (<a href="symbol-plist.htm">symbol-plist</a> <i>sym</i>) <i>exprN</i>)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">Sets the property list of 'symbol' to 'exprN'. This
+ allows you to change or destroy the entire property list of a 'symbol'
+ at one time.</td>
+</tr>
+</tbody></table></p>
+
+<p>See the
+<a href="../manual/xlisp-man-013.htm#setf">setf</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/setq.htm b/docsrc/xlisp/xlisp-doc/reference/setq.htm new file mode 100644 index 0000000..83fee7a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/setq.htm @@ -0,0 +1,70 @@ +<html><head><title>XLISP setq</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>setq</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(setq [<i>symbol1 expr1</i>] ... )</dt>
+<dd><i>symbolN</i> - un-evaluated symbol<br>
+<i>exprN</i> - value for <i>symbolN</i><br>
+returns - the new value</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'setq' special form sets 'expr' as the value of 'symbol'. 'setq'
+returns the value from 'expr' as it's result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq a 1) <font color="#008844">; symbol A gets value 1</font>
+(setq b '(a b c)) <font color="#008844">; symbol B gets value (A B C)</font>
+(setq mynum (+ 3 4)) <font color="#008844">; symbol MYNUM gets value 7</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-013.htm#setq">setq</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/setup-console.htm b/docsrc/xlisp/xlisp-doc/reference/setup-console.htm new file mode 100644 index 0000000..ff21c53 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/setup-console.htm @@ -0,0 +1,72 @@ +<html><head><title>XLISP setup-console</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>setup-console</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>sys/unix/osstuff.c, sys/mac/macstuff.c, sys/win/msvc/winfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(setup-console)</dt>
+<dd>returns - <a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The '<nobr>setup-console</nobr>' function sets the default console
+attributes.</p>
+
+<p><b>Note:</b> Under Windows, Nyquist normally starts up in a
+<nobr>medium-sized</nobr> console window with black text and a white
+background, with a window title of 'Nyquist'. This is normally accomplished
+by calling '<nobr>setup-console</nobr>' <nobr>in 'system.lsp'</nobr>.
+<nobr>In Nyquist</nobr>, you can avoid this behavior by setting
+<nobr>*setup-console*</nobr> to <a href="nil.htm">NIL</a> in your
+'<nobr>init.lsp</nobr>' file. <nobr>If 'setup-console'</nobr> is not called,
+Nyquist uses standard input and output <nobr>as is</nobr>. This is what you
+want if you are running Nyquist inside of emacs, for example.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/sin.htm b/docsrc/xlisp/xlisp-doc/reference/sin.htm new file mode 100644 index 0000000..6ca07b6 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/sin.htm @@ -0,0 +1,76 @@ +<html><head><title>XLISP sin</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>sin</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(sin <i>expr</i>)</dt>
+<dd><i>expr</i> - floating point number or expression<br>
+returns - the sine of the number</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'sin' function returns the sine of the 'expr'. The 'expr' is in
+radians.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(sin 0.0) <font color="#008844">; returns 0</font>
+(sin .5) <font color="#008844">; returns 0.479426</font>
+(sin 1.0) <font color="#008844">; returns 0.841471</font>
+(sin (/ 3.14159 2)) <font color="#008844">; returns 1</font>
+(sin 3.14159) <font color="#008844">; returns 2.65359e-06</font>
+(sin 0) <font color="#008844">; error: bad integer operation</font>
+(sin 1.) <font color="#008844">; error: bad integer operation</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common LISP allows for integer numbers, which
+XLISP does not support for 'sin'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-023.htm#sin">sin</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/sort.htm b/docsrc/xlisp/xlisp-doc/reference/sort.htm new file mode 100644 index 0000000..ac874e1 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/sort.htm @@ -0,0 +1,104 @@ +<html><head><title>XLISP sort</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>sort</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(sort <i>list test</i>)</dt>
+<dd><i>list</i> - a list containing elements to be sorted<br>
+<i>test</i> - the test to use for the sort<br>
+returns - the sorted list</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'sort' function sorts the 'list' using the 'test' to order the
+list. The 'sort' function is destructive and modifies the 'list'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq a '(3 1 4 1 5 9 6 7)) <font color="#008844">; returns (3 1 4 1 5 9 6 7)</font>
+
+(sort a '<) <font color="#008844">; returns (1 1 3 4 5 6 7 9)</font>
+
+(print a) <font color="#008844">; returns (1 1 3 4 5 6 7 9)</font>
+ <font color="#008844">; notice that A is modified</font>
+
+(sort a '>) <font color="#008844">; returns (9 7 6 5 4 3 1 1)</font>
+
+(sort '("a" "bar" "foo") 'string>) <font color="#008844">; returns ("foo" "bar" "a")</font>
+</pre>
+
+<p><div class="box">
+
+<p><b>XLISP Bug</b></p>
+
+<p>Nyquist 'sort' returns the proper value, but improperly modifies the
+symbol or the actual 'list', for example:</p>
+
+<pre class="example">
+(setq a '(3 1 4 1 5 9 6 7)) => (3 1 4 1 5 9 6 7)
+(sort a '<) => (1 1 3 4 5 6 7 9) <font color="#008844">; OK</font>
+a => (3 4 5 6 7 9) <font color="#AA0000">; BUG</font>
+</pre>
+
+<p>But this way it works:</p>
+
+<pre class="example">
+(setq a '(3 1 4 1 5 9 6 7)) => (3 1 4 1 5 9 6 7)
+(setq a (sort a '<)) => (1 1 3 4 5 6 7 9)
+a => (1 1 3 4 5 6 7 9)
+</pre>
+
+</div></p>
+
+<p><b>Common Lisp:</b> Common Lisp allows for a ':key' keyword, which
+allows a specified function to be run before the ordering takes place, which
+XLISP does not support.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-017.htm#sort">sort</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/soundp.htm b/docsrc/xlisp/xlisp-doc/reference/soundp.htm new file mode 100644 index 0000000..3e72247 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/soundp.htm @@ -0,0 +1,70 @@ +<html><head><title>XLISP soundp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>soundp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>sndfnint.c, sound.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>soundp</b> <i>expr</i>)</nobr></dt>
+<dd><i>expr</i> - an arbitrary Lisp expression<br>
+returns - <a href="t.htm"> T </a> if <i>expr</i> is a sound,
+<a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'soundp' function returns <a href="t.htm"> T </a> if
+'expr' is a Nyquist sound, <a href="nil.htm">NIL</a> otherwise.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p>Please see the Nyquist manual for Nyquist/XLISP audio functions.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/sqrt.htm b/docsrc/xlisp/xlisp-doc/reference/sqrt.htm new file mode 100644 index 0000000..c563933 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/sqrt.htm @@ -0,0 +1,76 @@ +<html><head><title>XLISP sqrt</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>sqrt</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(sqrt <i>expr</i>)</dt>
+<dd><i>expr</i> - floating point number or expression<br>
+returns - the square root of the number</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'sqrt' function calculates the square root of 'expr' and returns
+this result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(sqrt 1.0) <font color="#008844">; returns 1</font>
+(sqrt 2.0) <font color="#008844">; returns 1.41421</font>
+(sqrt 3.0) <font color="#008844">; returns 1.73205</font>
+(sqrt 4.0) <font color="#008844">; returns 2</font>
+(sqrt 5.0) <font color="#008844">; returns 2.23607</font>
+(sqrt -1.0) <font color="#008844">; error: square root of a negative number</font>
+(sqrt 2) <font color="#008844">; error: bad integer operation</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp allows for integer numbers, which
+XLISP does not support for 'sqrt'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-023.htm#sqrt">sqrt</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/strcat.htm b/docsrc/xlisp/xlisp-doc/reference/strcat.htm new file mode 100644 index 0000000..f0437b9 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/strcat.htm @@ -0,0 +1,72 @@ +<html><head><title>XLISP strcat</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>strcat</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(strcat [<i>string1</i> ... ])</dt>
+<dd><i>stringN</i> - a string expression<br>
+returns - the result of concatenating the strings</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'strcat' function returns the concatenation of a sequence of string
+expressions. If there are no strings, an empty string is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(strcat) <font color="#008844">; returns ""</font>
+(strcat "a") <font color="#008844">; returns "a"</font>
+(strcat "a" "b") <font color="#008844">; returns "ab"</font>
+(strcat "ab" "cd" "ef") <font color="#008844">; returns "abcdef"</font>
+(strcat "f" "ire tr" "uck") <font color="#008844">; returns "fire truck"</font>
+(strcat 1 2) <font color="#008844">; error: bad argument type</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#strcat">strcat</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/streamp.htm b/docsrc/xlisp/xlisp-doc/reference/streamp.htm new file mode 100644 index 0000000..848998b --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/streamp.htm @@ -0,0 +1,84 @@ +<html><head><title>XLISP streamp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>streamp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(streamp <i>expr</i>)</dt>
+<dd><i>expr</i> - the expression to check<br>
+returns - <a href="t.htm"> T </a> if the value is a
+stream, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'streamp' predicate function checks if an 'expr' is a stream.
+<a href="t.htm"> T </a> is returned if 'expr' is a
+stream, <a href="nil.htm">NIL</a> is returned otherwise.</p>
+
+<p>EXAMPLES</p>
+
+<pre class="example">
+(streamp *standard-input*) <font color="#008844">; returns T - stream</font>
+(streamp *debug-io*) <font color="#008844">; returns T - stream</font>
+(streamp (make-string-output-stream)) <font color="#008844">; returns T - stream</font>
+
+(setq a *standard-output*)
+(streamp a) <font color="#008844">; returns T - evaluates to stream</font>
+
+(streamp "a") <font color="#008844">; returns NIL - string</font>
+(streamp #\a) <font color="#008844">; returns NIL - character</font>
+(streamp '(a b c)) <font color="#008844">; returns NIL - list</font>
+(streamp 1) <font color="#008844">; returns NIL - integer</font>
+(streamp 1.2) <font color="#008844">; returns NIL - float</font>
+(streamp '*debug-io*) <font color="#008844">; returns NIL - symbol</font>
+(streamp 'a) <font color="#008844">; returns NIL - symbol</font>
+(streamp #(0 1 2)) <font color="#008844">; returns NIL - array</font>
+(streamp NIL) <font color="#008844">; returns NIL - NIL</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#streamp">streamp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-downcase.htm b/docsrc/xlisp/xlisp-doc/reference/string-downcase.htm new file mode 100644 index 0000000..f67c211 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-downcase.htm @@ -0,0 +1,80 @@ +<html><head><title>XLISP string-downcase</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string-downcase</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string-downcase <i>string</i> [{:start | :end} <i>offset</i>] ... )</dt>
+<dd><i>string</i> - a string expression<br>
+<i>offset</i> - an optional integer expression for a keyword<br>
+returns - a converted copy of the string</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string-downcase' function takes a string argument and returns a new
+string that has been made lower case.</p>
+
+<p>The keyword arguments allow for accessing substrings within 'string'. The
+keyword arguments require a keyword ':start' or ':end' first and a single
+integer expression second. The ':start' keyword specifies the starting
+offset for the 'string-downcase' operation on 'string'. A value of 0 starts
+the string at the beginning [no offset]. The ':end' keyword specifies the
+end offset for the operation on 'string'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string-downcase "ABcd+-12&[") <font color="#008844">; returns "abcd+-&["</font>
+(string-downcase "ABCDEFGH" :start 2 :end 4) <font color="#008844">; returns "ABcdEFGH"</font>
+
+(setq mystr "ABcdEFgh") <font color="#008844">; set up variable</font>
+(string-downcase mystr) <font color="#008844">; returns "abcdefgh"</font>
+(print mystr) <font color="#008844">; prints "ABcdEFgh"</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-downcase">string-downcase</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-equal-i.htm b/docsrc/xlisp/xlisp-doc/reference/string-equal-i.htm new file mode 100644 index 0000000..f83b91c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-equal-i.htm @@ -0,0 +1,111 @@ +<html><head><title>XLISP tring-equal</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string-equal</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string-equal <i>string1 string2</i> [<i>key offset</i>] ... )</dt>
+<dd><i>stringN</i> - a string expression<br>
+<i>key</i> - a keyword [one of :start1 :start2 :end1 :end2]<br>
+<i>offset</i> - an optional integer expression for a keyword<br>
+returns - <a href="t.htm"> T </a> if <i>string1</i>
+equal to <i>string2</i>,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is not significant with this function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string-equal' function takes two string arguments. It checks to see
+if the string arguments have the same values.
+<a href="t.htm"> T </a> is returned if 'string1' is
+equal to 'string2', <a href="nil.htm">NIL</a> is returned
+otherwise. This test is not case sensitive, the character '#\a' is
+considered to be the same as '#\A'.</p>
+
+<p>The keyword arguments allow for accessing substrings within 'string1' and
+'string2'. The keyword arguments each require a keyword ':start1', ':end1',
+':start2' or ':end2' and a single integer expression as a pair with the
+keyword first and the integer second. The pairs may be in any order. The
+':startN' keywords specify the starting offset of the substring. A value of
+0 starts the string at the beginning [no offset]. The ':endN' keywords
+specify the ending offset of the substring. A value of 3 ends the string
+after the 3rd character [an offset of 3 characters].</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string-equal "a" "b") <font color="#008844">; returns NIL</font>
+(string-equal "a" "a") <font color="#008844">; returns T</font>
+(string-equal "a" "A") <font color="#008844">; returns T</font>
+(string-equal "A" "a") <font color="#008844">; returns T</font>
+(string-equal "abc" "abc ") <font color="#008844">; returns NIL</font>
+
+(string-equal "J Smith" "K Smith" :start1 1 :start2 1) <font color="#008844">; strip off the first chars</font>
+ <font color="#008844">; returns T</font>
+
+(string-equal "abc" "123456789" :end2 3 :end1 3) <font color="#008844">; leave just the first 3 chars</font>
+ <font color="#008844">; returns NIL</font>
+</pre>
+
+<p><b>Bug:</b> The 'string-equal' function is listed in the original XLISP
+documentation as 'string-equalp'. In the XLISP interpreter a call to
+'string-equalp' causes an error:</p>
+
+<pre class="example">
+<font color="#AA0000">error: unbound function - STRING-EQUALP</font>
+</pre>
+
+<p>The 'string-equal' function works exactly as the 'string-equalp' function
+described in the XLISP manual. This bug had obviously been corrected in
+the manual only but never in the interpreter. As the bug still exists with
+<nobr>Nyquist 2.36</nobr> in <nobr>July 2007</nobr> as well as all other
+<nobr>XLISP 2.x</nobr> implementations I know, I have changed both manuals
+to 'string-equal' even if I myself whould consider 'string-equalp' as the
+better name.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-equalp">string-equal</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-equal-s.htm b/docsrc/xlisp/xlisp-doc/reference/string-equal-s.htm new file mode 100644 index 0000000..a50ad74 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-equal-s.htm @@ -0,0 +1,96 @@ +<html><head><title>XLISP string=</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string=</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string= <i>string1 string2</i> [<i>key offset</i>] ... )</dt>
+<dd><i>stringN</i> - a string expression<br>
+<i>key</i> - a keyword [one of :start1 :start2 :end1 :end2]<br>
+<i>offset</i> - an optional integer expression for a keyword<br>
+returns - <a href="t.htm"> T </a> if the string
+arguments have the same values,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is significant with this function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string=' [string-equal] function takes two string arguments. It
+checks to see if the string arguments have the same values.
+<a href="t.htm"> T </a> is returned if 'string1' is
+equal to 'string2', <a href="nil.htm">NIL</a> is returned
+otherwise. This test is case sensitive, the character '#\a' is different and
+of greater <a href="../misc/ascii-table.htm">ASCII</a> value than
+'#\A'.</p>
+
+<p>The keyword arguments allow for accessing substrings within 'string1' and
+'string2'. The keyword arguments each require a keyword ':start1', ':end1',
+':start2' or ':end2' and a single integer expression as a pair with the
+keyword first and the integer second. The pairs may be in any order. The
+':startN' keywords specify the starting offset of the substring. A value of
+0 starts the string at the beginning [no offset]. The ':endN' keywords
+specify the ending offset of the substring. A value of 3 ends the string
+after the 3rd character [an offset of 3 characters].</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string= "a" "b") <font color="#008844">; returns NIL</font>
+(string= "a" "a") <font color="#008844">; returns T</font>
+(string= "a" "A") <font color="#008844">; returns NIL</font>
+(string= "A" "a") <font color="#008844">; returns NIL</font>
+(string= "abc" "abc ") <font color="#008844">; returns NIL</font>
+
+(string= "J Smith" "K Smith" :start1 1 :start2 1) <font color="#008844">; strip off the first chars </font>
+ <font color="#008844">; returns T</font>
+
+(string= "abc" "123456789" :end2 3 :end1 3) <font color="#008844">; leave just the first 3 chars </font>
+ <font color="#008844">; returns NIL</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-equal">string=</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-greaterp-i.htm b/docsrc/xlisp/xlisp-doc/reference/string-greaterp-i.htm new file mode 100644 index 0000000..71b18db --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-greaterp-i.htm @@ -0,0 +1,98 @@ +<html><head><title>XLISP string-greaterp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string-greaterp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string-greaterp <i>string1 string2</i> [<i>key offset</i>] ... )</dt>
+<dd><i>stringN</i> - a string expression<br>
+<i>key</i> - a keyword [one of :start1 :start2 :end1 :end2]<br>
+<i>offset</i> - an optional integer expression for a keyword<br>
+returns - a non-<a href="nil.htm">NIL</a> value if <i>string1</i>
+is greater than <i>string2</i> in
+<a href="../misc/ascii-table.htm">ASCII</a> ordering,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is not significant with this function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string-greaterp' [string-greater-than] predicate function takes two
+string arguments. A non-<a href="nil.htm">NIL</a> value is
+returned if 'string1' is greater than 'string2' in
+<a href="../misc/ascii-table.htm">ASCII</a> ordering, otherwise
+<a href="nil.htm">NIL</a> is returned. The
+non-<a href="nil.htm">NIL</a> value returned is the integer index
+of the first character of 'string1' which is
+<a href="char-greaterp-i.htm">char-greaterp</a> [char-greater-than] the
+corresponding character of 'string2'. This test is not case sensitive, the
+character '#\a' is considered to be the same as '#\A'.</p>
+
+<p>The keyword arguments allow for accessing substrings within 'string1' and
+'string2'. The keyword arguments each require a keyword ':start1', ':end1',
+':start2' or ':end2' and a single integer expression as a pair with the
+keyword first and the integer second. The pairs may be in any order. The
+':startN' keywords specify the starting offset of the substring. A value of
+0 starts the string at the beginning [no offset]. The ':endN' keywords
+specify the ending offset of the substring. A value of 3 ends the string
+after the 3rd character [an offset of 3 characters].</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string-greaterp "a" "b") <font color="#008844">; returns NIL</font>
+(string-greaterp "a" "a") <font color="#008844">; returns NIL</font>
+(string-greaterp "a" "A") <font color="#008844">; returns NIL</font>
+(string-greaterp "A" "a") <font color="#008844">; returns NIL</font>
+(string-greaterp "abc" "abc ") <font color="#008844">; returns NIL</font>
+(string-greaterp "1234qrst" "12345678") <font color="#008844">; returns 4</font>
+
+(string-greaterp "J Smith" "K Jones" :start1 1 :start2 1) <font color="#008844">; strip off the first chars </font>
+ <font color="#008844">; returns 2</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-greaterp">string-greaterp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-greaterp-s.htm b/docsrc/xlisp/xlisp-doc/reference/string-greaterp-s.htm new file mode 100644 index 0000000..c5f5fa4 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-greaterp-s.htm @@ -0,0 +1,99 @@ +<html><head><title>XLISP string></title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string></h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string> string1 string2 [key offset] ... )</dt>
+<dd><i>stringN</i> - a string expression<br>
+<i>key</i> - a keyword [one of :start1 :start2 :end1 :end2]<br>
+<i>offset</i> - an optional integer expression for a keyword<br>
+returns - a non-<a href="nil.htm">NIL</a> value if <i>string1</i>
+is greater than <i>string2</i> in
+<a href="../misc/ascii-table.htm">ASCII</a> ordering,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is significant with this function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string>' [string-greater-than] function takes two string
+arguments. A non-<a href="nil.htm">NIL</a> value is returned if
+'string1' is greater than 'string2' in
+<a href="../misc/ascii-table.htm">ASCII</a> ordering, otherwise
+<a href="nil.htm">NIL</a> is returned. The
+non-<a href="nil.htm">NIL</a> value returned is the integer index
+of the first character of 'string1' which is
+<a href="char-greaterp-s.htm">char></a> [char-greater-than] the
+corresponding character of 'string2'. This test is case sensitive, the
+character '#\a' is different and of greater
+<a href="../misc/ascii-table.htm">ASCII</a> value than '#\A'.</p>
+
+<p>The keyword arguments allow for accessing substrings within 'string1' and
+'string2'. The keyword arguments each require a keyword ':start1', ':end1',
+':start2' or ':end2' and a single integer expression as a pair with the
+keyword first and the integer second. The pairs may be in any order. The
+':startN' keywords specify the starting offset of the substring. A value of
+0 starts the string at the beginning [no offset]. The ':endN' keywords
+specify the ending offset of the substring. A value of 3 ends the string
+after the 3rd character [an offset of 3 characters].</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string> "a" "b") <font color="#008844">; returns NIL</font>
+(string> "a" "a") <font color="#008844">; returns NIL</font>
+(string> "a" "A") <font color="#008844">; returns 0</font>
+(string> "A" "a") <font color="#008844">; returns NIL</font>
+(string> "abc" "abc ") <font color="#008844">; returns NIL</font>
+(string> "1234qrst" "12345678") <font color="#008844">; returns 4</font>
+
+(string> "J Smith" "K Jones" :start1 1 :start2 1) <font color="#008844">; strip off the first chars</font>
+ <font color="#008844">; returns 2</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-greater-than">string></a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-left-trim.htm b/docsrc/xlisp/xlisp-doc/reference/string-left-trim.htm new file mode 100644 index 0000000..bf88c2c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-left-trim.htm @@ -0,0 +1,84 @@ +<html><head><title>XLISP string-left-trim</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string-left-trim</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string-left-trim <i>trim-stuff string</i>)</dt>
+<dd><i>trim-stuff</i> - a string expression<br>
+<i>string</i> - a string expression<br>
+returns - a trimed copy of the string</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string-left-trim' function takes the 'trim-stuff' characters and
+removes them from the left end of the 'string'. The 'trim-stuff' characters
+are an un-ordered set of characters to be removed, so any character that
+occurs in 'trim-stuff' is removed if it appears in left portion of 'string'.
+A new string is created and returned as the result of this function.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string-left-trim "." "....foo....") <font color="#008844">; returns "foo...."</font>
+(string-left-trim "<>" "<<<<bar>>>>") <font color="#008844">; returns "bar>>>>"</font>
+(string-left-trim "(.)" "..(12.34)..") <font color="#008844">; returns "12.34).."</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp also supports a list of characters as
+a valid 'trim-stuff' argument. An example:</p>
+
+<pre class="example">
+(string-trim '(#\Tab #\Newline) mystring)
+</pre>
+
+<p>XLISP does not support non-string parameters. Porting from XLISP will
+be no problem, but modifications will be necessary if porting from Common
+Lisp code which uses a list of characters.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-left-trim">string-left-trim</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-lessp-i.htm b/docsrc/xlisp/xlisp-doc/reference/string-lessp-i.htm new file mode 100644 index 0000000..14d40f7 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-lessp-i.htm @@ -0,0 +1,98 @@ +<html><head><title>XLISP string-lessp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string-lessp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string-lessp <i>string1 string2</i> [<i>key offset</i>] ... )</dt>
+<dd><i>stringN</i> - a string expression<br>
+<i>key</i> - a keyword [one of :start1 :start2 :end1 :end2]<br>
+<i>offset</i> - an optional integer expression for a keyword<br>
+returns - a non-<a href="nil.htm">NIL</a> value if <i>string1</i>
+is less than <i>string2</i> in
+<a href="../misc/ascii-table.htm">ASCII</a> ordering,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is not significant with this function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string-lessp' [string-less-than] predicate function takes two string
+arguments. A non-<a href="nil.htm">NIL</a> value is returned if
+'string1' is less than 'string2' in
+<a href="../misc/ascii-table.htm">ASCII</a> ordering, otherwise
+<a href="nil.htm">NIL</a> is returned. The
+non-<a href="nil.htm">NIL</a> value returned is the integer index
+of the first character of 'string1' which is
+<a href="char-lessp-i.htm">char-lessp</a> [char-less-than] the
+corresponding character of 'string2'. This test is not case sensitive, the
+character '#\a' is considered to be the same as '#\A'.</p>
+
+<p>The keyword arguments allow for accessing substrings within 'string1' and
+'string2'. The keyword arguments each require a keyword ':start1', ':end1',
+':start2' or ':end2' and a single integer expression as a pair with the
+keyword first and the integer second. The pairs may be in any order. The
+':startN' keywords specify the starting offset of the substring. A value of
+0 starts the string at the beginning [no offset]. The ':endN' keywords
+specify the ending offset of the substring. A value of 3 ends the string
+after the 3rd character [an offset of 3 characters].</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string-lessp "a" "b") <font color="#008844">; returns 0</font>
+(string-lessp "a" "a") <font color="#008844">; returns NIL</font>
+(string-lessp "a" "A") <font color="#008844">; returns NIL</font>
+(string-lessp "A" "a") <font color="#008844">; returns NIL</font>
+(string-lessp "abc" "abc ") <font color="#008844">; returns 3</font>
+(string-lessp "1234567" "1234qrst") <font color="#008844">; returns 4</font>
+
+(string-lessp "J Smith" "K Smith" :start1 1 :start2 1) <font color="#008844">; strip off the first chars</font>
+ <font color="#008844">; returns NIL</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-lessp">string-lessp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-lessp-s.htm b/docsrc/xlisp/xlisp-doc/reference/string-lessp-s.htm new file mode 100644 index 0000000..393ef49 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-lessp-s.htm @@ -0,0 +1,98 @@ +<html><head><title>XLISP string<</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string<</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string< <i>string1 string2</i> [<i>key offset</i>] ... )</dt>
+<dd><i>stringN</i> - a string expression<br>
+<i>key</i> - a keyword [one of :start1 :start2 :end1 :end2]<br>
+<i>offset</i> - an optional integer expression for a keyword<br>
+returns - a non-<a href="nil.htm">NIL</a> value if <i>string1</i>
+is less than <i>string2</i> in
+<a href="../misc/ascii-table.htm">ASCII</a> ordering,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is significant with this function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string<' [string-less-than] function takes two string arguments.
+A non-<a href="nil.htm">NIL</a> value is returned if 'string1'
+is less than 'string2' in <a href="../misc/ascii-table.htm">ASCII</a>
+ordering, otherwise <a href="nil.htm">NIL</a> is returned. The
+non-<a href="nil.htm">NIL</a> value returned is the integer index
+of the first character of 'string1' which is
+<a href="char-lessp-s.htm">char<</a> [char-less-than] the corresponding
+character of 'string2'. This test is case sensitive, the character '#\a' is
+different and of greater <a href="../misc/ascii-table.htm">ASCII</a>
+value than '#\A'.</p>
+
+<p>The keyword arguments allow for accessing substrings within 'string1' and
+'string2'. The keyword arguments each require a keyword ':start1', ':end1',
+':start2' or ':end2' and a single integer expression as a pair with the
+keyword first and the integer second. The pairs may be in any order. The
+':startN' keywords specify the starting offset of the substring. A value of
+0 starts the string at the beginning [no offset]. The ':endN' keywords
+specify the ending offset of the substring. A value of 3 ends the string
+after the 3rd character [an offset of 3 characters].</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string< "a" "b") <font color="#008844">; returns 0</font>
+(string< "a" "a") <font color="#008844">; returns NIL</font>
+(string< "a" "A") <font color="#008844">; returns NIL</font>
+(string< "A" "a") <font color="#008844">; returns 0</font>
+(string< "abc" "abc ") <font color="#008844">; returns 3</font>
+(string< "1234567" "1234qrst") <font color="#008844">; returns 4</font>
+
+(string< "J Smith" "K Smith" :start1 1 :start2 1) <font color="#008844">; strip off the first chars</font>
+ <font color="#008844">; returns NIL</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-less-than">string<</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-not-equal-i.htm b/docsrc/xlisp/xlisp-doc/reference/string-not-equal-i.htm new file mode 100644 index 0000000..4360306 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-not-equal-i.htm @@ -0,0 +1,112 @@ +<html><head><title>XLISP string-not-equal</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string-not-equal</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string-not-equal string1 string2 [key offset] ... )</dt>
+<dd><i>stringN</i> - a string expression<br>
+<i>key</i> - a keyword [one of :start1 :start2 :end1 :end2]<br>
+<i>offset</i> - an optional integer expression for a keyword<br>
+returns - a non-<a href="nil.htm">NIL</a> value if <i>string1</i>
+is not equal to <i>string2</i>,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is not significant with this function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string-not-equal' function takes two string arguments. A
+non-<a href="nil.htm">NIL</a> value is returned if 'string1' is
+not equal to 'string2', otherwise <a href="nil.htm">NIL</a> is
+returned. The non-<a href="nil.htm">NIL</a> value returned is the
+integer index of the first character of 'string1' which is
+<a href="char-not-equal-i.htm">char-not-equal</a> to the corresponding
+character of 'string2'. This test is not case sensitive, the character
+'#\a' is considered to be the same as '#\A'.</p>
+
+<p>The keyword arguments allow for accessing substrings within 'string1' and
+'string2'. The keyword arguments each require a keyword ':start1', ':end1',
+':start2' or ':end2' and a single integer expression as a pair with the
+keyword first and the integer second. The pairs may be in any order. The
+':startN' keywords specify the starting offset of the substring. A value of
+0 starts the string at the beginning [no offset]. The ':endN' keywords
+specify the ending offset of the substring. A value of 3 ends the string
+after the 3rd character [an offset of 3 characters].</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string-not-equal "a" "b") <font color="#008844">; returns 0</font>
+(string-not-equal "a" "a") <font color="#008844">; returns NIL</font>
+(string-not-equal "a" "A") <font color="#008844">; returns NIL</font>
+(string-not-equal "A" "a") <font color="#008844">; returns NIL</font>
+(string-not-equal "abc" "abc ") <font color="#008844">; returns 3</font>
+
+(string-not-equal "J Smith" "K Smith" :start1 1 :start2 1) <font color="#008844">; strip off the first chars</font>
+ <font color="#008844">; returns NIL</font>
+(string-not-equal "abc" "123456789" :end2 3 :end1 3) <font color="#008844">; leave just the first 3 chars</font>
+ <font color="#008844">; returns 0</font>
+</pre>
+
+<p><b>Bug:</b> The 'string-not-equal' function is listed in the original
+XLISP documentation as 'string-not-equalp'. In the XLISP interpreter a call
+to 'string-not-equalp' causes an error:</p>
+
+<pre class="example">
+<font color="#AA0000">error: unbound function - STRING-NOT-EQUALP</font>
+</pre>
+
+<p>The 'string-not-equal' function works exactly as the 'string-not-equalp'
+function described in the XLISP manual. This bug had obviously been
+corrected in the manual only but never in the interpreter. As the bug still
+exists with <nobr>Nyquist 2.36</nobr> in <nobr>July 2007</nobr> as well as
+all other <nobr>XLISP 2.x</nobr> implementations I know, I have changed both
+manuals to 'string-not-equal' even if I myself whould consider
+'string-not-equalp' as the better name.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-not-equalp">string-not-equal</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-not-equal-s.htm b/docsrc/xlisp/xlisp-doc/reference/string-not-equal-s.htm new file mode 100644 index 0000000..ef515c6 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-not-equal-s.htm @@ -0,0 +1,104 @@ +<html><head><title>XLISP string/=</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string/=</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string/= <i>string1 string2</i> [<i>key offset</i>] ... )</dt>
+<dd><i>stringN</i> - a string expression<br>
+<i>key</i> - a keyword [one of :start1 :start2 :end1 :end2]<br>
+<i>offset</i> - an optional integer expression for a keyword<br>
+returns - a non-<a href="nil.htm">NIL</a> value if <i>string1</i>
+is not equal to <i>string2</i>,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is significant with this function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string/=' [string-not-equal] function takes two string arguments. A
+non-<a href="nil.htm">NIL</a> value is returned if 'string1' is
+not equal to 'string2', otherwise
+<a href="nil.htm">NIL</a> is returned. The
+non-<a href="nil.htm">NIL</a> value returned is the integer index
+of the first character of 'string1' which is
+<a href="char-not-equal-s.htm">char/=</a> [char-not-equal] to the
+corresponding character of 'string2'.
+This test is case sensitive, the character '#\a' is different and of greater
+<a href="../misc/ascii-table.htm">ASCII</a> value than '#\A'.</p>
+
+<p>The keyword arguments allow for accessing substrings within 'string1' and
+'string2'. The keyword arguments each require a keyword ':start1', ':end1',
+':start2' or ':end2' and a single integer expression as a pair with the
+keyword first and the integer second. The pairs may be in any order. The
+':startN' keywords specify the starting offset of the substring. A value of
+0 starts the string at the beginning [no offset]. The ':endN' keywords
+specify the ending offset of the substring. A value of 3 ends the string
+after the 3rd character [an offset of 3 characters].</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string/= "a" "b") <font color="#008844">; returns 0</font>
+(string/= "a" "a") <font color="#008844">; returns NIL</font>
+(string/= "a" "A") <font color="#008844">; returns 0</font>
+(string/= "A" "a") <font color="#008844">; returns 0</font>
+(string/= "abc" "abc ") <font color="#008844">; returns 3</font>
+
+(string/= "J Smith" "K Smith" :start1 1 :start2 1) <font color="#008844">; returns NIL</font>
+(string/= "abc" "123456789" :end2 3 :end1 3) <font color="#008844">; returns 0</font>
+</pre>
+
+<p><b>Note:</b> Be sure that the 'string/=' function is properly typed in.
+The '/' is a forward slash. It is possible to mistakenly type a '\'
+backslash. This is especially easy because the character mechanism is '#\a'.
+If you do use the backslash, no error will be reported because backslash is
+the single escape character and the XLISP reader will evaluate 'string\=' as
+'string='. No error will be reported, but the sense of the test is
+reversed.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-not-equal">string/=</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-not-greaterp-i.htm b/docsrc/xlisp/xlisp-doc/reference/string-not-greaterp-i.htm new file mode 100644 index 0000000..a5cafa8 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-not-greaterp-i.htm @@ -0,0 +1,99 @@ +<html><head><title>XLISP string-not-greaterp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string-not-greaterp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string-not-greaterp <i>string1 string2</i> [<i>key offset</i>] ... )</dt>
+<dd><i>stringN</i> - a string expression<br>
+<i>key</i> - a keyword [one of :start1 :start2 :end1 :end2]<br>
+<i>offset</i> - an optional integer expression for a keyword<br>
+returns - a non-<a href="nil.htm">NIL</a> value if <i>string1</i>
+is less than or equal to <i>string2</i> in
+<a href="../misc/ascii-table.htm">ASCII</a> ordering,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is not significant with this function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string-not-greaterp' [string-not-greater-than] predicate function
+takes two string arguments. A non-<a href="nil.htm">NIL</a> value
+is returned if 'string1' is less than or equal to 'string2' in
+<a href="../misc/ascii-table.htm">ASCII</a> ordering, otherwise
+<a href="nil.htm">NIL</a> is returned. The
+non-<a href="nil.htm">NIL</a> value returned is the integer index
+of the first character of 'string1' which is
+<a href="">char-not-greaterp</a> [char-not-greater-than] the corresponding
+character of 'string2'. This test is not case sensitive, the character
+'#\a' is considered to be the same as '#\A'.</p>
+
+<p>The keyword arguments allow for accessing substrings within 'string1' and
+'string2'. The keyword arguments each require a keyword ':start1', ':end1',
+':start2' or ':end2' and a single integer expression as a pair with the
+keyword first and the integer second. The pairs may be in any order. The
+':startN' keywords specify the starting offset of the substring. A value of
+0 starts the string at the beginning [no offset]. The ':endN' keywords
+specify the ending offset of the substring. A value of 3 ends the string
+after the 3rd character [an offset of 3 characters].</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string-not-greaterp "a" "b") <font color="#008844">; returns 0</font>
+(string-not-greaterp "b" "a") <font color="#008844">; returns NIL</font>
+(string-not-greaterp "a" "a") <font color="#008844">; returns 1</font>
+(string-not-greaterp "a" "A") <font color="#008844">; returns 1</font>
+(string-not-greaterp "A" "a") <font color="#008844">; returns 1</font>
+(string-not-greaterp "abc" "abc ") <font color="#008844">; returns 3</font>
+(string-not-greaterp "12345" "1234qr") <font color="#008844">; returns 4</font>
+
+(string-not-greaterp "J Smith" "K Smith" :start1 1 :start2 1) <font color="#008844">; strip off the first chars</font>
+ <font color="#008844">; returns 7</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-not-greaterp">string-not-greaterp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-not-greaterp-s.htm b/docsrc/xlisp/xlisp-doc/reference/string-not-greaterp-s.htm new file mode 100644 index 0000000..8710fdf --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-not-greaterp-s.htm @@ -0,0 +1,99 @@ +<html><head><title>XLISP string<=</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string<=</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string<= <i>string1 string2</i> [<i>key offset</i>] ... )</dt>
+<dd><i>stringN</i> - a string expression<br>
+<i>key</i> - a keyword [one of :start1 :start2 :end1 :end2]<br>
+<i>offset</i> - an optional integer expression for a keyword<br>
+returns - a non-<a href="nil.htm">NIL</a> value if <i>string1</i>
+is less than or equal to <i>string2</i> in
+<a href="../misc/ascii-table.htm">ASCII</a> ordering,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is significant with this function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string<=' [string-less-than-or-equal] function takes two string
+arguments. A non-<a href="nil.htm">NIL</a> value is returned if
+'string1' is less than or equal to 'string2' in
+<a href="../misc/ascii-table.htm">ASCII</a> ordering, otherwise
+<a href="nil.htm">NIL</a> is returned. The
+non-<a href="nil.htm">NIL</a> value returned is the integer index
+of the first character of 'string1' which is
+<a href="char-not-greaterp-s.htm">char<=</a> [char-less-than-or-equal] to the
+corresponding character of 'string2'. This test is case sensitive, the
+character '#\a' is different and of greater
+<a href="../misc/ascii-table.htm">ASCII</a> value than '#\A'.</p>
+
+<p>The keyword arguments allow for accessing substrings within 'string1' and
+'string2'. The keyword arguments each require a keyword ':start1', ':end1',
+':start2' or ':end2' and a single integer expression as a pair with the
+keyword first and the integer second. The pairs may be in any order. The
+':startN' keywords specify the starting offset of the substring. A value of
+0 starts the string at the beginning [no offset]. The ':endN' keywords
+specify the ending offset of the substring. A value of 3 ends the string
+after the 3rd character [an offset of 3 characters].</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string<= "a" "b") <font color="#008844">; returns 0</font>
+(string<= "a" "a") <font color="#008844">; returns 1</font>
+(string<= "a" "A") <font color="#008844">; returns NIL</font>
+(string<= "A" "a") <font color="#008844">; returns 0</font>
+(string<= "abc" "abc ") <font color="#008844">; returns 3</font>
+(string<= "1234567" "1234qrst") <font color="#008844">; returns 4</font>
+
+(string<= "J Smith" "K Smith" :start1 1 :start2 1) <font color="#008844">; strip off the first chars</font>
+ <font color="#008844">; returns 7</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-less-than-or-equal">string<=</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-not-lessp-i.htm b/docsrc/xlisp/xlisp-doc/reference/string-not-lessp-i.htm new file mode 100644 index 0000000..e70c391 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-not-lessp-i.htm @@ -0,0 +1,98 @@ +<html><head><title>XLISP string-not-lessp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string-not-lessp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string-not-lessp <i>string1 string2</i> [<i>key offset</i>] ... )</dt>
+<dd><i>stringN</i> - a string expression<br>
+<i>key</i> - a keyword [one of :start1 :start2 :end1 :end2]<br>
+<i>offset</i> - an optional integer expression for a keyword<br>
+returns - a non-<a href="nil.htm">NIL</a> value if <i>string1</i>
+is greater than or equal to <i>string2</i> in
+<a href="../misc/ascii-table.htm">ASCII</a> ordering,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is not significant with this function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string-not-lessp' [string-not-less-than] predicate function
+takes two string arguments. A non-<a href="nil.htm">NIL</a> value
+is returned if 'string1' is greater than or equal to 'string2' in
+<a href="../misc/ascii-table.htm">ASCII</a> ordering, otherwise
+<a href="nil.htm">NIL</a> is returned. The
+non-<a href="nil.htm">NIL</a> value returned is the integer index
+of the first character of 'string1' which is
+<a href="char-lessp-i.htm">char-not-lessp</a> [char-not-less-than] the
+corresponding character of 'string2'. This test is not case sensitive, the
+character '#\a' is considered to be the same as '#\A'.</p>
+
+<p>The keyword arguments allow for accessing substrings within 'string1' and
+'string2'. The keyword arguments each require a keyword ':start1', ':end1',
+':start2' or ':end2' and a single integer expression as a pair with the
+keyword first and the integer second. The pairs may be in any order. The
+':startN' keywords specify the starting offset of the substring. A value of
+0 starts the string at the beginning [no offset]. The ':endN' keywords
+specify the ending offset of the substring. A value of 3 ends the string
+after the 3rd character [an offset of 3 characters].</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string-not-lessp "a" "b") <font color="#008844">; returns NIL</font>
+(string-not-lessp "a" "a") <font color="#008844">; returns 1</font>
+(string-not-lessp "a" "A") <font color="#008844">; returns 1</font>
+(string-not-lessp "A" "a") <font color="#008844">; returns 1</font>
+(string-not-lessp "abc" "abc ") <font color="#008844">; returns NIL</font>
+(string-not-lessp "1234qr" "123456") <font color="#008844">; returns 4</font>
+
+(string-not-lessp "J Smith" "K Jones" :start1 1 :start2 1) <font color="#008844">; strip off the first chars </font>
+ <font color="#008844">; returns 2</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-not-lessp">string-not-lessp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-not-lessp-s.htm b/docsrc/xlisp/xlisp-doc/reference/string-not-lessp-s.htm new file mode 100644 index 0000000..527c116 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-not-lessp-s.htm @@ -0,0 +1,99 @@ +<html><head><title>XLISP string>=</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string>=</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string>= <i>string1 string2</i> [<i>key offset</i>] ... )</dt>
+<dd><i>stringN</i> - a string expression<br>
+<i>key</i> - a keyword [one of :start1 :start2 :end1 :end2]<br>
+<i>offset</i> - an optional integer expression for a keyword<br>
+returns - a non-<a href="nil.htm">NIL</a> value if <i>string1</i>
+is greater than or equal to <i>string2</i> in
+<a href="../misc/ascii-table.htm">ASCII</a> ordering,
+<a href="nil.htm">NIL</a> otherwise<br>
+<b>Note:</b> case is significant with this function</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string>=' [string-greater-than-or-equal] function takes two
+string arguments. A non-<a href="nil.htm">NIL</a> value is
+returned if 'string1' is greater than or equal to 'string2' in an
+<a href="../misc/ascii-table.htm">ASCII</a> ordering, otherwise
+<a href="nil.htm">NIL</a> is returned. The
+non-<a href="nil.htm">NIL</a> value returned is the integer index
+of the first character of 'string1' which is
+<a href="char-not-lessp-s.htm">char>=</a> [char-greater-than-or-equal] to
+the corresponding character of 'string2'. This test is case sensitive, the
+character '#\a' is different and of greater
+<a href="../misc/ascii-table.htm">ASCII</a> value than '#\A'.</p>
+
+<p>The keyword arguments allow for accessing substrings within 'string1' and
+'string2'. The keyword arguments each require a keyword ':start1', ':end1',
+':start2' or ':end2' and a single integer expression as a pair with the
+keyword first and the integer second. The pairs may be in any order. The
+':startN' keywords specify the starting offset of the substring. A value of
+0 starts the string at the beginning [no offset]. The ':endN' keywords
+specify the ending offset of the substring. A value of 3 ends the string
+after the 3rd character [an offset of 3 characters].</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string>= "a" "b") <font color="#008844">; returns NIL</font>
+(string>= "a" "a") <font color="#008844">; returns 1</font>
+(string>= "a" "A") <font color="#008844">; returns 0</font>
+(string>= "A" "a") <font color="#008844">; returns NIL</font>
+(string>= "abc" "abc ") <font color="#008844">; returns NIL</font>
+(string>= "1234qrst" "12345678") <font color="#008844">; returns 4</font>
+
+(string>= "J Smith" "K Jones" :start1 1 :start2 1) <font color="#008844">; strip off the first chars</font>
+ <font color="#008844">; returns 2</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-greater-than-or-equal">string>=</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-right-trim.htm b/docsrc/xlisp/xlisp-doc/reference/string-right-trim.htm new file mode 100644 index 0000000..56cb58d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-right-trim.htm @@ -0,0 +1,85 @@ +<html><head><title>XLISP string-right-trim</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string-right-trim</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string-right-trim <i>trim-stuff string</i>)</dt>
+<dd><i>trim-stuff</i> - a string expression<br>
+<i>string</i> - a string expression<br>
+returns - a trimed copy of the string</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string-right-trim' function takes the 'trim-stuff' characters and
+removes them from the right end of the 'string'. The 'trim-stuff' characters
+are an un-ordered set of characters to be removed, so any character that
+occurs in 'trim-stuff' is removed if it appears in right portion of
+'string'. A new string is created and returned as the result of this
+function.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string-right-trim "." "....foo....") <font color="#008844">; returns "....foo"</font>
+(string-right-trim "<>" "<<<<bar>>>>") <font color="#008844">; returns "<<<<bar"</font>
+(string-right-trim "(.)" "..(12.34)..") <font color="#008844">; returns "..(12.34"</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common LISP also supports a list of characters as
+a valid 'trim-stuff' argument. An example:
+
+<pre class="example">
+(string-trim '(#\Tab #\Newline) mystring)
+</pre>
+
+<p>XLISP does not support non-string parameters. Porting from XLISP will be
+no problem, but modifications will be necessary if porting from Common LISP
+code which uses a list of characters.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-right-trim">string-right-trim</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-search.htm b/docsrc/xlisp/xlisp-doc/reference/string-search.htm new file mode 100644 index 0000000..ebf5e8a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-search.htm @@ -0,0 +1,68 @@ +<html><head><title>XLISP string-search</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string-search</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(<b>string-search</b> <i>pattern</i> <i>string</i> &key :start :end)</dt><dd>
+<i>pattern</i> - a string to search for<br>
+<i>string</i> - the string to be searched<br>
+:start <i>integer</i> - the starting offset in <i>string</i><br>
+:end <i>integer</i> - the ending offset + 1<br>
+returns - index of <i>pattern</i> in <i>string</i> or <a href="nil.htm">NIL</a> if not found</dd>
+</dl>
+
+
+<h2>Description</h2>
+
+<p> The '<nobr>string-search</nobr>' function searches for 'pattern' in
+'string' and returns the index of the first 'pattern' found in 'string' or
+NIL if no pattern was found.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-trim.htm b/docsrc/xlisp/xlisp-doc/reference/string-trim.htm new file mode 100644 index 0000000..7e26375 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-trim.htm @@ -0,0 +1,84 @@ +<html><head><title>XLISP string-trim</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string-trim</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string-trim <i>trim-stuff string</i>)</dt>
+<dd><i>trim-stuff</i> - a string expression<br>
+<i>string</i> - a string expression<br>
+returns - a trimed copy of the string</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string-trim' function takes the 'trim-stuff' characters and removes
+them from both ends of the 'string'. The 'trim-stuff' characters are an
+un-ordered set of characters to be removed, so any character that occurs in
+'trim-stuff' is removed if it appears in 'string'. A new string is created
+and returned as the result of this function.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string-trim "." "....foo....") <font color="#008844">; returns "foo"</font>
+(string-trim "<>" "<<<<bar>>>>") <font color="#008844">; returns "bar"</font>
+(string-trim "(.)" "..(12.34)..") <font color="#008844">; returns "12.34"</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common LISP also supports a list of characters as
+a valid 'trim-stuff' argument. An example:
+
+<pre class="example">
+(string-trim '(#\Tab #\Newline) mystring)
+</pre>
+
+<p>XLISP does not support non-string parameters. Porting from XLISP will be
+no problem, but modifications will be necessary if porting from Common LISP
+code which uses a list of characters.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-trim">string-trim</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string-upcase.htm b/docsrc/xlisp/xlisp-doc/reference/string-upcase.htm new file mode 100644 index 0000000..cd2e54f --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string-upcase.htm @@ -0,0 +1,80 @@ +<html><head><title>XLISP string-upcase</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string-upcase</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string-upcase <i>string</i> [{:start | :end} <i>offset</i>] ... )</dt>
+<dd><i>string</i> - a string expression<br>
+<i>offse</i>t - an optional integer expression for a keyword<br>
+returns - a converted copy of the string</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string-upcase' function takes a string argument and returns a new
+string that has been made upper case.</p>
+
+<p>The keyword arguments allow for accessing substrings within 'string'. The
+keyword arguments require a keyword ':start' or ':end' first and a single
+integer expression second. The ':start' keyword specifies the starting
+offset for the 'string-upcase' operation on 'string'. A value of 0 starts
+the string at the beginning [no offset]. The ':end' keyword specifies the
+end offset for the operation on 'string'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string-upcase "ABcd+-12&[") <font color="#008844">; returns "ABCD+-&["</font>
+(string-upcase "abcdefgh" :start 2 :end 4) <font color="#008844">; returns "abCDefgh"</font>
+
+(setq mystr "ABcdEFgh") <font color="#008844">; set up variable</font>
+(string-upcase mystr) <font color="#008844">; returns "ABCDEFGH"</font>
+(print mystr) <font color="#008844">; prints "ABcdEFgh"</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string-upcase">string-upcase</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/string.htm b/docsrc/xlisp/xlisp-doc/reference/string.htm new file mode 100644 index 0000000..90224fa --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/string.htm @@ -0,0 +1,88 @@ +<html><head><title>XLISP string</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>string</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(string <i>expr</i>)</dt>
+<dd><i>expr</i> - a symbol, character, integer or string expression<br>
+returns - a string</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'string' function makes the 'expr' to be a string. <nobr>If
+the</nobr> 'expr' is a string, it is returned, as is. <nobr>If the</nobr>
+'expr' is a character, a <nobr>one-character</nobr> string is returned.
+<nobr>If the</nobr> 'expr' is a symbol, the symbol is turned into a string.
+<nobr>If the</nobr> 'expr' is an integer, a string representing the
+character with an ASCII code of the lowest 8-bit of the intger will be
+returned:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>(string <font color="#0000CC">integer</font>)</code></nobr></td>
+ <td><nobr> → </nobr></td>
+ <td class="button"><nobr><code>(code-char (rem <font color="#0000CC">integer</font> 256))</code></nobr></td>
+ <td><nobr> → </nobr></td>
+ <td class="button"><nobr><code><font color="#0000CC">string</font></code></nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(string 'foo) <font color="#008844">; returns "FOO"</font>
+(string 'x) <font color="#008844">; returns "X"</font>
+(string "abcdef") <font color="#008844">; returns "abcdef"</font>
+(string #\a) <font color="#008844">; returns "a"</font>
+(string #\A) <font color="#008844">; returns "A"</font>
+(string #\Newline) <font color="#008844">; returns "\n"</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#string">string</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/stringp.htm b/docsrc/xlisp/xlisp-doc/reference/stringp.htm new file mode 100644 index 0000000..a9fa3da --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/stringp.htm @@ -0,0 +1,80 @@ +<html><head><title>XLISP tringp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>stringp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(stringp <i>expr</i>)</dt>
+<dd><i>expr</i> - the expression to check<br>
+returns - <a href="t.htm"> T </a> if the value is a
+string, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'stringp' predicate function checks if 'expr' is a string.
+<a href="t.htm"> T </a> is returned if 'expr' is a
+string, <a href="nil.htm">NIL</a> is returned otherwise.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(stringp "a") <font color="#008844">; returns T - string</font>
+
+(setq a "hi there"
+(stringp a) <font color="#008844">; returns T - evaluates to string</font>
+
+(stringp #\a) <font color="#008844">; returns NIL - character</font>
+(stringp '(a b c)) <font color="#008844">; returns NIL - list</font>
+(stringp 1) <font color="#008844">; returns NIL - integer</font>
+(stringp 1.2) <font color="#008844">; returns NIL - float</font>
+(stringp 'a) <font color="#008844">; returns NIL - symbol</font>
+(stringp #(0 1 2)) <font color="#008844">; returns NIL - array</font>
+(stringp nil) <font color="#008844">; returns NIL - nil</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#stringp">stringp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/sublis.htm b/docsrc/xlisp/xlisp-doc/reference/sublis.htm new file mode 100644 index 0000000..2724892 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/sublis.htm @@ -0,0 +1,129 @@ +<html><head><title>XLISP sublis</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>sublis</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(sublis <i>a-list expr</i> [{:test | :test-not} <i>test</i>])</dt>
+<dd><i>expr</i> - the expression to substitute within, an atom<br>
+<i>a-list</i> - the association list to search<br>
+test - optional test function, default is <a href="eql.htm">eql</a><br>
+returns - the expression with substitutions</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'sublis' function searches through an 'expr' and replaces each of the
+elements in the 'expr' that match the <a href="car.htm">car</a>
+of the elements of the association list 'a-list' with the
+
+<a href="cdr.htm">cdr</a> of elements of the 'a-list'. The 'expr'
+with the substitutions, if any, is returned. You may specify your own test
+with the ':test' and ':test-not' keywords followed by the 'test' you wish to
+perform. The 'sublis' function is normally used with a dotted pair <nobr>(A
+. B)</nobr> association list. It is possible to use a normal list pair
+<nobr>(A B)</nobr> or a list of the form <nobr>(A (B C)).</nobr></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(sublis '((a . b)) '(a a)) <font color="#008844">; returns (B B)</font>
+(sublis '((a b)) '(a a)) <font color="#008844">; returns ((B) (B))</font>
+(sublis '((a (b c))) '(a a)) <font color="#008844">; returns (((B C)) ((B C)))</font>
+
+(setq newlist '((a . 1) <font color="#008844">; set up an association list</font>
+ (b . 2)
+ (c . 3)))
+
+(sublis newlist '(a b c d e f b a c)) <font color="#008844">; returns (1 2 3 D E F 2 1 3)</font>
+
+(sublis newlist 'a) <font color="#008844">; returns 1</font>
+
+(setq mylist '((a my-a) (b his-b) <font color="#008844">; set up a non-dotted pair assoc list</font>
+ (c her-c) (d end)))
+
+(sublis mylist '(a b c d e f g)) <font color="#008844">; returns ((MY-A) (HIS-B)</font>
+ <font color="#008844">; (HER-C) (END) E F G)</font>
+
+(sublis mylist 'a) <font color="#008844">; returns (MY-A)</font>
+
+(setq numlist '((1 . a) (2 . b)) ) <font color="#008844">; set up a new assoc list</font>
+
+(defun mytest (x y) (princ ": ") <font color="#008844">; set up my own test function with 2 parameters</font>
+ (princ x) <font color="#008844">; to see what SUBLIS does</font>
+ (princ " ")
+ (princ y) (terpri)
+ t) <font color="#008844">; always return T</font>
+
+(sublis numlist '(3 1) :test mytest) <font color="#008844">; prints : (3 1) 1</font>
+ <font color="#008844">; returns A - because the entire list succeeds</font>
+ <font color="#008844">; with the test and so (1 . A) produces the</font>
+ <font color="#008844">; returned value</font>
+
+(sublis numlist '(1) :test-not mytest) <font color="#008844">; prints : (1) 1</font>
+ <font color="#008844">; : (1) 2</font>
+ <font color="#008844">; : 1 1</font>
+ <font color="#008844">; : 1 2</font>
+ <font color="#008844">; : NIL 1</font>
+ <font color="#008844">; : NIL 2</font>
+ <font color="#008844">; returns (1) - because SUBLIS tried to match</font>
+ <font color="#008844">; every list/sublist against each entry in the</font>
+ <font color="#008844">; assoc list and failed because of the :TEST-NOT</font>
+ <font color="#008844">; and so returned the original list unaltered</font>
+</pre>
+
+<p><b>Note:</b> The SUBLIS function can work with a list or string as the
+'expr'. However, the default <a href="eql.htm">eql</a> test does
+not work with lists or strings, only symbols and numbers. To make this work,
+you need to use the ':test' keyword along with
+<a href="equal.htm">equal</a> for 'test'.</p>
+
+<p><b>Common Lisp:</b> Common LISP supports the use of the ':key' keyword
+which specifies a function that is applied to each element of 'a-list'
+before it is tested. XLISP does not support this.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#sublis">sublis</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/subseq.htm b/docsrc/xlisp/xlisp-doc/reference/subseq.htm new file mode 100644 index 0000000..ebc0fb4 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/subseq.htm @@ -0,0 +1,83 @@ +<html><head><title>XLISP subseq</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>subseq</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(subseq <i>string start</i> [<i>end</i>])</dt>
+<dd><i>string</i> - a string expression<br>
+<i>start</i> - an integer expression<br>
+<i>end</i> - an integer expression<br>
+returns - the substring between <i>start</i> and <i>end</i></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p> The 'subseq' function extracts a substring from 'string' starting with
+the 'start' offset and ending with the 'end' offset. The 'start' offset has
+a origin or 0. The substring is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(subseq "12345678" 0) <font color="#008844">; returns "12345678"</font>
+(subseq "12345678" 2) <font color="#008844">; returns "345678"</font>
+(subseq "12345678" 2 4) <font color="#008844">; returns "34"</font>
+(subseq "1234" 3) <font color="#008844">; returns "4"</font>
+
+(subseq "1234" 4) <font color="#008844">; returns ""</font>
+(subseq "1234" 4 2) <font color="#008844">; returns ""</font>
+(subseq "1234" 5) <font color="#008844">; error: string index out of bounds - 5</font>
+</pre>
+
+<p><b>Common Lisp:</b> The 'subseq' function in Common Lisp is intended to
+return a portion of a sequence, a sub-sequence. This function operates on
+lists and vectors [one-dimensional arrays of data], basically ordered data.
+Strings are just one of the valid types operated on by 'subseq' in Common
+Lisp. The XLISP 'subseq' function only operates on strings.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-025.htm#subseq">subseq</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/subsetp.htm b/docsrc/xlisp/xlisp-doc/reference/subsetp.htm new file mode 100644 index 0000000..dff9b98 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/subsetp.htm @@ -0,0 +1,79 @@ +<html><head><title>XLISP subsetp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>subsetp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp function (closure)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xm.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>subsetp</b> <i>list1 list2</i>)</nobr></dt>
+<dd><i>listN</i> - a list of symbols or numbers<br>
+returns - <a href="t.htm"> T </a> if <i>list1</i> is a subset of <i>list2</i>, NIL otherwise</dd>
+</dl>
+
+</div></p>
+
+<p>In Nyquist, 'subsetp' is implemented as a Lisp function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">subsetp</font> (a b)
+ (let ((result t))
+ (dolist (elem a)
+ (cond ((not (member elem b))
+ (setf result nil)
+ (return nil))))
+ result))
+</pre>
+
+<h2>Description</h2>
+
+<p>The '<nobr>subsetp</nobr>' function tests if all elements of 'list1' are
+contained in 'list2'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/subst.htm b/docsrc/xlisp/xlisp-doc/reference/subst.htm new file mode 100644 index 0000000..9fc00f0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/subst.htm @@ -0,0 +1,96 @@ +<html><head><title>XLISP subst</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>subst</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(subst <i>new-expr old-expr expr</i> [{:test | :test-not} <i>test</i>])</dt>
+<dd><i>old-expr</i> - the expression to search for<br>
+<i>new-expr</i> - the expression to replace <i>old-expr</i> with<br>
+<i>expr</i> - the expression to substitute within, an atom or list<br>
+<i>test</i> - optional test function, default is <a href="eql.htm">eql</a><br>
+returns - the expression with substitutions</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'subst' function searches through an 'expr' and replaces each of the
+'old-expr' elements with the 'new-expr'. The 'expr' with the substitutions,
+if any, is returned. You may specify your own test with the ':test' and
+':test-not' keywords followed by the 'test' you wish to perform.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(subst 'new 'old '(old mid dif)) <font color="#008844">; returns (NEW MID DIF)</font>
+(subst '(a) 'old '(old mid dif)) <font color="#008844">; returns ((A) MID DIF)</font>
+(subst "a" 'old '(old mid dif)) <font color="#008844">; returns ("a" MID DIF)</font>
+
+(defun mytest (x y) (princ x) (princ " ") <font color="#008844">; define a test function</font>
+ (princ y) (terpri) <font color="#008844">; that prints the arguments</font>
+ T ) <font color="#008844">; and always returns T</font>
+
+(subst 'a 'b '(a b c d) :test 'mytest) <font color="#008844">; prints (A B C D) B returns A</font>
+
+(subst 'a 'b '(a b) :test-not 'mytest) <font color="#008844">; prints (A B) B</font>
+ <font color="#008844">; A B</font>
+ <font color="#008844">; (B) B</font>
+ <font color="#008844">; B B</font>
+ <font color="#008844">; NIL B returns (A B)</font>
+</pre>
+
+<p><b>Note:</b> The 'subst' function can work with a list or string as the
+'expr' However, the default <a href="eql.htm">eql</a> test does
+not work with lists or strings, only symbols and numbers. To make this work,
+you need to use the ':test' keyword along with
+<a href="equal.htm">equal</a> for 'test'.</p>
+
+<p><b>Common Lisp:</b> Common Lisp supports the use of the ':key' keyword
+which specifies a function that is applied to each element of 'expr' before
+it is tested. XLISP does not support this.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#subst">subst</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/subtraction.htm b/docsrc/xlisp/xlisp-doc/reference/subtraction.htm new file mode 100644 index 0000000..96ca6a9 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/subtraction.htm @@ -0,0 +1,88 @@ +<html><head><title>XLISP −</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>−</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(- <i>expr1</i> ...)</nobr></dt>
+<dd><i>exprN</i> - integer or floating point number/expression<br>
+returns - the result of the subtraction</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The '-' function subtracts one or more numbers from the first number
+given and returns the result. If there is only one number as an argument, it
+is negated.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(- 1) => -1
+(- 1 2) => -1
+(- 1 2 3) => -4
+(- 1 2 3 4) => -8
+</pre>
+
+<pre class="example">
+> (print (- 1 2 (* 3.5 (/ 3.9 1.45))))
+-10.4138
+-10.4138
+</pre>
+
+<p>See <a href="multiplication.htm"> * </a>,
+<a href="division.htm"> / </a>, <a href="print.htm">print</a>.
+XLISP first prints the value on the screen, the second number is the
+return value.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>Contents → <a href="../manual/contents.htm#arithmetic-functions">Arithmetic Functions</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/symbol-function.htm b/docsrc/xlisp/xlisp-doc/reference/symbol-function.htm new file mode 100644 index 0000000..e63dc8a --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/symbol-function.htm @@ -0,0 +1,67 @@ +<html><head><title>XLISP symbol-name</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>symbol-function</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(symbol-function <i>symbol</i>)</dt>
+<dd><i>symbol</i> - an expression that evaluates to a symbol name<br>
+returns - the symbol's functional value</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'symbol-function' function ... [this page was missing in the
+original reference and still needs to be written].</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-013.htm#symbol-function">symbol-function</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/symbol-name.htm b/docsrc/xlisp/xlisp-doc/reference/symbol-name.htm new file mode 100644 index 0000000..8ab1ac2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/symbol-name.htm @@ -0,0 +1,80 @@ +<html><head><title>XLISP symbol-name</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>symbol-name</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>symbol-name</b> <i>symbol</i>)</dt>
+<dd><i>symbol</i> - an expression that evaluates to a symbol name<br>
+returns - the symbol's print name</dd>
+</dl>
+
+</div></p>
+
+<h2>Description</h2>
+
+<p>The 'symbol-name' function takes the 'symbol' expression and returns the
+printable string of the 'symbol'. If the 'symbol' had not existed, then it
+will be created and <a href="intern.htm">intern</a>ed into the
+system symbol table
+<nobr><a href="global-obarray.htm">*obarray*</a> ,</nobr> but with it's
+value unbound and an empty property list.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(symbol-name 'foo) <font color="#008844">; returns "FOO"</font>
+(symbol-name 'gleep) <font color="#008844">; returns "GLEEP"</font>
+
+(setq my-symbol 'flop) <font color="#008844">; define MY-SYMBOL</font>
+(symbol-name my-symbol) <font color="#008844">; returns "FLOP"</font>
+</pre>
+
+<p><b>XLISP Bug:</b> The 'symbol-name' function signals a 'bad
+argument type' error with the <nobr>symbol
+<a href="nil.htm">NIL</a></nobr> <nobr>[Nyquist 3.03</nobr> in
+<nobr>December 2010]</nobr>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/symbol-plist.htm b/docsrc/xlisp/xlisp-doc/reference/symbol-plist.htm new file mode 100644 index 0000000..3260cd1 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/symbol-plist.htm @@ -0,0 +1,85 @@ +<html><head><title>XLISP symbol-plist</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>symbol-plist</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr> xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(symbol-plist <i>symbol</i>)</dt>
+<dd><i>symbol</i> - the symbol name with a property list<br>
+returns - the symbol's property list </dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'symbol-plist' function returns the actual property list from the
+'symbol'. The 'symbol' must be an existing, bound variable, but it does not
+need to have anything in it's property list.</p>
+
+<p>Property lists are lists attached to any user defined variables. The lists
+are in the form of:</p>
+
+<pre class="example">
+(<font color="#008844"><i>name1 val1 name2 val2</i></font> ....)
+</pre>
+
+<p>Any number of properties may be attached to a single variable.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq person 'bobby) <font color="#008844">; create a var with a value</font>
+(putprop person 'boogie 'last-name) <font color="#008844">; add a LAST-NAME property</font>
+(putprop person 'disc-jockey 'job) <font color="#008844">; add a JOB property</font>
+(putprop person '(10 20 30) 'stats) <font color="#008844">; add a STATS list</font>
+
+(symbol-plist person) <font color="#008844">; returns the property list:</font>
+ <font color="#008844">; (STATS (10 20 30)</font>
+ <font color="#008844">; JOB DISC-JOCKEY</font>
+ <font color="#008844">; LAST-NAME BOOGIE)</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-013.htm#symbol-plist">symbol-plist</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/symbol-value.htm b/docsrc/xlisp/xlisp-doc/reference/symbol-value.htm new file mode 100644 index 0000000..7097d22 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/symbol-value.htm @@ -0,0 +1,82 @@ +<html><head><title>XLISP symbol-value</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>symbol-value</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(symbol-value <i>symbol</i>)</dt>
+<dd><i>symbol</i> - an expression that evaluates to a symbol name<br>
+returns - the symbol's value</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'symbol-value' function takes the 'symbol' expression and returns
+the current value of the 'symbol'.</p>
+
+<p>If the 'symbol' had not existed, then it will be created and
+<a href="intern.htm">intern</a>ed into the system symbol table
+<nobr><a href="global-obarray.htm">*obarray*</a> ,</nobr> but with it's
+value unbound and an empty property list. In this case of a previously
+non-existant 'symbol', since it has no bound value, the 'symbol-value'
+function will still report an error due to an unbound variable.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq myvar 55) <font color="#008844">; set MYVAR to value 55</font>
+(symbol-value 'myvar) <font color="#008844">; returns 55</font>
+(symbol-value 'floop) <font color="#008844">; error: unbound variable</font>
+
+(setq my-symbol 'a) <font color="#008844">; set MY-SYMBOL to A</font>
+
+(setq a '(contents of symbol a)) <font color="#008844">; set A to value (CONTENTS OF SYMBOL A)</font>
+
+(symbol-value my-symbol) <font color="#008844">; returns (CONTENTS OF SYMBOL A)</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-013.htm#symbol-value">symbol-value</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/symbolp.htm b/docsrc/xlisp/xlisp-doc/reference/symbolp.htm new file mode 100644 index 0000000..c27fd71 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/symbolp.htm @@ -0,0 +1,85 @@ +<html><head><title>XLISP symbolp</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>symbolp</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xllist.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(symbolp <i>expr</i>)</dt>
+<dd><i>expr</i> - the expression to check<br>
+returns - <a href="t.htm"> T </a> if the expression
+is a symbol, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'symbolp' predicate function checks if an 'expr' is a valid symbol.
+<a href="t.htm"> T </a> is returned if 'expr' is a
+symbol, <a href="nil.htm">NIL</a> is returned otherwise. An
+'expr' that evaluates to an integer, function [subr or otherwise], and so
+on is not a symbol. However, the quoted [un-evaluated] name of these
+objects [like 'myarray] is a valid symbol.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(symbolp (make-symbol "a")) <font color="#008844">; returns T - symbol</font>
+(symbolp 'a) <font color="#008844">; returns T - symbol</font>
+
+(symbolp #(1 2 3)) <font color="#008844">; returns NIL - array</font>
+(symbolp (lambda (x) (print x))) <font color="#008844">; returns NIL - closure</font>
+(symbolp *standard-output*) <font color="#008844">; returns NIL - stream</font>
+(symbolp 1.2) <font color="#008844">; returns NIL - float</font>
+(symbolp 2) <font color="#008844">; returns NIL - integer</font>
+(symbolp object) <font color="#008844">; returns NIL - object</font>
+(symbolp "hi") <font color="#008844">; returns NIL - string</font>
+
+(symbolp #'car) <font color="#008844">; returns NIL - subr</font>
+(symbolp 'car) <font color="#008844">; returns T - it is a symbol now</font>
+(symbolp '2) <font color="#008844">; returns NIL - not a symbol</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#symbolp">symbolp</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/system.htm b/docsrc/xlisp/xlisp-doc/reference/system.htm new file mode 100644 index 0000000..e2f5888 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/system.htm @@ -0,0 +1,73 @@ +<html><head><title>XLISP system</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>system</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>sys/unix/osstuff.c, sys/mac/macfun.c, sys/win/msvc/winfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(system <i>command</i>)</dt>
+<dd><i>command</i> - the OS command string to be executed<br>
+returns - <a href="t.htm"> T </a> if the command
+was successful, the error code otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'system' function will send the 'command' string to the underlying
+operating system for execution. After execution of the 'command', the
+'system' function will return a
+<a href="t.htm"> T </a> result if the 'command' was
+successful. If the 'command' was not successful, the numeric error code will
+be returned. Any output from the 'command' execution will not be put in the
+transcript file.</p>
+
+<p><b>Note:</b> In Nyquist, this function is only defined to work on Unix
+systems [including Linux and <nobr>Mac OS X]</nobr>. <nobr>On
+Windows</nobr> systems, <a href="nil.htm">NIL</a> is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(system "ls") <font color="#008844">; do a directory listing</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/t.htm b/docsrc/xlisp/xlisp-doc/reference/t.htm new file mode 100644 index 0000000..99e3e63 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/t.htm @@ -0,0 +1,71 @@ +<html><head><title>XLISP t</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>t</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>system constant</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt> t</dt>
+</dl>
+
+<h2>Description</h2>
+
+<p>The T system constant is built into XLISP. T represents 'true',
+as oppossed to <nobr><a href="nil.htm">NIL</a> ,</nobr>
+representing 'false'.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(setq myvar T) <font color="#008844">; set MYVAR to True</font>
+(setq myvar 'T) <font color="#008844">; T and 'T both evaluate to T</font>
+(if t (print "this will print") <font color="#008844">; if, then, else</font>
+ (print "this won't print"))
+</pre>
+
+<p><b>Note:</b> Be careful with the T value. It is possible to do a
+<a href="setq.htm">setq</a> on T and set it to other values like
+<a href="nil.htm">NIL</a>. Some operations will still return
+proper T or <a href="nil.htm">NIL</a> values, but the system
+will be in a bad state.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/tagbody.htm b/docsrc/xlisp/xlisp-doc/reference/tagbody.htm new file mode 100644 index 0000000..123167d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/tagbody.htm @@ -0,0 +1,81 @@ +<html><head><title>XLISP tagbody</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>tagbody</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(tagbody [<i>expr</i> ... ])</dt>
+<dd><i>expr</i> - expressions comprising the body of the block which may
+contain <a href="go.htm">go</a>s or tags for
+<a href="go.htm">go</a><br>
+returns - <a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'tagbody' special form is basically a 'block' construct that contains
+a block of code [expressions] to evaluate. After the execution of the
+'tagbody' 'exprs', <a href="nil.htm">NIL</a> is returned. The
+'tagbody' special form allows 'go-to' style branching within the 'block'
+construct via the <a href="go.htm">go</a> special form. To allow
+this, each 'expr' may be a tag or a form. The tag-symbol is the 'label' and
+must exist somewhere within the 'block' that the <a
+href="go.htm">go</a> occurs within.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(tagbody <font color="#008844">; build the 'block'</font>
+ start (print "begin") <font color="#008844">; tag - start</font>
+ (GO end)
+ (print "hello") <font color="#008844">; won't ever be reached</font>
+ end (print "done")) <font color="#008844">; tag - END</font>
+ <font color="#008844">; prints "begin" "done"</font>
+ <font color="#008844">; returns NIL</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-021.htm#tagbody">tagbody</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/tan.htm b/docsrc/xlisp/xlisp-doc/reference/tan.htm new file mode 100644 index 0000000..81fd0de --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/tan.htm @@ -0,0 +1,76 @@ +<html><head><title>XLISP tan</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>tan</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(tan <i>expr</i>)</dt>
+<dd><i>expr</i> - floating point number or expression<br>
+returns - the tangent of the number</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'tan' function calculates the tangent of the 'expr' and returns the
+result. The 'expr' is in radians.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(tan 0.0) <font color="#008844">; returns 0</font>
+(tan 1.0) <font color="#008844">; returns 1.55741</font>
+(tan (/ 3.14159 2)) <font color="#008844">; returns 753696</font>
+(tan 2.0) <font color="#008844">; returns -2.18504</font>
+(tan 3.0) <font color="#008844">; returns -0.142547</font>
+(tan 3.14159) <font color="#008844">; returns -2.65359e-06</font>
+(tan 4.5) <font color="#008844">; returns 4.63733</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp allows for integer numbers, which
+XLISP does not support for 'tan'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-023.htm#tan">tan</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/terpri.htm b/docsrc/xlisp/xlisp-doc/reference/terpri.htm new file mode 100644 index 0000000..2b5cdf2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/terpri.htm @@ -0,0 +1,90 @@ +<html><head><title>XLISP terpri</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>terpri</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c, xlprin.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(terpri [<i>dest</i>])</dt>
+<dd><i>dest</i> - an optional destination, must be a file pointer or
+stream, default is <a href="global-standard-output.htm">*standard-output*</a><br>
+returns - <a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'terpri' function prints a new-line to the specified 'destination'
+This will terminate the current print line for 'destination'.
+<a href="nil.htm">NIL</a> is always returned as the result. The
+'destination' may be a file pointer or a stream. If there is no
+'destination', <a href="global-standard-output.htm">*standard-output*</a> is the
+default.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(terpri) <font color="#008844">; prints #\Newline</font>
+
+(setq f (open "pr" :direction :output)) <font color="#008844">; create a file</font>
+(princ "hi" f) <font color="#008844">; returns "hi"</font>
+(princ 727 f) <font color="#008844">; returns 727</font>
+(princ "ho" f) <font color="#008844">; returns "ho"</font>
+(terpri f) <font color="#008844">; returns NIL</font>
+(close f) <font color="#008844">; file contains hi727ho#\Newline</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp specifies that print operations with a
+'destination' of <a href="nil.htm">NIL</a> will go to
+<a href="global-standard-output.htm">*standard-output*</a>. XLISP does not send the
+output to <a href="global-standard-output.htm">*standard-output*</a> with a
+'destination' of <a href="nil.htm">NIL</a>. Common Lisp also
+specifies that a 'destination' of
+<a href="t.htm"> T </a> will be sent to
+*terminal-io*, which is not defined in XLISP by default. XLISP does not
+allow <a href="t.htm"> T </a> as a valid argument
+for 'destination'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-027.htm#terpri">terpri</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/third.htm b/docsrc/xlisp/xlisp-doc/reference/third.htm new file mode 100644 index 0000000..78fab50 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/third.htm @@ -0,0 +1,81 @@ +<html><head><title>XLISP third</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>third</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlinit.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(third <i>expr</i>)</dt>
+<dl><i>expr</i> - a list or list expression<br>
+returns - the third element of <i>expr</i> or
+<a href="nil.htm">NIL</a></dl>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'third' function returns the third element of a list or list
+expression. If the list is
+<nobr><a href="nil.htm">NIL</a> ,</nobr>
+<a href="nil.htm">NIL</a> is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(third '(1 2 3 4)) <font color="#008844">; returns 3</font>
+(third NIL) <font color="#008844">; returns NIL</font>
+
+(setq kids '(junie vickie cindy chris)) <font color="#008844">; set up variable KIDS</font>
+(first kids) <font color="#008844">; returns JUNIE</font>
+(second kids) <font color="#008844">; returns VICKIE</font>
+(third kids) <font color="#008844">; returns CINDY</font>
+(fourth kids) <font color="#008844">; returns CHRIS</font>
+(rest kids) <font color="#008844">; returns (VICKIE CINDY CHRIS)</font>
+</pre>
+
+<p><b>Note:</b> This function is set to the same code as
+<a href="caaar.htm">caddr</a>.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-016.htm#third">third</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/throw.htm b/docsrc/xlisp/xlisp-doc/reference/throw.htm new file mode 100644 index 0000000..4b12de6 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/throw.htm @@ -0,0 +1,23 @@ +<html><head><title>XLISP throw</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>throw</h1>
+
+<hr>
+
+<p>See <a href="catch.htm">catch</a>.</p>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/top-level.htm b/docsrc/xlisp/xlisp-doc/reference/top-level.htm new file mode 100644 index 0000000..6a0a8e3 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/top-level.htm @@ -0,0 +1,91 @@ +<html><head><title>XLISP top-level</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>top-level</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c, xldbug.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(top-level)</dt>
+<dd>returns - never returns</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'top-level' function aborts to the top level of XLISP. This may be
+from within several levels of the
+<nobr><a href="../manual/xlisp-man-004.htm">break loop</a></nobr>.
+This is valid for
+<a href="break.htm">break</a>s,
+<a href="error.htm">error</a>s and
+<a href="cerror.htm">cerror</a>s [continuable errors]. If 'top-level'
+is evaluated while not in a
+<nobr><a href="../manual/xlisp-man-004.htm">break loop</a> ,</nobr>
+a message is printed:
+
+<pre class="example">
+<font color="#008844">[ back to top level ]</font>
+</pre>
+
+<p>This message does not cause XLISP to go into a
+<nobr><a href="../manual/xlisp-man-004.htm">break loop</a></nobr>.
+The 'top-level' function never actually returns a value.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(top-level) <font color="#008844">; [ back to top level ]</font>
+
+(break "out") <font color="#008844">; break: out (1st)</font>
+(break "twice") <font color="#008844">; break: twice (2nd)</font>
+(top-level) <font color="#008844">; to exit out of the break loop</font>
+</pre>
+
+<p><b>Keyboard:</b> In the IBM PC and MS-DOS versions of XLISP, a 'Ctrl+c'
+key sequence has the same effect as doing a (top-level). On a Macintosh,
+this can be accomplished by a pull-down menu or a 'Command+t'. [I haven't
+tested this with Nyquist.]</p>
+
+<p>See the
+<a href="../manual/xlisp-man-022.htm#top-level">top-level</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/trace.htm b/docsrc/xlisp/xlisp-doc/reference/trace.htm new file mode 100644 index 0000000..f81f621 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/trace.htm @@ -0,0 +1,93 @@ +<html><head><title>XLISP trace</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>trace</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(trace <i>function</i> ... )</dt>
+<dd><i>function</i> - an unquoted function<br>
+returns - the trace list</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'trace' special form allows the tracing of user or system functions.
+'trace' returns a list containing the current set of functions that are
+being traced. The 'function' does not have to be currently defined, it can
+be created as part of the execution. The trace output consists of entry and
+exit information.</p>
+
+<p>At entry and exit of a traced 'function', lines will be printed of the
+form:</p>
+
+<pre class="example">
+Entering: <font color="#008844"><i>function</i></font>, Argument list: <font color="#008844"><i>arg-list</i></font>
+Exiting: <font color="#008844"><i>function</i></font>, Value: <font color="#008844"><i>return-value</i></font>
+</pre>
+
+<p>A list of all currently traced functions can be found in the
+<a href="global-tracelist.htm">*tracelist*</a> system variable.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun foo (x) (print (car x))) <font color="#008844">; define FOO</font>
+(trace 'foo) <font color="#008844">; returns (FOO)</font>
+(trace 'car) <font color="#008844">; returns (CAR FOO)</font>
+
+(foo '(a)) <font color="#008844">; Entering: FOO, Argument list: ((A))</font>
+ <font color="#008844">; Entering: CAR, Argument list: ((A))</font>
+ <font color="#008844">; Exiting: CAR, Value: A</font>
+ <font color="#008844">; A</font>
+ <font color="#008844">; Exiting: FOO, Value: A</font>
+ <font color="#008844">; returns A</font>
+</pre>
+
+<p><b>Common Lisp:</b> The XLISP 'trace' function does not support any
+keyword options, which Common Lisp allows.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-022.htm#trace">trace</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/truncate.htm b/docsrc/xlisp/xlisp-doc/reference/truncate.htm new file mode 100644 index 0000000..421ca7f --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/truncate.htm @@ -0,0 +1,74 @@ +<html><head><title>XLISP truncate</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>truncate</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(truncate <i>expr</i>)</dt>
+<dd><i>expr</i> - integer or floating point number or expression<br>
+returns - the result of truncating <i>expr</i></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'truncate' function takes the 'expr' and truncates it to an integer
+value and returns this result.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(truncate 123.456) <font color="#008844">; returns 123</font>
+(truncate -1.49) <font color="#008844">; returns -1</font>
+(truncate -1.59) <font color="#008844">; returns -1</font>
+(truncate 123) <font color="#008844">; returns 123</font>
+(truncate 123.999) <font color="#008844">; returns 123</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common LISP allows an optional division parameter,
+which XLISP does not support.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-023.htm#truncate">truncate</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/type-of.htm b/docsrc/xlisp/xlisp-doc/reference/type-of.htm new file mode 100644 index 0000000..1e01c24 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/type-of.htm @@ -0,0 +1,103 @@ +<html><head><title>XLISP type-of</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>type-of</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlsys.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(type-of <i>expr</i>)</dt>
+<dd><i>expr</i> - an expression to check<br>
+returns - the type of the expression</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'type-of' function returns the type of the expression.</p>
+
+<ul>
+<li><nobr>SYMBOL - for symbols</nobr></li>
+<li><nobr>OBJECT - for objects</nobr></li>
+<li><nobr>CONS - for conses</nobr></li>
+<li><nobr>SUBR - for built-in functions</nobr></li>
+<li><nobr>FSUBR - for special forms</nobr></li>
+<li><nobr>CLOSURE - for defined functions</nobr></li>
+<li><nobr>STRING - for strings</nobr></li>
+<li><nobr>FIXNUM - for integers</nobr></li>
+<li><nobr>FLONUM - for floating point numbers</nobr></li>
+<li><nobr>CHARACTER - for characters</nobr></li>
+<li><nobr>FILE-STREAM - for file pointers</nobr></li>
+<li><nobr>UNNAMED-STREAM - for unnamed streams</nobr></li>
+<li><nobr>ARRAY - for arrays</nobr></li>
+</ul>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(type-of NIL) <font color="#008844">; returns NIL</font>
+(type-of '#(1 2 3)) <font color="#008844">; returns ARRAY</font>
+(type-of (lambda (x) (print x))) <font color="#008844">; returns CLOSURE</font>
+(type-of '(a b)) <font color="#008844">; returns CONS</font>
+(type-of #'savefun) <font color="#008844">; returns CLOSURE</font>
+(type-of '(a . b)) <font color="#008844">; returns CONS</font>
+(type-of *standard-output*) <font color="#008844">; returns FILE-STREAM</font>
+(type-of 1.2) <font color="#008844">; returns FLONUM</font>
+(type-of #'do) <font color="#008844">; returns FSUBR</font>
+(type-of 1) <font color="#008844">; returns FIXNUM</font>
+(type-of object) <font color="#008844">; returns OBJECT</font>
+(type-of "str") <font color="#008844">; returns STRING</font>
+(type-of #'car) <font color="#008844">; returns SUBR</font>
+(type-of 'a) <font color="#008844">; returns SYMBOL</font>
+(type-of #\a) <font color="#008844">; returns CHARACTER</font>
+(type-of (make-string-input-stream "a")) <font color="#008844">; returns UNNAMED-STREAM</font>
+</pre>
+
+<p><b>Common Lisp:</b> The XLISP and Common Lisp 'type-of' functions are
+basically the same. Differences between the two can occur in what the types
+are called [like CHARACTER in XLISP and STANDARD-CHAR in Common Lisp]. Also,
+Common Lisp can give additional information. For strings, it returns a list
+of the form (SIMPLE-STRING 32) where the number 32 is the string size.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-031.htm#type-of">type-of</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/union.htm b/docsrc/xlisp/xlisp-doc/reference/union.htm new file mode 100644 index 0000000..d728399 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/union.htm @@ -0,0 +1,80 @@ +<html><head><title>XLISP union</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>union</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp function (closure)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xm.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>union</b> <i>list1 list2</i>)</nobr></dt>
+<dd><i>listN</i> - a list of symbols or numbers<br>
+returns - the union of <i>list1</i> and <i>list2</i></dd>
+</dl>
+
+</div></p>
+
+<p>In Nyquist, 'union' is implemented as a Lisp function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">union</font> (a b)
+ (let (result)
+ (dolist (elem a)
+ (if (not (member elem result)) (push elem result)))
+ (dolist (elem b)
+ (if (not (member elem result)) (push elem result)))
+ result))
+</pre>
+
+<h2>Description</h2>
+
+<p>The 'union' function computes the union of two lists. <nobr>The
+result</nobr> is a list containing all elements of both lists, where every
+element appears exactly once.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/unless.htm b/docsrc/xlisp/xlisp-doc/reference/unless.htm new file mode 100644 index 0000000..d54cbd0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/unless.htm @@ -0,0 +1,82 @@ +<html><head><title>XLISP unless</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>unless</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(unless <i>test</i> [<i>expr</i> ... ])</dt>
+<dd><i>test</i> - an expression, <a href="nil.htm">NIL</a> or
+non-<a href="nil.htm">NIL</a><br>
+<i>expr</i> - expressions comprising a body of code<br>
+returns - the value of the last expression or
+<a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'unless' special form executes the 'expr' forms if 'test' evaluates
+to a <a href="nil.htm">NIL</a> value. If 'test' is
+<nobr><a href="nil.htm">NIL</a> ,</nobr> the value of the last
+'expr' is returned as the result. If 'test' is
+<nobr>non-<a href="nil.htm">NIL</a> ,</nobr>
+<a href="nil.htm">NIL</a> is returned with none of 'expr'
+evaluated.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(unless NIL) <font color="#008844">; returns NIL</font>
+(unless T) <font color="#008844">; returns NIL</font>
+
+(unless NIL (print "hi") 'foo) <font color="#008844">; prints "hi" returns FOO</font>
+
+(unless (listp "a")
+ (print "not a list")) <font color="#008844">; prints "not a list"</font>
+ <font color="#008844">; returns "not a list"</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-019.htm#unless">unless</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/untrace.htm b/docsrc/xlisp/xlisp-doc/reference/untrace.htm new file mode 100644 index 0000000..5576b8e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/untrace.htm @@ -0,0 +1,86 @@ +<html><head><title>XLISP untrace</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>untrace</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(untrace function ... )</dt>
+<dd><i>function</i> - a function name<br>
+returns - the trace list</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'untrace' function removes 'function' from the current list of traced
+functions. 'untrace' returns a list containing the current set of functions
+that are being traced. If the 'function' does currently exist or is
+currently be traced, there will be no error reported. If there are no
+functions being traced, a <a href="nil.htm">NIL</a> is
+returned. A list of all currently traced functions can be found in the
+<a href="global-tracelist.htm">*tracelist*</a> system variable.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(defun foo (x) (print (car x))) <font color="#008844">; define FOO</font>
+(trace 'foo) <font color="#008844">; returns (FOO)</font>
+
+(foo '(a)) <font color="#008844">; Entering: FOO, Argument list: ((A))</font>
+ <font color="#008844">; A</font>
+ <font color="#008844">; Exiting: FOO, Value: A</font>
+ <font color="#008844">; returns A</font>
+
+(untrace 'foo) <font color="#008844">; returns NIL</font>
+(untrace 'glip) <font color="#008844">; returns NIL</font>
+
+(foo '(a)) <font color="#008844">; prints A returns A</font>
+</pre>
+
+<p><b>Common Lisp:</b> The XLISP 'untrace' function does not support any
+options, which Common Lisp allows.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-022.htm#untrace">untrace</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/unwind-protect.htm b/docsrc/xlisp/xlisp-doc/reference/unwind-protect.htm new file mode 100644 index 0000000..1f40d74 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/unwind-protect.htm @@ -0,0 +1,137 @@ +<html><head><title>XLISP unwind-protect</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>unwind-protect</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(unwind-protect <i>protect-form clean-up-form</i> ... )</dt>
+<dd><i>protect-form</i> - a form that is to be protected<br>
+<i>clean-up-form</i> - a sequence forms to execute after <i>protect-form</i><br>
+returns - the value of <i>protect-form</i></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p> The 'unwind-protect' special form allows the protecting [trapping] of
+all forms of exit from the 'protect-form'. The exits that are trapped
+include errors, <nobr><a href="throw.htm">throw</a> ,</nobr> <a
+href="return.htm">return</a> and <a
+href="go.htm">go</a>. The 'clean-up-form' will be executed in
+all cases, when there is an exit from 'protect-form' and when the form does
+not have exit. 'unwind-protect' will return the result from the
+'protect-form', not from the 'clean-up-forms'. Errors or exits that occur in
+the 'clean-up-form' are not protected. It is possible to trap these with
+another 'unwind-protect'.</p>
+
+<p><div class="box">
+
+<p><b>Note:</b> 'unwind-protext' will not protect against errors signalled
+by <nobr>built-in</nobr> functions if
+<a href="global-breakenable.htm">*breakenable*</a> is <nobr>not
+<a href="nil.htm">NIL</a></nobr></nobr>.</p>
+
+</div></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(unwind-protect
+ (+ 2 2) <font color="#008844">; protected form</font>
+ (print "an exit")) <font color="#008844">; clean up form</font>
+ <font color="#008844">; prints "an exit"</font>
+ <font color="#008844">; returns 4</font>
+</pre>
+
+<pre class="example">
+(setq *breakenable* nil) <font color="#008844">; to turn off break loop traps</font>
+
+(unwind-protect
+ (+ 1 "2") <font color="#008844">; protected form</font>
+ (print "something happened")) <font color="#008844">; clean up form</font>
+ <font color="#008844">; error: bad argument type - "2"</font>
+ <font color="#008844">; prints "something happened"</font>
+</pre>
+
+<pre class="example">
+(catch 'mytag
+ (unwind-protect
+ (throw 'mytag) <font color="#008844">; protected form</font>
+ (print "an exit"))) <font color="#008844">; clean up form</font>
+ <font color="#008844">; prints "an exit"</font>
+</pre>
+
+<pre class="example">
+(setq *breakenable* nil) <font color="#008844">; to turn off break loop traps</font>
+
+(unwind-protect
+ (throw 'notag) <font color="#008844">; protected form</font>
+ (print "an exit")) <font color="#008844">; clean up form</font>
+ <font color="#008844">; error: no target for THROW</font>
+ <font color="#008844">; prints "an exit"</font>
+</pre>
+
+<pre class="example">
+(prog () (print "start")
+ (unwind-protect
+ (go end) <font color="#008844">; protected form</font>
+ (print "an exit")) <font color="#008844">; clean-up form</font>
+ end (print "end")) <font color="#008844">; prints "start"</font>
+ <font color="#008844">; prints "an exit"</font>
+ <font color="#008844">; prints "end"</font>
+</pre>
+
+<pre class="example">
+(prog () (print "start")
+ (unwind-protect
+ (return "I'm done") <font color="#008844">; protected form</font>
+ (print "but first")) <font color="#008844">; clean-up form</font>
+ (print "won't get here")) <font color="#008844">; prints "start"</font>
+ <font color="#008844">; prints "but first"</font>
+ <font color="#008844">; returns "I'm done"</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-019.htm#unwind-protect">unwind-protect</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/upper-case-p.htm b/docsrc/xlisp/xlisp-doc/reference/upper-case-p.htm new file mode 100644 index 0000000..406f546 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/upper-case-p.htm @@ -0,0 +1,76 @@ +<html><head><title>XLISP upper-case-p</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>upper-case-p</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlstr.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(upper-case-p <i>char</i>)</dt>
+<dd><i>char</i> - a character expression<br>
+returns - <a href="t.htm"> T </a> if the character
+is upper case, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'upper-case-p' predicate function checks if the 'char' expression is
+an upper case character. If 'char' is upper case a
+<a href="t.htm"> T </a> is returned, otherwise a
+<a href="nil.htm">NIL</a> is returned. Upper case characters are
+'A' [<a href="../misc/ascii-table.htm">ASCII</a> decimal <nobr>value
+65]</nobr> through 'Z' [<a href="../misc/ascii-table.htm">ASCII</a>
+decimal <nobr>value 90].</nobr></p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(upper-case-p #\A) <font color="#008844">; returns T</font>
+(upper-case-p #\a) <font color="#008844">; returns NIL</font>
+(upper-case-p #\1) <font color="#008844">; returns NIL</font>
+(upper-case-p #\[) <font color="#008844">; returns NIL</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-026.htm#upper-case-p">upper-case-p</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/vector.htm b/docsrc/xlisp/xlisp-doc/reference/vector.htm new file mode 100644 index 0000000..4ef325e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/vector.htm @@ -0,0 +1,73 @@ +<html><head><title>XLISP vector</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>vector</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlbfun.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(vector [<i>expr</i> ... ])</dt>
+<dd><i>expr</i> - an expression<br>
+returns - the new vector</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'vector' function creates an initialized vector and returns it as the
+result. 'vector' is essentially a fast method to do a one-dimensional <a
+href="make-array.htm">make-array</a> with initial data in the
+vector.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(vector 'a 'b 'c) <font color="#008844">; returns #(A B C)</font>
+(vector '(a b) '(c d)) <font color="#008844">; returns #((A B) (C D))</font>
+(vector) <font color="#008844">; returns #()</font>
+(vector NIL) <font color="#008844">; returns #(NIL)</font>
+(vector 'a () 4 "s") <font color="#008844">; returns #(A NIL 4 "s")</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-015.htm#vector">vector</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/when.htm b/docsrc/xlisp/xlisp-doc/reference/when.htm new file mode 100644 index 0000000..5129f6e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/when.htm @@ -0,0 +1,82 @@ +<html><head><title>XLISP when</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>when</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>special form (fsubr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlcont.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(when <i>test</i> [<i>expr</i> ... ])</dt>
+<dd><i>test</i> - an expression, <a href="nil.htm">NIL</a>
+or non-<a href="nil.htm">NIL</a><br>
+<i>expr</i> - expressions comprising a body of code<br>
+returns - the value of the last expression or
+<a href="nil.htm">NIL</a></dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'when' macro executes the 'expr' forms if 'test' evaluates to a
+non-<a href="nil.htm">NIL</a> value. If 'test' is
+<nobr>non-<a href="nil.htm">NIL</a> ,</nobr> the value of the
+last 'expr' is returned as the result. If 'test' is
+<nobr><a href="nil.htm">NIL</a> ,</nobr>
+<a href="nil.htm">NIL</a> is returned with none of 'expr'
+evaluated.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(when NIL) <font color="#008844">; returns NIL</font>
+(when T) <font color="#008844">; returns T</font>
+
+(when T (print "hi") 'foo) <font color="#008844">; prints "hi" returns FOO</font>
+
+(when (listp '(a))
+ (print "a list")) <font color="#008844">; prints "a list"</font>
+ <font color="#008844">; returns "a list"</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-019.htm#when">when</a>
+special form in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/while.htm b/docsrc/xlisp/xlisp-doc/reference/while.htm new file mode 100644 index 0000000..2a2f8da --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/while.htm @@ -0,0 +1,81 @@ +<html><head><title>XLISP while</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>while</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>Lisp macro (closure)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>misc.lsp</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>while</b> <i>condition body</i>)</nobr></dt>
+<dd><i>condition</i> - test expression for terminating the 'while' loop<br>
+<dd><i>body</i> - Lisp expressions to be executed inside the loop<br>
+returns - returns <a href="nil.htm">NIL</a> or a value defined by
+(<a href="return.htm">return</a> <i>expr</i>) inside <i>body</i></dd>
+</dl>
+
+</div></p>
+
+<p>In Nyquist, 'while' is implemented as a Lisp macro:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">while</font> (condition &rest body)
+ `(prog () loop (if ,condition () (return)) ,@body (go loop)))
+</pre>
+
+<h2>Description</h2>
+
+<p>The 'while' macro implements a conventional 'while' loop. <nobr>If
+the</nobr> 'condition' evaluates to true, the expressions in the in the
+'body' are evaluated, then the 'condition' is tested again. <nobr>If
+the</nobr> 'condition' evaluates to false, the 'while' loop terminates. The
+'while' macro returns <a href="nil.htm">NIL</a> unless a <nobr>(<a
+href="return.htm">return</a> <i>expr</i>)</nobr> is evaluated in the 'body',
+in which case the value of 'expr' is returned.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/write-byte.htm b/docsrc/xlisp/xlisp-doc/reference/write-byte.htm new file mode 100644 index 0000000..6ceab26 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/write-byte.htm @@ -0,0 +1,92 @@ +<html><head><title>XLISP write-byte</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>write-byte</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(write-byte <i>expr</i> [<i>dest</i>])</dt>
+<dd><i>expr</i> - an integer expression<br>
+<i>dest</i> - an optional destination, must be a file pointer or stream,
+default is <a href="global-standard-output.htm">*standard-output*</a><br>
+returns - the byte as an integer</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'write-byte' function writes the 'expr' as a single byte to the
+specified 'destination'. Only the 'expr' byte is written. The 'expr' must be
+an integer expression. The 'expr' is returned as the result. The
+'destination' may be a file pointer or a stream. If there is no
+'destination', <a href="global-standard-output.htm">*standard-output*</a> is the
+default.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(write-byte 67) <font color="#008844">; prints C returns 67</font>
+
+(setq fp (open "t" :direction :output)) <font color="#008844">; create file</font>
+(write-byte 65 fp) <font color="#008844">; returns 65</font>
+(write-byte 66 fp) <font color="#008844">; returns 66</font>
+(write-byte 10 fp) <font color="#008844">; returns 10</font>
+(close fp) <font color="#008844">; returns NIL</font>
+
+(read (open "t" :direction :input)) <font color="#008844">; returns AB</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp specifies that print operations with a
+'destination' of <a href="nil.htm">NIL</a> will go to
+<a href="global-standard-output.htm">*standard-output*</a>. XLISP does not send the
+output to <a href="global-standard-output.htm">*standard-output*</a> with a
+'destination' of <a href="nil.htm">NIL</a>. Common Lisp also
+specifies that a 'destination' of
+<a href="t.htm"> T </a> will be sent to
+*terminal-io*, which is not defined in XLISP by default. XLISP does not
+allow <a href="t.htm"> T </a> as a valid argument
+for 'destination'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-029.htm#write-byte">write-byte</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/write-char.htm b/docsrc/xlisp/xlisp-doc/reference/write-char.htm new file mode 100644 index 0000000..d4075cd --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/write-char.htm @@ -0,0 +1,92 @@ +<html><head><title>XLISP write-char</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>write-char</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(write-char <i>char-expr</i> [<i>dest</i>])</dt>
+<dd><i>char-expr</i> - a character expression<br>
+<i>dest</i> - an optional destination, must be a file pointer or stream,
+default is <a href="global-standard-output.htm">*standard-output*</a><br>
+returns - the character</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'write-char' function writes the 'char-expr' to the specified
+'destination'. Only the 'char-expr' is written. The 'char-expr' must be a
+character expression. The 'char-expr' is returned as the result. The
+'destination' may be a file pointer or a stream. If there is no
+'destination', <a href="global-standard-output.htm">*standard-output*</a> is the
+default.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(write-char #\C) <font color="#008844">; prints C</font>
+
+(setq fp (open "t" :direction :output)) <font color="#008844">; create file</font>
+(write-char #\A fp) <font color="#008844">; returns #\A</font>
+(write-char #\B fp) <font color="#008844">; returns #\B</font>
+(write-char #\Newline fp) <font color="#008844">; returns #\Newline</font>
+(close fp) <font color="#008844">; returns NIL</font>
+
+(read (open "t" :direction :input)) <font color="#008844">; returns AB</font>
+</pre>
+
+<p><b>Common Lisp:</b> Common Lisp specifies that print operations with a
+'destination' of <a href="nil.htm">NIL</a> will go to
+<a href="global-standard-output.htm">*standard-output*</a>. XLISP does not send the
+output to <a href="global-standard-output.htm">*standard-output*</a> with a
+'destination' of <a href="nil.htm">NIL</a>. Common Lisp also
+specifies that a 'destination' of
+<a href="t.htm"> T </a> will be sent to
+*terminal-io*, which is not defined in XLISP by default. XLISP does not
+allow <a href="t.htm"> T </a> as a valid argument
+for 'destination'.</p>
+
+<p>See the
+<a href="../manual/xlisp-man-029.htm#write-char">write-char</a>
+function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/write-float.htm b/docsrc/xlisp/xlisp-doc/reference/write-float.htm new file mode 100644 index 0000000..f5bce92 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/write-float.htm @@ -0,0 +1,80 @@ +<html><head><title>XLISP write-float</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>write-float</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(write-float <i>float</i> [<i>stream</i> [<i>length</i>]])</dt>
+<dd><i>float</i> - the floating point number to write<br>
+<i>stream</i> - the output stream [default is standard output]<br>
+<i>length</i> - the length of the float in bytes [default is 4,
+legal values are -4, -8, 4, and 8]<br>
+returns - the float</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The '<nobr>write-float</nobr>' function writes a binary floating point
+number to an output stream, created by the
+<nobr><a href="open-binary.htm">open-binary</a></nobr> function.</p>
+
+<p><b>Note:</b> Integers and floats are assumed to be
+<nobr>big-endian</nobr> [<nobr>high-order</nobr> byte first] and signed,
+regardless of the platform. <nobr>To read</nobr> <nobr>little-endian</nobr>
+format, use a negative number for the length, e.g. '-4' indicates a
+<nobr>4-bytes</nobr>, <nobr>low-order</nobr> byte first. The file should be
+opened in binary mode.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p>See also <nobr><a href="read-int.htm">read-int</a></nobr>,
+<nobr><a href="write-int.htm">write-int</a></nobr>,
+<nobr><a href="read-float.htm">read-float</a></nobr>,
+<nobr><a href="bigendianp.htm">bigendianp</a></nobr>,
+<nobr><a href="open-binary.htm">open-binary</a></nobr>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/write-int.htm b/docsrc/xlisp/xlisp-doc/reference/write-int.htm new file mode 100644 index 0000000..131f9ae --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/write-int.htm @@ -0,0 +1,79 @@ +<html><head><title>XLISP write-int</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>write-int</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlfio.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(write-int <i>integer</i> [<i>stream</i> [<i>length</i>]])</dt>
+<dd><i>integer</i> - the integer to write<br>
+<i>stream</i> - the output stream [default is standard output]<br>
+<i>length</i> - the length of the integer in bytes [default is 4]<br>
+returns - the integer</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The '<nobr>write-int</nobr>' function writes an integer to a binary output
+stream, created by the
+<nobr><a href="open-binary.htm">open-binary</a></nobr> function.</p>
+
+<p><b>Note:</b> Integers and floats are assumed to be
+<nobr>big-endian</nobr> [<nobr>high-order</nobr> byte first] and signed,
+regardless of the platform. <nobr>To read</nobr> <nobr>little-endian</nobr>
+format, use a negative number for the length, e.g. '-4' indicates a
+<nobr>4-bytes</nobr>, <nobr>low-order</nobr> byte first. The file should be
+opened in binary mode.</p>
+
+<h2>Examples</h2>
+
+<pre class="example">
+
+</pre>
+
+<p>See also <nobr><a href="read-int.htm">read-int</a></nobr>,
+<nobr><a href="read-float.htm">read-float</a></nobr>,
+<nobr><a href="write-float.htm">write-float</a></nobr>,
+<nobr><a href="bigendianp.htm">bigendianp</a></nobr>,
+<nobr><a href="open-binary.htm">open-binary</a></nobr>.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/reference/zerop.htm b/docsrc/xlisp/xlisp-doc/reference/zerop.htm new file mode 100644 index 0000000..014101b --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/reference/zerop.htm @@ -0,0 +1,81 @@ +<html><head><title>XLISP zerop</title>
+
+<link rel="stylesheet" type="text/css" href="reference.css">
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>zerop</h1>
+
+<hr>
+
+<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
+<tr valign="top">
+ <td><nobr>Type:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>predicate function (subr)</nobr></td>
+</tr>
+<tr valign="top">
+ <td><nobr>Source:</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>xlmath.c</nobr></td>
+</tr>
+</tbody></table></p>
+
+<h2>Syntax</h2>
+
+<dl>
+<dt>(zerop <i>expr</i>)</dt>
+<dd><i>expr</i> - the numeric expression to check<br>
+returns - <a href="t.htm"> T </a> if the number is
+zero, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+<h2>Description</h2>
+
+<p>The 'zerop' predicate function checks to see if the number 'expr' is
+zero. <a href="t.htm"> T </a> is returned if the
+number is zero, <a href="nil.htm">NIL</a> is returned otherwise.
+An error is generated if the 'expr' is not a numeric expression:</p>
+
+<pre class="example">
+<font color="#AA0000">error: bad argument type</font>
+</pre>
+
+<h2>Examples</h2>
+
+<pre class="example">
+(zerop 0) <font color="#008844">; returns T</font>
+(zerop 0.0) <font color="#008844">; returns T</font>
+(zerop 99999.9) <font color="#008844">; returns NIL</font>
+(zerop -0.000000000002) <font color="#008844">; returns NIL</font>
+
+(zerop 'a) <font color="#008844">; error: bad argument type</font>
+(setq a 0) <font color="#008844">; set value of A to 0</font>
+(zerop a) <font color="#008844">; returns T</font>
+</pre>
+
+<p>See the
+<a href="../manual/xlisp-man-018.htm#zerop">zerop</a>
+predicate function in the <nobr>XLISP 2.0</nobr> manual.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/start.htm b/docsrc/xlisp/xlisp-doc/start.htm new file mode 100644 index 0000000..c8154c9 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/start.htm @@ -0,0 +1,86 @@ +<html><head>
+
+<title>XLisp</title></head>
+
+<body>
+
+Nyquist / XLISP 2.0 -
+<a href="manual/contents.htm">Contents</a> |
+<a href="tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples/examples.htm">Examples</a> |
+<a href="reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Nyquist / XLISP 2.0</h1>
+
+<hr>
+
+<ul>
+<li><nobr><a href="misc/preface.htm">Preface</a> - what's this all about</nobr></li>
+</ul>
+
+<ul>
+<li><nobr><a href="manual/contents.htm">Contents</a></nobr></li>
+<ul>
+<li><nobr><a href="manual/xlisp.htm">XLISP 2.0 Manual</a> - by David Betz</nobr></li>
+<li><nobr><a href="manual/objects.htm">XLISP Object System</a> - by David Betz</nobr></li>
+<li><nobr><a href="reference/reference-index.htm">Language Reference</a> - based on documents by David Betz and Tim I Mikkelsen</nobr></li>
+<br>
+<li><nobr><a href="manual/xlisp-man-033.htm">Nyquist Functions</a> - added by Nyquist to the XLISP interpreter</nobr></li>
+<li><nobr><a href="xlisp-plus/xlisp-plus-index.htm">XLISP Plus Functions</a> - written in XLISP code</nobr></li>
+</ul>
+</ul>
+
+<ul>
+<li><nobr><a href="tutorials/tutorials.htm">Tutorials</a></nobr></li>
+<ul>
+<li><nobr><a href="tutorials/lisp-hints.htm">Lisp Hints</a> - XLISP basics</nobr></li>
+<li><nobr><a href="tutorials/xlisp-objects.htm">XLISP Objects Primer</a> - by Tim I Mikkelsen</nobr></li>
+</ul>
+</ul>
+
+<ul>
+<li><nobr><a href="examples/examples.htm">Examples</a> - XLISP examples</nobr></li>
+</ul>
+
+<ul>
+<li><nobr>Miscellaneous</nobr></li>
+<ul>
+<li><nobr><a href="misc/ascii-table.htm">ASCII Table</a> - XLISP characters</nobr></li>
+<li><nobr><a href="misc/c-printf.htm">ANSI C 'printf' Format</a> - for
+<a href="reference/global-float-format.htm">*float-format*</a> and
+<a href="reference/global-integer-format.htm">*integer-format*</a></nobr></li>
+<li><nobr><a href="misc/links.htm">Lisp Links</a> - books and documents available for free in the internet</nobr></li>
+</ul>
+</ul>
+
+<ul>
+<li><nobr>Internals</nobr></li>
+<ul>
+<li><nobr><a href="internals/xlisp-internals.html">XLISP Internals</a></nobr></li>
+</ul>
+</ul>
+
+<hr>
+
+<p>If you find bugs in these documents please write to:</p>
+
+<ul>
+<li><a href="mailto:edgar-rft@web.de">edgar-rft@web.de</a></li>
+</ul>
+
+<p>If you send me email please write the words XLISP or NYQUIST as big as
+possible into the subject line in case you get catched by the spam filter.
+I usually sort out my emails by hand but often do not have the time to
+open them all during sorting.</p>
+
+<hr>
+
+Nyquist / XLISP 2.0 -
+<a href="manual/contents.htm">Contents</a> |
+<a href="tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples/examples.htm">Examples</a> |
+<a href="reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/tutorials/binary-io.htm b/docsrc/xlisp/xlisp-doc/tutorials/binary-io.htm new file mode 100644 index 0000000..73fce58 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/tutorials/binary-io.htm @@ -0,0 +1,79 @@ +<html><head>
+
+<title>Binary File I/O</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Binary File I/O</h1>
+
+<hr>
+
+
+
+<pre class="example">
+(defun hexdump (filename &key (start 0) end)
+ (if (and (integerp start) (not (minusp start)))
+ (error "not a non-negative integer" start))
+ (or (null end)
+ (and (integerp end) (not (minusp end)))
+ (error "not a non-negative integer" end))
+ (let ((file (open-binary filename)))
+</pre>
+
+
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/tutorials/environment.htm b/docsrc/xlisp/xlisp-doc/tutorials/environment.htm new file mode 100644 index 0000000..2ce9a99 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/tutorials/environment.htm @@ -0,0 +1,530 @@ +<html><head>
+
+<title>Environment</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Environment</h1>
+
+<hr>
+
+<a name="global-and-lexical-binding"></a>
+
+<hr>
+
+<h2>Global and Lexical Binding</h2>
+
+<hr>
+
+<p>From the XLISP perspective, there are two kinds of bindings:</p>
+
+<ol>
+
+<li><p>Global bindings are bindings to symbols in the *obarray*.</p></li>
+
+<li><p>Lexical bindings are bindings in a local association list</p></li>
+
+</ol>
+
+<p>There is a third kind of binding, 'dynamical binding', used by progv.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lexical-scope"></a>
+
+<hr>
+
+<h2>Lexical Scope</h2>
+
+<hr>
+
+<p>Have you ever wondered why this doesn't work:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">print-x</font> ()
+ (print x)) <font color="#008844">; unbound variable X</font>
+
+(let ((x 'hello))
+ (print-x))
+<font color="#AA0000">error: unbound variable - X</font>
+</pre>
+
+<p>The answer is twofold:</p>
+
+<ol>
+
+<li><p>The '<nobr>print-x</nobr>' function is defined at the global
+<nobr>top-level</nobr>, where no lexical environment exists.</p></li>
+
+<li><p>The '<nobr>print-x</nobr>' function is called inside a
+<a href="../reference/let.htm">let</a> form, where a lexical variable
+binding for 'x' exists, but '<nobr>print-x</nobr>' is evaluated at the
+global <nobr>top-level</nobr>, where it was defined, so
+'<nobr>print-x</nobr>' cannot see the lexical
+<a href="../reference/let.htm">let</a> binding <nobr>of 'x'</nobr> and
+signals an '<nobr>unbound variable</nobr>' error.</p></li>
+
+</ol>
+
+<p>Here is a version that seems to work:</p>
+
+<pre class="example">
+(let ((x 'hello))
+
+ (defun <font color="#0000CC">print-x</font> ()
+ (print x))
+
+ (print-x))
+HELLO
+</pre>
+
+<ol>
+
+<li><p>The '<nobr>print-x</nobr>' function is defined inside a
+<a href="../reference/let.htm">let</a> form.</p></li>
+
+<li><p>The '<nobr>print-x</nobr>' function is called inside the same
+<a href="../reference/let.htm">let</a> form as where it was defined, so
+'<nobr>print-x</nobr>' prints the lexical
+<a href="../reference/let.htm">let</a> binding
+<nobr>of 'x'</nobr>.</p></li>
+
+</ol>
+
+<p>But here again a version that does not behave as wanted:</p>
+
+<pre class="example">
+(let ((x 'lexical))
+ (defun <font color="#0000CC">print-x</font> ()
+ (print x)))
+
+(let ((x 'hello))
+ (print-x))
+LEXICAL
+</pre>
+
+<ol>
+
+<li><p>The '<nobr>print-x</nobr>' function is defined inside a
+<a href="../reference/let.htm">let</a> form.</p></li>
+
+<li><p>The '<nobr>print-x</nobr>' function is called inside a different
+<a href="../reference/let.htm">let</a> form as where it was defined, so
+'<nobr>print-x</nobr>' prints the lexical
+<a href="../reference/let.htm">let</a> binding <nobr>of 'x'</nobr> from
+the place where it was defined.</p></li>
+
+</ol>
+
+<p>Somehow it seems to be important where a function was defined.</p>
+
+<a name="closures"></a>
+
+<hr>
+
+<h2>Closures</h2>
+
+<hr>
+
+<p>Here a Lisp function, defined inside a
+<a href="../reference/let.htm">let</a> form:</p>
+
+<pre class="example">
+(let ((a 'A) (b 'B) (c 'C))
+
+ (defun <font color="#0000CC">print-abc</font> ()
+ (format t <font color="#880000">";; a = ~s, b = ~s, c = ~s~%"</font> a b c))
+
+ ) <font color="#008844">; end of LET</font>
+</pre>
+
+<p>Now '<nobr>print-abc</nobr>' is called outside the
+<a href="../reference/let.htm">let</a> form:</p>
+
+<pre class="example">
+> (print-abc)
+;; a = A, b = B, c = C
+NIL
+</pre>
+
+<p>The lexical <a href="../reference/let.htm">let</a> variables 'a', 'b',
+and 'c' have become a permanent part of the '<nobr>print-abc</nobr>'
+function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lisp-objects"></a>
+
+<hr>
+
+<h2>Lisp Objects</h2>
+
+<hr>
+
+<p>The following examples are based on <nobr>Chapter 13</nobr> of 'Paradigms
+of Artificial Intelligence Programming' by Peter Norvig. <nobr>The
+code</nobr> has been ported from <nobr>Common Lisp</nobr> to XLISP, all
+examples have been tested with <nobr>Nyquist 3.03</nobr> in <nobr>December
+2010</nobr>.</p>
+
+<p>The function '<nobr>new-account</nobr>' creates account objects, which
+are implemented as closures encapsulating three variables 'name', 'balance',
+and '<nobr>interest-rate</nobr>'. <nobr> An account</nobr> object also
+encapsulates functions to handle five messages ':withdraw', ':deposit',
+':balance', ':name', and ':interest', to which the object can respond:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">new-account</font> (name &optional (balance 0.0) (interest-rate 0.06))
+ #'(lambda (message)
+ (case message
+ (:withdraw #'(lambda (amount)
+ (if (<= amount balance)
+ (setq balance (- balance amount))
+ 'insufficient-funds)))
+ (:deposit #'(lambda (amount)
+ (setq balance (+ balance amount))))
+ (:balance #'(lambda () balance))
+ (:name #'(lambda () name))
+ (:interest #'(lambda ()
+ (setq balance (+ balance (* interest-rate balance))))))))
+</pre>
+
+<p>An account object can only do one thing, receive a message and return the
+appropriate function to execute that message. This function is called the
+'method' that implements the message.</p>
+
+<p>The function '<nobr>get-method</nobr>' finds the method that implements a
+message for a given object:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">get-method</font> (object message)
+ (funcall object message))
+</pre>
+
+<p>The function '<nobr>send-message</nobr>' gets the method and applies it
+to a list of arguments:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">send-message</font> (object message &rest args)
+ (apply (get-method object message) args))
+</pre>
+
+<p>Here are some examples how it works:</p>
+
+<pre class="example">
+> (setq a1 (new-account "My Name" 1000.0))
+#<Closure...>
+
+> (send-message a1 :name)
+"My Name"
+
+> (send-message a1 :balance)
+1000.0
+
+> (send-message a1 :withdraw 500.0)
+500
+
+> (send-message a1 :deposit 123.45)
+623.45
+
+> (send-message a1 :balance)
+623.45
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="generic-functions"></a>
+
+<hr>
+
+<h2>Generic Functions</h2>
+
+<hr>
+
+<p>The '<nobr>send-message</nobr>' syntax is awkward, as it is different
+from normal Lisp function calling syntax, and it doesn't fit in with the
+other Lisp tools.</p>
+
+<p>For example if we want <nobr>to say</nobr>:</p>
+
+<pre class="example">
+(mapcar :balance accounts)
+</pre>
+
+<p>with '<nobr>send-message</nobr>' we would have to write:</p>
+
+<pre class="example">
+(mapcar #'(lambda (acc)
+ (send-message acc :balance))
+ accounts)
+</pre>
+
+<p>We could fix this problem by defining a generic function 'withdraw' like
+this:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">withdraw</font> (object &rest args)
+ (apply (get-method object :withdraw) args))
+</pre>
+
+<p>Now we can write:</p>
+
+<pre class="example">
+(withdraw account x)
+</pre>
+
+<p>instead of:</p>
+
+<pre class="example">
+(send-message account :withdraw x)
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="classes"></a>
+
+<hr>
+
+<h2>Classes</h2>
+
+<hr>
+
+<p>The macro '<nobr>define-class</nobr>' defines a class with its associated
+message handling methods. <nobr>It also</nobr> defines a generic function
+for each message. Finally, it allows the programmer to make a distinction
+between instance variables, associated with each object, and class
+variables, associated with a class and shared by all members of the
+class.</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">define-class</font> (class ivars cvars &rest methods)
+ `(let ,cvars
+ (mapcar #'ensure-generic-function ',(mapcar #'first methods))
+ (defun ,class ,ivars
+ #'(lambda (message)
+ (case message
+ ,@(mapcar #'make-clause methods))))))
+</pre>
+
+<p>The '<nobr>make-clause</nobr>' function translates a message from
+'<nobr>define-class</nobr>' into a
+<a href="../reference/case.htm">case</a> clause.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">make-clause</font> (clause)
+ `(,(car clause) #'(lambda ,(cadr clause) ,@(cddr clause))))
+</pre>
+
+<p>The '<nobr>ensure-generic-function</nobr>' function defines a dispatch
+function for a message, unless it already has been defined <nobr>as
+one</nobr>:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">ensure-generic-function</font> (message)
+ (unless (generic-function-p message)
+ (let ((fn #'(lambda (object &rest args)
+ (apply (get-method object message) args))))
+ (setf (symbol-function message) fn)
+ (putprop message fn 'generic-function))))
+</pre>
+
+<p>The '<nobr>generic-function-p</nobr>' function tests if a function has
+been defined as a generic function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">generic-function-p</font> (name)
+ (and (fboundp name)
+ (eq (get name 'generic-function) (symbol-function name))))
+</pre>
+
+<p>Now we can define the 'account' class with '<nobr>define-class</nobr>'.
+We make '<nobr>interest-rate</nobr>' a class variable, shared by all
+accounts:</p>
+
+<pre class="example">
+(define-class <font color="#0066CC">account</font> (name &optional (balance 0.0)) ((interest-rate 0.06))
+ (withdraw (amount)
+ (if (<= amount balance)
+ (setq balance (- balance amount))
+ 'insufficient-funds))
+ (deposit (amount)
+ (setq balance (+ balance amount)))
+ (balance ()
+ balance)
+ (name ()
+ name)
+ (interest ()
+ (setq balance (+ balance (* interest-rate balance)))))
+</pre>
+
+<p>Macroexpansion:</p>
+
+<pre class="example">
+(let ((interest-rate 0.06))
+ (mapcar (function ensure-generic-function)
+ (quote (withdraw deposit balance name interest)))
+ (defun account (name &optional (balance 0))
+ (function (lambda (message)
+ (case message
+ (withdraw (function (lambda (amount)
+ (if (<= amount balance)
+ (setq balance (- balance amount))
+ (quote insufficient-funds)))))
+ (deposit (function (lambda (amount)
+ (setq balance (+ balance amount)))))
+ (balance (function (lambda nil balance)))
+ (name (function (lambda nil name)))
+ (interest (function (lambda nil
+ (setq balance (+ balance (* interest-rate balance)))))))))))
+</pre>
+
+<p>Here is how it works:</p>
+
+<pre class="example">
+> (setq a2 (account "my-name" 2000.0)
+#<Closure...>
+
+> (balance a2)
+2000
+
+> (deposit a2 42.0)
+2042
+
+> (interest a2)
+2164.52
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="delegation"></a>
+
+<hr>
+
+<h2>Delegation</h2>
+
+<hr>
+
+<p>Here is a '<nobr>password-account</nobr>' class with two
+message clauses:</p>
+
+<pre class="example">
+(define-class <font color="#0066CC">password-account</font> (password acc) ()
+ (change-password (pass new-pass)
+ (if (equal pass password)
+ (setq password new-pass)
+ 'wrong-password))
+ (t (pass &rest args)
+ (if (equal pass password)
+ (if args
+ (apply message (cons acc args))
+ (funcall message acc))
+ 'wrong-password)))
+</pre>
+
+<p>The definition of '<nobr>password-account</nobr>' depends on some
+internal details of '<nobr>define-class</nobr>'. <nobr>It uses</nobr> 't' as
+a <nobr>catch-all</nobr> clause to <a href="../reference/case.htm">case</a>
+and uses the dispatch variable 'message'. Usually it is not a good idea to
+rely on details of other code, so this will be changed below.</p>
+
+<p>Here is how '<nobr>password-account</nobr>' works:</p>
+
+<pre class="example">
+> (setq a3 (password-account "secret" a2))
+#<Closure...>
+
+> (balance a3 "secret")
+2164.52
+
+> (withdraw a3 "guess" 2000.0)
+WRONG-PASSWORD
+
+> (withdraw a3 "secret" 2000.0)
+164.52
+</pre>
+
+<p>Here is a '<nobr>limited-account</nobr>' class, where only a limited
+amount of money can be withdrawn at any time:</p>
+
+<pre class="example">
+(define-class <font color="#0066CC">limited-account</font> (limit acc) ()
+ (withdraw (amount)
+ (if (<= amount limit)
+ (withdraw acc amount)
+ 'over-limit))
+ (t (&rest args)
+ (if args
+ (apply message (cons acc args))
+ (funcall message acc))))
+</pre>
+
+<p>The 'withdraw' message is redefined to check if the account limit is
+exceeded, while the 't' clause passes all other messages unchanged:</p>
+
+<pre class="example">
+> (setq a4 (password-account "pass"
+ (limited-account 100.0
+ (account "limited" 500.0)))
+#<Closure...>
+
+
+
+
+
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/tutorials/file-io.htm b/docsrc/xlisp/xlisp-doc/tutorials/file-io.htm new file mode 100644 index 0000000..19f6862 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/tutorials/file-io.htm @@ -0,0 +1,349 @@ +<html><head><title>XLISP: An Object-oriented Lisp</title></head> + +<style type="text/css"> +.example { + color: #000000; + background-color: #F5F5F5; + padding: 8px; + border: #808080; + border-style: solid; + border-width: 1px; + width:auto; +} +.button { + color: #000000; + background-color: #F5F5F5; + padding-top: 1px; + padding-bottom: 1px; + padding-left: 4px; + padding-right: 8px; + border: #808080; + border-style: solid; + border-width: 1px; + white-space: pre; +} +.box { + color: #000000; + padding-top: 4px; + padding-bottom: 4px; + padding-left: 16px; + padding-right: 16px; + border: #808080; + border-style: solid; + border-width: 1px; +} +</style> + +<body> + +<a href="../start.htm">Nyquist / XLISP 2.0</a> - +<a href="../manual/contents.htm">Contents</a> | +<a href="tutorials.htm">Tutorials</a> | +<a href="../examples/examples.htm">Examples</a> | +<a href="../reference/reference-index.htm">Reference</a> + +<hr> + +<h1>File I/O</h1> + +<hr> + +<ol> +<li><nobr><a href="#1">File I/O Examples</a> - from the XLISP 2.0 manual, by David Betz</nobr></li> +<ul> +<li><nobr><a href="#1-1">Input from a File</a></nobr></li> +<li><nobr><a href="#1-2">Output to a File</a></nobr></li> +<li><nobr><a href="#1-3">A Slightly More Complicated File Example</a></nobr></li> +<li><nobr><a href="#1-4">Closing Files via 'unwind-protect'</a></nobr></li> +</ul> +<li><nobr><a href="#2">Files and Directories</a></nobr></li> +<ul> +<li><nobr><a href="#2-1">setdir</a></nobr></li> +<li><nobr><a href="#2-2">listdir</a></nobr></li> +</ul> +<li><nobr><a href="#3">Testing Existence</a></nobr></li> +<ul> +<li><nobr><a href="#directory-exists-p">directory-exists-p</a></nobr></li> +<li><nobr><a href="#file-exists-p">file-exists-p</a></nobr></li> +<li><nobr><a href="#file-or-directory-exists-p">file-or-directory-exists-p</a></nobr></li> +</ul> +<li><nobr><a href="#4">Text File I/O</a></nobr></li> +<ul> +<li><nobr><a href="#">Reading from a Text File</a></nobr></li> +<li><nobr><a href="#">Writing to a Text File</a></nobr></li> +<li><nobr><a href="#">Appending to a Text File</a></nobr></li> +</ul> +<li><nobr><a href="#5">Binary File I/O</a></nobr></li> +</ol> + +<a name="1"></a> + +<hr> + +<h2>1 File I/O Examples</h2> + +<a name="1-1"></a> + +<hr> + +<h2>1.1 Input from a File</h2> + +<hr> + +<p>The basics of file i/o with XLISP:</p> + +<ul> + +<li><p>To open a file for input, use the +<a href="../reference/open.htm">open</a> function with the keyword argument +:direction set to :input.</p></li> + +<li><p>To open a file for +output, use the <a href="../reference/open.htm">open</a> function with the +keyword argument :direction set to :output.</p></li> + +<li><p>To close a file, use the <a href="../reference/close.htm">close</a> +function.</p></li> + +</ul> + +<p>The <a href="../reference/open.htm">open</a> function takes a single +required argument which is the name of the file to be opened. This name can +be in the form of a string or a symbol. <nobr>The +<a href="../reference/open.htm">open</a></nobr> function returns an object +of type '<nobr>file-stream</nobr>' if it succeeds in opening the specified +file. <nobr>It returns</nobr> the value +<a href="../reference/nil.htm">NIL</a> if it fails.</p> + +<p>In order to manipulate the file, it is necessary to save the value +returned by the <a href="../reference/open.htm">open</a> function. +This is usually done by assigning it to a variable with the +<a href="../reference/setq.htm">setq</a> special form or by binding it using +<a href="../reference/let.htm">let</a> or +<a href="../reference/let-star.htm">let*</a>. Here is an example:</a> + +<pre class="example"> +(setq file-stream (open "init.lsp" :direction :input)) +</pre> + +<p>Evaluating this expression will result in the file 'init.lsp' being +opened. The file object that will be returned by the +<a href="../reference/open.htm">open</a> function will be +assigned to the variable '<nobr>file-stream</nobr>'.</p> + +<p>It is now possible to use the file for input. <nobr>To read</nobr> an +expression from the file, just supply the value of the +'<nobr>file-stream</nobr>' variable as the optional 'stream' argument to the +<a href="../reference/read.htm">read</a> function:</p> + +<pre class="example"> +(read file-stream) +</pre> + +<p>Evaluating this expression will result in reading the first expression +from the file 'init.lsp'. The expression will be returned as the +result of the <a href="../reference/read.htm">read</a> function. +More expressions can be read from the file using further calls to the +<a href="../reference/read.htm">read</a> function. When there +are no more expressions to read, the +<a href="../reference/read.htm">read</a> function will return +<a href="../reference/nil.htm">NIL</a> [or whatever value was +supplied as the second argument to +<a href="../reference/read.htm">read</a>].</p> + +<p>Once you are done reading from the file, you should close it. To close +the file, use the <a href="../reference/close.htm">close</a> +function:</p> + +<pre class="example"> +(close file-stream) +</pre> + +<p>Evaluating this expression will cause the file to be closed.</p> + +<p> <a href="#top">Back to Top</a></p> + +<a name="1-2"></a> + +<hr> + +<h2>1.2 Output to a File</h2> + +<hr> + +<p>Writing to a file is pretty much the same as reading from one. You need +to open the file first. This time you should use the +<a href="../reference/open.htm">open</a> function to indicate +that you will do output to the file:</p> + +<pre class="example"> +(setq file-stream (open "test.dat" :direction :output)) +</pre> + +<p>Evaluating this expression will open the file 'test.dat' for output. +<nobr>If the</nobr> file already exists, its current contents will be +discarded. <nobr>If it</nobr> doesn't already exist, it will be created. +<nobr>In any</nobr> case, a '<nobr>file-stream</nobr>' object will be +returned by the <a href="../reference/open.htm">open</a> function. This file +object will be assigned to the '<nobr>file-stream</nobr>' variable.</p> + +<p>It is now possible to write to this file by supplying the value of the +'<nobr>file-stream</nobr>' variable as the optional 'stream' parameter in +the <a href="../reference/print.htm">print</a> function.</p> + +<pre class="example"> +(print "Hello there" file-stream) +</pre> + +<p>Evaluating this expression will result in the string <nobr>"Hello +there"</nobr> being written to the <nobr>file +"test.dat"</nobr>. More data can be written to the file using the +same technique.</p> + +<p>Once you are done writing to the file, you should +<nobr><a href="../reference/close.htm">close</a> it</nobr>. Closing an +output file is just like closing an input file:</p> + +<pre class="example"> +(close file-stream) +</pre> + +<p>Evaluating this expression will +<a href="../reference/close.htm">close</a> the output file and +make it permanent.</p> + +<p> <a href="#top">Back to Top</a></p> + +<a name="1-3"></a> + +<hr> + +<h2>1.3 A Slightly More Complicated File Example</h2> + +<hr> + +<p>This example shows how to +<a href="../reference/open.htm">open</a> a file, +<a href="../reference/read.htm">read</a> each Lisp expression +from the file and <a href="../reference/print.htm">print</a> it. +It demonstrates the use of files and the use of the optional 'stream' +argument to the <a href="../reference/read.htm">read</a> +function.</p> + +<pre class="example"> +(do* ((file-stream (open "test.dat" :direction :input)) + (expression (read file-stream) (read file-stream))) + ((null expression) nil) + (print expression)) +</pre> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="1-4"></a> + +<hr> + +<h2>1.4 Closing Files via 'unwind-protect'</h2> + +<hr> + +<p>To make sure that the file gets closed in the end, the +<nobr>file i/o</nobr> functions can be wrapped by an <nobr><a +href="../reference/unwind-protect.htm">unwind-protect</a> form:</nobr></p> + +<pre class="example"> +(let ((file-stream (open "test.dat" :direction :input))) + (unwind-protect + <font color="#008844">;; protect-form</font> + (do ((expression (read file-stream) (read file-stream))) + ((null expression) nil) + (print expression)) + <font color="#008844">;; clean-up form</font> + (when file-stream (close file-stream)))) +</pre> + +<p>This pattern can be found in many <nobr>file i/o</nobr> functions:</p> + +<pre class="example"> +(let ((<font color="#AA0000">file-stream</font> (open <font color="#0000CC">filename</font> :direction <font color="#0000CC">direction</font>))) + (unwind-protect + (progn + <font color="#008844">;; do something with the file-stream</font> + ) + (when <font color="#AA0000">file-stream</font> (close <font color="#AA0000">file-stream</font>)))) +</pre> + +<p><nobr> <a href="#top">Back to top</a></nobr></p> + +<a name="3"></a> + +<hr> + +<h2>3 Testing Existence</h2> + +<hr> + +<p><div class="box"> + +<p>Note that these function are meant to prevent accidents during basic +<nobr>file i/o</nobr>, they may not be able to test if a file or directory +physically exists or is a link to a different place.</p> + +</div></p> + +<a name="directory-exists-p"></a> + +<p>The Nyquist <a href="../reference/listdir.htm">listdir</a> function can +be used to test if a directory exists:</p> + +<pre class="example"> +(defun <font color="#0000CC">directory-exists-p</font> (string) + (and (listdir string) t)) +</pre> + +<a name="file-exists-p"></a> + +<p>Testing if a file exists is a bit more tricky because on Unix [including +Linux and <nobr>Mac OS X]</nobr> a directory is a special kind of file, so +the XLISP <a href="../reference/open.htm">open</a> function also can open +directories. That's why we first must make sure that the filename string is +not the name of an existing directory:</p> + +<pre class="example"> +(defun <font color="#0000CC">file-exists-p</font> (string) + (or (stringp string) (error <font color="#880000">"not a string"</font> string)) + (unless (listdir string) + (let ((file-stream (open string))) + (when file-stream + (close file-stream) + string)))) +</pre> + +<a name="file-or-directory-exists-p"></a> + +<p>Before creating a new file it's always a good idea to check +if a file or directory with the same name already exists:</p> + +<pre class="example"> +(defun <font color="#0000CC">file-or-directory-exists-p</font> (string) + (or (stringp string) (error <font color="#880000">"not a string"</font> string)) + (when (or (listdir string) + (let ((file-stream (open string))) + (when file-stream + (close file-stream) + t))) + string)) +</pre> + + +<p><nobr> <a href="#top">Back to Top</a></nobr></p> + +<hr> + +<a href="../start.htm">Nyquist / XLISP 2.0</a> - +<a href="../manual/contents.htm">Contents</a> | +<a href="tutorials.htm">Tutorials</a> | +<a href="../examples/examples.htm">Examples</a> | +<a href="../reference/reference-index.htm">Reference</a> + +</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/tutorials/lisp-faq.htm b/docsrc/xlisp/xlisp-doc/tutorials/lisp-faq.htm new file mode 100644 index 0000000..a00e621 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/tutorials/lisp-faq.htm @@ -0,0 +1,199 @@ +<html><head>
+
+<title>Lisp FAQ</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Lisp FAQ</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#and-or-with-apply-funcall">Why do #'and and #'or not work with apply and funcall?</a></nobr></li>
+<li><nobr><a href="#more-faqs">Where can I find more Lisp FAQs in the Internet?</a></nobr></li>
+</ol>
+
+<a name="and-or-with-apply-funcall"></a>
+
+<hr>
+
+<h2>Why do #'and and #'or not work with apply and funcall?</h2>
+
+<hr>
+
+<p><nobr>From
+<a href="http://www.cs.cmu.edu/Groups/AI/html/faqs/lang/lisp/part3/faq-doc-3.html"
+>http://www.cs.cmu.edu/Groups/AI/html/faqs/lang/lisp/part3/faq-doc-3.html</a></nobr></p>
+
+<p>The short answer is that <a href="../reference/and.htm">and</a> and
+<a href="../reference/or.htm">or</a> are special operators, not functions,
+while <a href="../reference/apply.htm">apply</a> and
+<a href="../reference/funcall.htm">funcall</a> can only be used to invoke
+functions, not macros and special operators.</p>
+
+<p>The reason why <a href="../reference/and.htm">and</a> and <a
+href="../reference/or.htm">or</a> are special operators is because they
+implement control structure in addition to computing a boolean value. They
+evaluate their subforms sequentially from left to right, and stop evaluating
+subforms as soon as the result can be determined. This is referred to as
+'<nobr>short circuiting</nobr>'. <a href="../reference/apply.htm">apply</a>
+and <a href="../reference/funcall.htm">funcall</a>, however, are ordinary
+functions. Therefore, their arguments are evaluated before they are called.
+Thus, were <a href="../reference/apply.htm">apply</a> able to be used with
+#'<a href="../reference/and.htm">and</a> and
+<a href="../reference/or.htm">or</a>, the <nobr>short-circuiting</nobr>
+would be defeated.</p>
+
+<p>Perhaps you don't really care about the <nobr>short-circuiting</nobr>,
+and simply want the functional, boolean interpretation. While this may be a
+reasonable interpretation of trying to
+<a href="../reference/apply.htm">apply</a>
+<a href="../reference/and.htm">and</a>
+<nobr>or <a href="../reference/or.htm">or</a></nobr>, it doesn't generalize
+to other macros well, so there's no obvious way to have the Lisp system 'do
+the right thing' when trying to apply macros. <nobr>The only</nobr> function
+associated with a macro is its expander function. This function accepts and
+returns and form, so it cannot be used to compute the value.</p>
+
+<p>The <nobr>Common Lisp</nobr> functions EVERY, SOME and IDENTITY can be
+used to get the functionality you intend when trying to
+<a href="../reference/apply.htm">apply</a>
+#'<a href="../reference/and.htm">and</a>
+<nobr>and #'<a href="../reference/or.htm">or</a></nobr>:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>(apply #'and <font color="#0000CC">list</font>)</code></nobr></td>
+ <td><nobr> → </nobr></td>
+ <td class="button"><nobr><code>(every #'identity <font color="#0000CC">list</font>)</code></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>(apply #'or <font color="#0000CC">list</font>)</code></nobr></td>
+ <td><nobr> → </nobr></td>
+ <td class="button"><nobr><code>(some #'identity <font color="#0000CC">list</font>)</code></nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>Defining <a href="../reference/and.htm">and</a> and
+<a href="../reference/or.htm">or</a> as functions using
+<a href="../reference/cons.htm">cons</a> and
+<a href="../reference/eval.htm">eval</a>:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">and-fn</font> (&rest args)
+ (eval (cons 'and args)))
+
+(defun <font color="#0000CC">or-fn</font> (&rest args)
+ (eval (cons 'or args)))
+</pre>
+
+<p>Defining <a href="../reference/and.htm">and</a> and
+<a href="../reference/or.htm">or</a> as functions using
+<a href="../reference/dolist.htm">dolist</a>:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">and-fn</font> (&rest args)
+ (dolist (x args t)
+ (and (not x) (return nil))))
+
+(defun <font color="#0000CC">or-fn</font> (&rest args)
+ (dolist (x args nil)
+ (and x (return t))))
+</pre>
+
+
+<pre class="example">
+(defun <font color="#0000CC">apply*</font> (function args)
+ (if (eq (type-of function) 'fsubr)
+ (eval (cons function args))
+ (apply function args)))
+
+
+</pre>
+
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="more-faqs"></a>
+
+<hr>
+
+<h2>Where can I find more Lisp FAQs in the Internet?</h2>
+
+<hr>
+
+<ul>
+<li><nobr><a href="http://www.cs.cmu.edu/Groups/AI/html/faqs/lang/lisp/top.html"
+>http://www.cs.cmu.edu/Groups/AI/html/faqs/lang/lisp/top.html</a>
+- comp.lang.lisp FAQ from the CMU AI Repository</nobr></li>
+</ul>
+
+
+
+
+
+
+
+
+
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/tutorials/lisp-hints.htm b/docsrc/xlisp/xlisp-doc/tutorials/lisp-hints.htm new file mode 100644 index 0000000..13e0e84 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/tutorials/lisp-hints.htm @@ -0,0 +1,2055 @@ +<html><head>
+
+<title>Lisp Hints</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Lisp Hints</h1>
+
+<hr>
+
+<p>The original document was written by <nobr>Geoffrey J. Gordon</nobr>
+[<nobr>ggordon@cs.cmu.edu</nobr>], <nobr>Friday, February 5, 1993</nobr>,
+<nobr>for <a href="http://www.cons.org/cmucl/">CMUCL</a></nobr>.</p>
+
+<p>Modified by:</p>
+
+<ul>
+
+<li><nobr>Bruno Haible for <a href="http://www.gnu.org/software/clisp/">CLISP</a>.</nobr></li>
+
+<li><nobr>Tom Almy in 1995 for <a href="http://almy.us/xlisp.html">XLISP Plus</a></nobr>.</li>
+
+<li><nobr>Edgar M. Franke [edgar-rft@web.de] in 2010 for
+<a href="http://www.cs.cmu.edu/~music/music.software.html">Nyquist</a></nobr>.</li>
+
+</ul>
+
+<p>All examples tested with <nobr>Nyquist 3.03</nobr> in <nobr>November
+2010</nobr>.</p>
+
+<hr>
+
+<h2>Table of Contents</h2>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#1">Symbols</a></nobr></li>
+<li><nobr><a href="#2">Numbers</a></nobr></li>
+<li><nobr><a href="#3">Conses</a></nobr></li>
+<li><nobr><a href="#4">Lists</a></nobr></li>
+<li><nobr><a href="#5">Functions</a></nobr></li>
+<li><nobr><a href="#6">Printing</a></nobr></li>
+<li><nobr><a href="#7">Forms and the Top-Level Loop</a></nobr></li>
+<li><nobr><a href="#8">Special Forms</a></nobr></li>
+<li><nobr><a href="#9">Binding</a></nobr></li>
+<li><nobr><a href="#10">Dynamic Scoping</a></nobr></li>
+<li><nobr><a href="#11">Arrays</a></nobr></li>
+<li><nobr><a href="#12">Strings</a></nobr></li>
+<li><nobr><a href="#13">Setf</a></nobr></li>
+<li><nobr><a href="#14">Booleans and Conditionals</a></nobr></li>
+<li><nobr><a href="#15">Iteration</a></nobr></li>
+<li><nobr><a href="#16">Non-local Exits</a></nobr></li>
+<li><nobr><a href="#17">Funcall, Apply, and Mapcar</a></nobr></li>
+<li><nobr><a href="#18">Lambda</a></nobr></li>
+<li><nobr><a href="#19">Sorting</a></nobr></li>
+<li><nobr><a href="#20">Equality</a></nobr></li>
+<li><nobr><a href="#21">Some Useful List Functions</a></nobr></li>
+</ol>
+
+<a name="1"></a>
+
+<hr>
+
+<h2>1 Symbols</h2>
+
+<hr>
+
+<p>A symbol is just a sequence of characters. There are restrictions on what
+you can include in a symbol and what the first character can be, but as long
+as you stick to letters, digits, and hyphens, you'll be safe. [Except that
+if you use only digits and possibly an initial hyphen, Lisp will think you
+typed an integer rather than a symbol.] Some examples of symbols:</p>
+
+<pre class="example">
+a
+b
+c1
+foo
+bar
+baaz-quux-garply
+</pre>
+
+<p>Some things you can do with symbols follow. Things after a <nobr>'>'
+prompt</nobr> are what you type to the Lisp interpreter, while other things
+are what the Lisp interpreter prints back to you. The <nobr>semicolon
+';'</nobr> is Lisp's comment character. Everything from a ';' to the end of
+line is ignored.</p>
+
+<pre class="example">
+> (setq a 5) <font color="#008844">; store a number as the value of a symbol</font>
+5
+
+> a <font color="#008844">; take the value of a symbol</font>
+5
+
+> (let ((a 6)) <font color="#008844">; bind the value of a symbol temporarily to 6</font>
+ a)
+6
+
+> a <font color="#008844">; the value returns to 5 once the let is finished</font>
+5
+
+> (+ a 6) <font color="#008844">; use the value of a symbol as an argument to a function</font>
+11
+
+> b <font color="#008844">; try to take the value of a symbol which has no value</font>
+<font color="#AA0000">error: unbound variable - b</font>
+</pre>
+
+<p>There are two special symbols,
+<a href="../reference/t.htm"> T </a>
+<nobr>and <a href="../reference/nil.htm">NIL</a></nobr>. <nobr>The
+value</nobr> of <a href="../reference/t.htm"> T </a> is defined
+always to <nobr>be <a href="../reference/t.htm"> T </a></nobr>,
+and the value of <a href="../reference/nil.htm">NIL</a></nobr> is defined
+always to <nobr>be <a href="../reference/nil.htm">NIL</a></nobr></nobr>.
+Lisp uses <a href="../reference/t.htm"> T </a> and
+<a href="../reference/nil.htm">NIL</a></nobr> to represent true and false.
+<nobr>An example</nobr> of this use is in the if statement, described more
+fully later:</p>
+
+<pre class="example">
+> (if t 5 6)
+5
+
+> (if nil 5 6)
+6
+
+> (if 4 5 6)
+5
+</pre>
+
+<p>The last example is odd but correct.
+<nobr><a href="../reference/nil.htm">NIL</a> means</nobr> false, and
+anything else means true. Unless we have a reason to do otherwise, we use
+<a href="../reference/t.htm"> T </a> to mean true, just for the
+sake of clarity.</p>
+
+<p>Symbols like <a href="../reference/t.htm"> T </a> and
+<a href="../reference/nil.htm">NIL</a> are called
+'<nobr>self-evaluating</nobr>' symbols, because they evaluate to themselves.
+There is a whole class of <nobr>self-evaluating</nobr> symbols called
+'keywords'. Any symbol whose name starts with a colon is a keyword. [See
+below for some uses for keywords.] Some examples:</p>
+
+<pre class="example">
+> :this-is-a-keyword
+:THIS-IS-A-KEYWORD
+
+> :so-is-this
+:SO-IS-THIS
+
+> :me-too
+:ME-TOO
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="2"></a>
+
+<hr>
+
+<h2>2 Numbers</h2>
+
+<hr>
+
+<p>An integer number [FIXNUM] is a sequence of digits optionally preceded by
+a plus <nobr>sign '+'</nobr> or a minus <nobr>sign '-'</nobr>. <nobr>A
+floating</nobr> point number [FLONUM] looks like an integer, except that it
+has a decimal point and optionally can be written in scientific notation.
+Here are some numbers:</p>
+
+<pre class="example">
+5
+17
+-34
++6
+3.1415
+1.722e-15
+</pre>
+
+<p>The standard arithmetic functions are all available:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr valign="top">
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>+</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><a href="../reference/addition.htm">addition</a></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>-</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><a href="../reference/subtraction.htm">subtraction</a></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>*</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><a href="../reference/multiplication.htm">multiplication</a></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>/</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><a href="../reference/division.htm">division</a></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>truncate</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><a href="../reference/truncate.htm">truncate</a> a float to an integer</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>rem</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><a href="../reference/rem.htm">remainder</a> of a division</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>sin</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><a href="../reference/sin.htm">sine</a></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>cos</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><a href="../reference/cos.htm">cosine</a></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>tan</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><a href="../reference/tan.htm">tangent</a></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>sqrt</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr><a href="../reference/sqrt.htm">square root</a></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>exp</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>natural <a href="../reference/exp.htm">exponent</a></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>expt</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>math <a href="../reference/expt.htm">exponent</a></nobr></td>
+</tr>
+</tbody></table></p>
+
+
+<p><nobr><a href="../reference/addition.htm"> + </a> [addition]</nobr>,
+<nobr><a href="../reference/subtraction.htm"> - </a> [subtraction]</nobr>,
+<nobr><a href="../reference/multiplication.htm"> * </a> [multiplication]</nobr>,
+and <nobr><a href="../reference/division.htm"> / </a> [division]</nobr>
+accept any number of arguments and return a number according to type
+contagion. This means that as long as only integer numbers are given as
+arguments the result will always be an integer number, but as soon as at
+least one of the arguments is a floating number then the result will be a
+floating point number. Here are some examples:</p>
+
+<pre class="example">
+> (/ 3 2) <font color="#008844">; integer division causes rounding error</font>
+1
+
+> (/ 3 2.0) <font color="#008844">; the 2.0 forces floating point computation</font>
+1.5
+
+> (exp 1) <font color="#008844">; e</font>
+2.71828
+
+> (exp 3) <font color="#008844">; e * e * e</font>
+20.0855
+
+> (expt 3 4.2) <font color="#008844">; exponent with a base other than e</font>
+100.904
+
+> (+ 5 6 7 (* 8 9 10)) <font color="#008844">; the functions + - * / accept multiple arguments</font>
+738
+</pre>
+
+<p>In Nyquist the valid range of integer numbers is limited by the size of a
+C 'long' value on the machine on which Nyquist is running.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="3"></a>
+
+<hr>
+
+<h2>3 Conses</h2>
+
+<hr>
+
+<p>A <a href="../reference/cons.htm">cons</a> is just a
+<nobr>two-field</nobr> record. <nobr>The fields</nobr> are called
+<a href="../reference/car.htm">car</a> and
+<a href="../reference/cdr.htm">cdr</a>, for historical reasons.
+<nobr>On the</nobr> first machine where Lisp was implemented, there
+were two assembly language instructions CAR and CDR which stood for
+'contents of address register' and 'contents of decrement register'.
+Conses were implemented using these two registers.</p>
+
+<p>Conses are created by the <a href="../reference/cons.htm">cons</a>
+function:</p>
+
+<pre class="example">
+> (cons 4 5) <font color="#008844">; Allocate a cons. Set the car to 4 and the cdr to 5</font>
+(4 . 5)
+
+> (cons (cons 4 5) 6)
+((4 . 5) . 6)
+
+> (car (cons 4 5))
+4
+
+> (cdr (cons 4 5))
+5
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="4"></a>
+
+<hr>
+
+<h2>4 Lists</h2>
+
+<hr>
+
+<p>You can build many structures out of conses. Perhaps the simplest is a
+linked list. <nobr>The <a href="../reference/car.htm">car</a></nobr>
+<nobr>[the <a href="../reference/first.htm">first</a></nobr> element] of
+each cons points to one of the elements of the list, and the
+<a href="../reference/cdr.htm">cdr</a> <nobr>[the
+<a href="../reference/rest.htm">rest</a></nobr> of the elements] points
+either to another cons or to <a href="../reference/nil.htm">NIL</a>.
+<nobr>You can</nobr> create such a linked list with the
+<a href="../reference/list.htm">list</a> function:</p>
+
+<pre class="example">
+> (list 4 5 6)
+(4 5 6)
+</pre>
+
+<p>Notice that Lisp prints linked lists a special way. <nobr>It omits</nobr>
+some of the periods and parentheses. The rule is that if the
+<a href="../reference/cdr.htm">cdr</a> of a
+<a href="../reference/cons.htm">cons</a> is
+<a href="../reference/nil.htm">NIL</a>, Lisp doesn't bother to print the
+period or the <a href="../reference/nil.htm">NIL</a>, and if the
+<a href="../reference/cdr.htm">cdr</a> of
+<nobr><a href="../reference/cons.htm">cons</a> A</nobr> is
+<nobr><a href="../reference/cons.htm">cons</a> B</nobr>, then Lisp doesn't
+bother to print the period for
+<nobr><a href="../reference/cons.htm">cons</a> A</nobr> or the parentheses
+for <nobr><a href="../reference/cons.htm">cons</a> B. So:</nobr></p>
+
+<pre class="example">
+> (cons 4 nil)
+(4) <font color="#008844">; (4 . nil)</font>
+
+> (cons 4 (cons 5 6))
+(4 5 . 6) <font color="#008844">; (4 . (5 . 6))</font>
+
+> (cons 4 (cons 5 (cons 6 nil)))
+(4 5 6) <font color="#008844">; (4 . (5 . (6 . nil)))</font>
+</pre>
+
+<p>The last example is exactly equivalent to the call:</p>
+
+<pre class="example">
+(list 4 5 6)
+</pre>
+
+<p>Note that <a href="../reference/nil.htm">NIL</a> now means the list with
+no elements. <nobr>The <a href="../reference/cdr.htm">cdr</a></nobr> of
+<nobr>(a b)</nobr>, a list with <nobr>2 elements</nobr>, <nobr>is
+(b)</nobr>, a list with 1 element, and the
+<a href="../reference/cdr.htm">cdr</a> of (b), a list with <nobr>1
+element</nobr>, <nobr>is <a href="../reference/nil.htm">NIL</a></nobr>,
+which therefore must be a list with no elements.</p>
+
+<p><div class="box">
+
+<p>The <a href="../reference/car.htm">car</a> and
+<a href="../reference/cdr.htm">cdr</a> of
+<a href="../reference/nil.htm">NIL</a> are defined to
+<nobr>be <a href="../reference/nil.htm">NIL</a></nobr>.</p>
+
+</div></p>
+
+<p>If you store your list in a variable, you can make it act like a
+stack:</p>
+
+<pre class="example">
+> (setq a nil)
+NIL <font color="#008844">; A = ()</font>
+
+> (push 4 a)
+(4) <font color="#008844">; A = (4)</font>
+
+> (push 5 a)
+(5 4) <font color="#008844">; A = (5 4)</font>
+
+> (pop a)
+5 <font color="#008844">; A = (4)</font>
+
+> (pop a)
+4 <font color="#008844">; A = ()</font>
+
+> (pop a)
+NIL <font color="#008844">; A = ()</font>
+</pre>
+
+<p>See <a href="../reference/pop.htm">pop</a>,
+<a href="../reference/push.htm">push</a>,
+<a href="../reference/setq.htm">setq</a>.</p>
+
+<a name="list-accessors"></a>
+
+<p><b>List Accessors</b></p>
+
+<p>There are several different approaches to name the accessor
+functions for elements of conses and lists. <nobr>The 'traditional'</nobr>
+Lisp still uses function names like
+<a href="../reference/car.htm">car</a> and
+<a href="../reference/cdr.htm">cdr</a> while the 'modern' Lisp uses more
+descriptive names like <a href="../reference/first.htm">first</a> and <a
+href="../reference/rest.htm">rest</a>. This leads to the situation that in
+most Lisps today the list accessor functions are available under different
+names for the same functions:</p>
+
+<p><div class="box">
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td align="right"><nobr>modern</nobr></td>
+ <td><nobr> — </nobr></td>
+ <td align="left"><nobr>traditional</nobr></td>
+ <td></td>
+ <td>equivalent to</td>
+ <td><nobr><code> </code></nobr></td>
+ <td>(1 2 3 4 5 6 7 8)</td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td align="right"><nobr><a href="../reference/first.htm">first</a></nobr></td>
+ <td><nobr> — </nobr></td>
+ <td align="left"><nobr><a href="../reference/car.htm">car</a></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td>(<a href="../reference/nth.htm">nth</a> 0 ... )</td>
+ <td><nobr><code> </code>→ </nobr></td>
+ <td>1</td>
+</tr>
+<tr>
+ <td align="right"><nobr><a href="../reference/second.htm">second</a></nobr></td>
+ <td><nobr> — </nobr></td>
+ <td align="left"><nobr><a href="../reference/caar.htm">cadr</a></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td>(<a href="../reference/nth.htm">nth</a> 1 ... )</td>
+ <td><nobr><code> </code>→ </nobr></td>
+ <td>2</td>
+</tr>
+<tr>
+ <td align="right"><nobr><a href="../reference/third.htm">third</a></nobr></td>
+ <td><nobr> — </nobr></td>
+ <td align="left"><nobr><a href="../reference/caaar.htm">caddr</a></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td>(<a href="../reference/nth.htm">nth</a> 2 ... )</td>
+ <td><nobr><code> </code>→ </nobr></td>
+ <td>3</td>
+</tr>
+<tr>
+ <td align="right"><nobr><a href="../reference/fourth.htm">fourth</a></nobr></td>
+ <td><nobr> — </nobr></td>
+ <td align="left"><nobr><a href="../reference/caaaar.htm">cadddr</a></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td>(<a href="../reference/nth.htm">nth</a> 3 ... )</td>
+ <td><nobr><code> </code>→ </nobr></td>
+ <td>4</td>
+</tr>
+<tr>
+ <td colspan="3"></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td>(<a href="../reference/nth.htm">nth</a> 4 ... )</td>
+ <td><nobr><code> </code>→ </nobr></td>
+ <td>5</td>
+</tr>
+<tr>
+ <td colspan="3"></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td> ...</td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td colspan="4"></td>
+ <td>(<a href="../reference/nthcdr.htm">nthcdr</a> 0 ... )</td>
+ <td><nobr><code> </code>→ </nobr></td>
+ <td>(1 2 3 4 5 6 7 8)</td>
+</tr>
+<tr>
+ <td align="right"><nobr><a href="../reference/rest.htm">rest</a></nobr></td>
+ <td><nobr> — </nobr></td>
+ <td align="left"><nobr><a href="../reference/cdr.htm">cdr</a></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td>(<a href="../reference/nthcdr.htm">nthcdr</a> 1 ... )</td>
+ <td><nobr><code> </code>→ </nobr></td>
+ <td>(2 3 4 5 6 7 8)</td>
+</tr>
+<tr>
+ <td colspan="2"></td>
+ <td align="left"><nobr><a href="../reference/caar.htm">cddr</a></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td>(<a href="../reference/nthcdr.htm">nthcdr</a> 2 ... )</td>
+ <td><nobr><code> </code>→ </nobr></td>
+ <td>(3 4 5 6 7 8)</td>
+</tr>
+<tr>
+ <td colspan="2"></td>
+ <td align="left"><nobr><a href="../reference/cdddr.htm">cdddr</a></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td>(<a href="../reference/nthcdr.htm">nthcdr</a> 3 ... )</td>
+ <td><nobr><code> </code>→ </nobr></td>
+ <td>(4 5 6 7 8)</td>
+</tr>
+<tr>
+ <td colspan="2"></td>
+ <td align="left"><nobr><a href="../reference/cddddr.htm">cddddr</a></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td>(<a href="../reference/nthcdr.htm">nthcdr</a> 4 ... )</td>
+ <td><nobr><code> </code>→ </nobr></td>
+ <td>(5 6 7 8)</td>
+</tr>
+<tr>
+ <td colspan="4"></td>
+ <td>(<a href="../reference/nthcdr.htm">nthcdr</a> 5 ... )</td>
+ <td><nobr><code> </code>→ </nobr></td>
+ <td>(6 7 8)</td>
+</tr>
+<tr>
+ <td colspan="3"></nobr></td>
+ <td><nobr><code> </code></nobr></td>
+ <td> ...</td>
+</tr>
+<tr>
+ <td align="right"><nobr><a href="../reference/last.htm">last</a></nobr></td>
+ <td colspan="4"></td>
+ <td><nobr><code> </code>→ </nobr></td>
+ <td>(8)</td>
+</tr>
+</tbody></table></p>
+
+</div></p>
+
+<p>The traditional <nobr>c..r-functions</nobr> are available in even more
+variations, see <a href="../reference/car.htm">car</a>,
+<a href="../reference/cdr.htm">cdr</a>,
+<nobr><a href="../reference/cddr.htm">cadr, cddr</a></nobr>,
+<nobr><a href="../reference/caaar.htm">caaar...caddr</a></nobr>,
+<nobr><a href="../reference/cdddr.htm">cdaar...cdddr</a></nobr>,
+<nobr><a href="../reference/caaaar.htm">caaaar...cadddr</a></nobr>,
+<nobr>and <a href="../reference/cddddr.htm">cdaaar...cddddr</a></nobr>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="5"></a>
+
+<hr>
+
+<h2>5 Functions</h2>
+
+<hr>
+
+<p>You saw one example of a function above. Here are some more:</p>
+
+<pre class="example">
+> (+ 3 4 5 6) <font color="#008844">; this function takes any number of arguments</font>
+18
+
+> (+ (+ 3 4) (+ (+ 4 5) 6)) <font color="#008844">; isn't prefix notation fun?</font>
+22
+
+> (defun foo (x y) <font color="#008844">; defining a function</font>
+ (+ x y 5))
+FOO
+
+> (foo 5 0) <font color="#008844">; calling a function</font>
+10
+
+> (defun fact (x) <font color="#008844">; a recursive function</font>
+ (if (> x 0)
+ (* x (fact (- x 1)))
+ 1))
+FACT
+
+> (fact 5)
+120
+
+> (defun a (x)
+ (if (= x 0)
+ t
+ (b (- x)))) <font color="#008844">; mutually recursive functions</font>
+A
+
+> (defun b (x)
+ (if (> x 0)
+ (a (- x 1))
+ (a (+ x 1))))
+B
+
+> (a 5)
+T
+
+> (defun bar (x) <font color="#008844">; A function with multiple statements</font>
+ (setq x (* x 3)) <font color="#008844">; in its body. It will return the value</font>
+ (setq x (/ x 2)) <font color="#008844">; returned by its final statement</font>
+ (+ x 4))
+BAR
+
+> (bar 6)
+13
+</pre>
+
+<p>See <a href="../reference/addition.htm"> + </a>,
+<a href="../reference/subtraction.htm"> − </a>,
+<a href="../reference/multiplication.htm"> * </a>,
+<a href="../reference/division.htm"> / </a>,
+<a href="../reference/number-equal.htm"> = </a>,
+<a href="../reference/number-greaterp.htm"> > </a>,
+<a href="../reference/defun.htm">defun</a>,
+<a href="../reference/if.htm"> if </a>,
+<a href="../reference/setq.htm">setq</a>. When we defined 'foo', we
+gave it two arguments, 'x' <nobr>and 'y'</nobr>. Now when we call 'foo', we
+are required to provide exactly two arguments. The first will become the
+value of 'x' for the duration of the call to 'foo', and the second will
+become the value of 'y' for the duration of the call. <nobr>In Lisp</nobr>,
+most variables are lexically scoped. <nobr>That is</nobr>, if 'foo' calls
+'bar' and 'bar' tries to reference 'x', then 'bar' will not get 'foo's value
+<nobr>for x</nobr>.</p>
+
+<p><div class="box">
+
+<p>The process of assigning a symbol a value for the duration of some
+lexical scope is called 'binding'.</p>
+
+</div></p>
+
+<p>You can specify optional arguments for your functions. Any argument
+after the symbol
+<a href="../reference/lambda-keyword-optional.htm">&optional</a> is
+optional:</p>
+
+<pre class="example">
+> (defun bar (x &optional y)
+ (if y
+ x
+ 0))
+BAR
+
+> (defun baaz (&optional (x 3) (z 10))
+ (+ x z))
+BAAZ
+
+> (bar 5)
+0
+
+> (bar 5 t)
+5
+
+> (baaz 5)
+15
+
+> (baaz 5 6)
+11
+
+> (baaz)
+13
+</pre>
+
+<p>See <a href="../reference/addition.htm"> + </a>,
+<a href="../reference/defun.htm">defun</a>,
+<a href="../reference/if.htm"> if </a>.
+<nobr>It is</nobr> legal to call the function 'bar' with either one or two
+arguments. <nobr>If it</nobr> is called with one argument, 'x' will be bound
+to the value of that argument and 'y' will be bound <nobr>to
+<a href="../reference/nil.htm">NIL</a></nobr>. <nobr>If it</nobr> is called
+with two arguments, 'x' and 'y' will be bound to the values of the first and
+second argument, respectively.</p>
+
+<p>The function 'baaz' has two optional arguments. <nobr>It specifies</nobr> a
+default value for each of them. <nobr>If the</nobr> caller specifies only
+one argument, 'z' will be bound <nobr>to 10</nobr> instead of <nobr>to
+<a href="../reference/nil.htm">NIL</a></nobr>, and if the caller
+specifies no arguments, 'x' will be bound <nobr>to 3</nobr> and <nobr>'z' to
+10</nobr>.</p>
+
+<p>You can make your function accept any number of arguments by ending its
+argument list with an
+<a href="../reference/lambda-keyword-rest.htm">&rest</a> parameter.
+Lisp will collect all arguments not otherwise accounted for into a list and
+bind the <a href="../reference/lambda-keyword-rest.htm">&rest</a>
+parameter to that <nobr>list. So:</nobr></p>
+
+<pre class="example">
+> (defun foo (x &rest y)
+ y)
+FOO
+
+> (foo 3)
+NIL
+
+> (foo 4 5 6)
+(5 6)
+</pre>
+
+<p>See <a href="../reference/defun.htm">defun</a>. Finally, you can give
+your function another kind of optional argument called a
+<a href="../reference/lambda-keyword-key.htm">&key</a> 'keyword'
+argument. <nobr>The caller</nobr> can give these arguments in any order,
+because they're labelled with keywords:</p>
+
+<pre class="example">
+> (defun foo (&key x y)
+ (cons x y))
+FOO
+
+> (foo :x 5 :y 3)
+(5 . 3)
+
+> (foo :y 3 :x 5)
+(5 . 3)
+
+> (foo :y 3)
+(NIL . 3)
+
+> (foo)
+(NIL)
+</pre>
+
+<p>See <a href="../reference/defun.htm">defun</a>.
+<nobr>An <a href="../reference/lambda-keyword-key.htm">&key</a></nobr>
+parameter can have a default <nobr>value too:</nobr></p>
+
+<pre class="example">
+> (defun foo (&key (x 5))
+ x)
+FOO
+
+> (foo :x 7)
+7
+
+> (foo)
+5
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="6"></a>
+
+<hr>
+
+<h2>6 Printing</h2>
+
+<hr>
+
+<p>Some functions can cause output. The simplest one is
+<a href="../reference/print.htm">print</a>, which
+prints its argument and then <nobr>returns it:</nobr></p>
+
+<pre class="example">
+> (print 3)
+3 <font color="#008844">; screen output</font>
+3 <font color="#008844">; return value</font>
+</pre>
+
+<p>The first 3 above was <a href="../reference/print.htm">print</a>ed, the
+second was returned.</p>
+
+<p>If you want more complicated output, you will need to use
+<a href="../reference/format.htm">format</a>.
+Here's an example:</p>
+
+<pre class="example">
+> (format t "An atom: ~S~%and a list: ~S~%and an integer: ~A~%"
+ nil (list 5) 6)
+An atom: NIL <font color="#008844">; screen output</font>
+and a list: (5) <font color="#008844">; screen output</font>
+and an integer: 6 <font color="#008844">; screen output</font>
+NIL <font color="#008844">; return value</font>
+</pre>
+
+<p>See <a href="../reference/list.htm">list</a>. <nobr>The first</nobr>
+argument to <a href="../reference/format.htm">format</a> is either
+<a href="../reference/t.htm"> T </a>,
+<a href="../reference/nil.htm">NIL</a>, or a stream.
+<nobr><a href="../reference/t.htm"> T </a> specifies</nobr> output
+to the terminal. <nobr><a href="../reference/nil.htm">NIL</a> means</nobr>
+not to print anything but to return a string containing the output instead.
+Streams are general places for output <nobr>to go</nobr>. They can specify a
+file, or the terminal, or a printer device. This tutorial will not describe
+streams in any further detail.</p>
+
+<p>The second argument is a formatting template, which is a string
+optionally containing formatting directives. <nobr>All remaining</nobr>
+arguments may be referred to by the formatting directives. Lisp will replace
+the directives with some appropriate characters based on the arguments to
+which they refer and then print the resulting string.</p>
+
+<p>The format function always returns <a href="../reference/nil.htm">NIL</a>
+unless its first argument is <a href="../reference/nil.htm">NIL</a>, in
+which case it prints nothing and returns a string.</p>
+
+<p>There are several different directives available:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>~S</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">[standard] - accepts any Lisp object and replaces it by
+ the same printed representation which is produced by the
+ <a href="../reference/print.htm">print</a> function.</td>
+</tr>
+<tr>
+ <td><nobr><font size="-2"> </font></nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>~A</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">[aestethic] - tries to '<nobr>pretty-print</nobr>'
+ its argument.</td>
+</tr>
+<tr>
+ <td><nobr><font size="-2"> </font></nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>~%</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">[linebreak] - is always replaced by a linebreak character
+ or character sequence of the underlying operation system.</td>
+</tr>
+<tr>
+ <td><nobr><font size="-2"> </font></nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>~~</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">[tilde] - is replaced by a single '~' character.</td>
+</tr>
+</tbody></table></p>
+
+<p>If the last character in a line in a
+<a href="../reference/format.htm">format</a> template is a tilde, then
+the linebreak is ignored and the template continues with the next
+<nobr>non-whitespace</nobr> character in the next line.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="7"></a>
+
+<hr>
+
+<h2>7 Forms and the Top-Level Loop</h2>
+
+<hr>
+
+<p>The things which you type to the Lisp interpreter are called 'forms'.
+<nobr>The Lisp</nobr> interpreter repeatedly
+<a href="../reference/read.htm">read</a>s a form,
+<a href="../reference/eval.htm">eval</a>uates it, and
+<a href="../reference/print.htm">print</a>s the result. This procedure
+is therefore called the '<nobr>read-eval-print' loop</nobr>, or REPL for
+short.</p>
+
+<p>Some forms will cause errors. After an error, Lisp will put you into the
+debugger so you can try to figure out what caused the error.</p>
+
+<p>In general, a form is either an <a href="../reference/atom.htm">atom</a>,
+<nobr>[for example</nobr> a symbol, an integer, or a string] or <nobr>a
+<a href="../reference/list.htm">list</a></nobr>. <nobr>If the</nobr> form is
+an <a href="../reference/atom.htm">atom</a>, Lisp evaluates it immediately.
+Symbols evaluate to their value, integers and strings evaluate to
+themselves. <nobr>If the</nobr> form is a
+<a href="../reference/list.htm">list</a></nobr>, Lisp treats its first
+element as the name of a function. <nobr>It evaluates</nobr> the remaining
+elements recursively, and then calls the function with the values of the
+remaining elements as arguments. </p>
+
+<p>For example, if Lisp sees the form:</p>
+
+<pre class="example">
+(+ 3 4)
+</pre>
+
+<p>then it treats <a href="../reference/addition.htm"> + </a> as
+the name of a function. <nobr>It then</nobr> evaluates 3 to <nobr>get
+3</nobr> and 4 to <nobr>get 4</nobr>, finally it calls <a
+href="../reference/addition.htm"> + </a> with 3 and 4 as the
+arguments. <nobr>The <a href="../reference/addition.htm"> + </a>
+function</nobr> <nobr>returns 7</nobr>, which Lisp prints.</p>
+
+<p><div class="box">
+
+<p><b>Nyquist:</b> <nobr>A description</nobr> of the debugger can be found
+in the <nobr><a href="../manual/xlisp.htm#break-loop">Break Command Loop</a></nobr>
+section and a detailed description of the evaluation process can be found in
+the <a href="../manual/xlisp.htm#the-evaluator">Evaluator</a> section of the XLISP
+manual.</p>
+
+</div></p>
+
+<p>The <nobr>top-level</nobr> loop provides some other conveniences.
+<nobr>One particularly</nobr> convenient convenience is the ability to talk
+about the results of previously typed forms. Lisp always saves its most
+recent three results, it stores them as the values of the symbols
+<a href="../manual/xlisp.htm#command-loop"> * </a>,
+<a href="../manual/xlisp.htm#command-loop"> ** </a>,
+<nobr>and <a href="../manual/xlisp.htm#command-loop"> *** </a></nobr>.
+<nobr>For example:</nobr></p>
+
+<pre class="example">
+> 3
+3
+
+> 4
+4
+
+> 5
+5
+
+> ***
+3
+
+> ***
+4
+
+> ***
+5
+
+> **
+4
+
+> *
+4
+</pre>
+
+<p>See <a href="../manual/xlisp.htm#command-loop"> * </a>,
+<a href="../manual/xlisp.htm#command-loop"> ** </a>,
+<a href="../manual/xlisp.htm#command-loop"> *** </a>,
+<a href="../manual/xlisp.htm#command-loop"> + </a>,
+<a href="../manual/xlisp.htm#command-loop"> ++ </a>,
+<a href="../manual/xlisp.htm#command-loop"> +++ </a>,
+<a href="../manual/xlisp.htm#command-loop"> − </a>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="8"></a>
+
+<hr>
+
+<h2>8 Special Forms</h2>
+
+<hr>
+
+<p>There are a number of special forms which look like function calls but
+aren't. These include control constructs such as
+<a href="../reference/if.htm"> if </a> statements and
+<a href="../reference/do.htm">do</a> loops, assignments like
+<a href="../reference/setq.htm">setq</a>,
+<a href="../reference/setf.htm">setf</a>,
+<a href="../reference/push.htm">push</a>, and
+<a href="../reference/pop.htm">pop</a>, definitions such as
+<a href="../reference/defun.htm">defun</a>, and binding constructs such
+<nobr>as <a href="../reference/let.htm">let</a></nobr>. <nobr>Not all</nobr>
+of these special forms have been mentioned yet, see below for examples.</p>
+
+<p>One useful special form is the <a href="../reference/quote.htm">quote</a>
+form. <nobr>The <a href="../reference/quote.htm">quote</a></nobr> function
+prevents its argument from being evaluated. <nobr>For example:</nobr></p>
+
+<pre class="example">
+> (setq a 3)
+3
+
+> a
+3
+
+> (quote a)
+A
+
+> 'a <font color="#008844">; 'a is an abbreviation for (quote a)</font>
+A
+</pre>
+
+<p>Another similar special form is the
+<a href="../reference/function.htm">function</a> form, it causes its
+argument to be interpreted as a function rather than being evaluated.
+<nobr>For example:</nobr></p>
+
+<pre class="example">
+> (setq + 3)
+3
+
+> +
+3
+
+> '+
++
+
+> (function +)
+#<Subr-+: #88b44d5e>
+
+> #'+ <font color="#008844">; #'+ is an abbreviation for (function +)</font>
+#<Subr-+: #88b44d5e>
+</pre>
+
+<p>The <a href="../reference/function.htm">function</a> special form is
+useful when you want to pass a function as an argument to another function.
+<nobr>See below</nobr> for some examples of functions which take functions
+as arguments.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="9"></a>
+
+<hr>
+
+<h2>9 Binding</h2>
+
+<hr>
+
+<p>Binding is lexically scoped assignment. <nobr>It happens</nobr> to the
+variables in a function's parameter list whenever the function is called.
+<nobr>The formal</nobr> parameters are bound to the actual parameters for
+the duration of the function call. <nobr>You can</nobr> bind variables
+anywhere in a program with the <a href="../reference/let.htm">let</a>
+special form, which looks <nobr>like this:</nobr></p>
+
+<pre class="example">
+(let ((<font color="#0000CC">variable-1 value-1</font>)
+ (<font color="#0000CC">variable-2 value-2</font>)
+ <font color="#008844">...</font> )
+ <font color="#0000CC">body</font>)
+</pre>
+
+<p>The <a href="../reference/let.htm">let</a> function binds
+'<nobr>variable-1</nobr>' to '<nobr>value-1</nobr>',
+'<nobr>variable-2</nobr>' to '<nobr>value-2</nobr>', and so forth.
+<nobr>Then it</nobr> executes the statements in its body. The body of a
+<a href="../reference/let.htm">let</a> follows exactly the same rules that
+a function body does. Some examples:</p>
+
+<pre class="example">
+> (let ((a 3)) (+ a 1))
+4
+
+> (let ((a 2)
+ (b 3)
+ (c 0))
+ (setq c (+ a b))
+ c)
+5
+
+> (setq c 4)
+4
+
+> (let ((c 5))
+ c)
+5
+
+> c
+4
+</pre>
+
+<p>See <a href="../reference/addition.htm"> + </a>,
+<a href="../reference/let.htm">let</a>,
+<a href="../reference/setq.htm">setq</a>. <nobr>Instead of:</nobr></p>
+
+<pre class="example">
+(let ((a nil)
+ (b nil))
+ <font color="#008844">...</font> )
+</pre>
+
+<p>you can write:</p>
+
+<pre class="example">
+(let (a b)
+ <font color="#008844">...</font> )
+</pre>
+
+<p>The '<nobr>value-1</nobr>', '<nobr>value-2</nobr>', etc. inside a
+<a href="../reference/let.htm">let</a> form cannot reference the variables
+'<nobr>variable-1</nobr>', '<nobr>variable-2</nobr>', etc. that the
+<a href="../reference/let.htm">let</a> form is binding. <nobr>For
+example:</nobr></p>
+
+<pre class="example">
+> (let ((x 1)
+ (y (+ <font color="#AA0000">x</font> 1))) <font color="#008844">; x is still unbound here</font>
+ y)
+<font color="#AA0000">error: unbound variable - x</font>
+</pre>
+
+<p>If the symbol 'x' already has a global value, stranger happenings will
+result:</p>
+
+<pre class="example">
+> (setq x 7)
+7
+
+> (let ((x 1)
+ (y (+ <font color="#AA0000">x</font> 1))) <font color="#008844">; references to the global x</font>
+ y)
+8
+</pre>
+
+<p>The <a href="../reference/let-star.htm">let*</a> special form is just
+like <a href="../reference/let.htm">let</a> except that it allows values to
+reference variables defined earlier in the
+<a href="../reference/let-star.htm">let*</a> form.
+<nobr>For example:</nobr></p>
+
+<pre class="example">
+> (setq x 7)
+7
+
+> (let* ((x 1)
+ (y (+ x 1))) <font color="#008844">; references to x in the line before</font>
+ y)
+2
+</pre>
+
+<p>The <a href="../reference/let-star.htm">let*</a> form:</p>
+
+<pre class="example">
+(let* ((x a)
+ (y b))
+ <font color="#008844">...</font> )
+</pre>
+
+<p>is equivalent to the following <a href="../reference/let.htm">let</a>
+construct:</p>
+
+<pre class="example">
+(let ((x a))
+ (let ((y b))
+ <font color="#008844">...</font> ))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="10"></a>
+
+<hr>
+
+<h2>10 Dynamic Scoping</h2>
+
+<hr>
+
+<p>The <a href="../reference/let.htm">let</a> and
+<a href="../reference/let-star.htm">let*</a> forms provide lexical scoping,
+which is what you expect if you're used to programming in C or Pascal.
+Dynamic scoping is what you get in BASIC. <nobr>If you</nobr> assign a value
+to a dynamically scoped variable, every mention of that variable returns
+that value until you assign another value to the same variable.</p>
+
+<p>In Lisp, dynamically scoped variables are called 'special' variables.
+<nobr>In Common Lisp</nobr> special variables are declared with the 'defvar'
+special form. <nobr>In Nyquist</nobr> there is no 'defvar' form.</p>
+
+<p><div class="box">
+
+<p>Nyquist has no 'dynamic' scoping in the <nobr>Common Lisp</nobr> sense.</p>
+
+</div></p>
+
+<p>In Nyquist every variable assigned with
+<a href="../reference/setq.htm">setq</a> or
+<a href="../reference/setf.htm">setf</a> at the <nobr>top-level</nobr>,
+outside of a function or a <a href="../reference/let.htm">let</a>
+binding, is a lexical scoped variable. Here is an example what this means:</p>
+
+<pre class="example">
+> (setq *variable* 5) <font color="#008844">; define a global variable</font>
+5
+
+> (defun check-variable () <font color="#008844">; define a function in global scope,</font>
+ *variable*) <font color="#008844">; returning the value of the variable</font>
+CHECK-VARIABLE
+
+> (check-variable) <font color="#008844">; the CHECK-VARIABLE function returns</font>
+5 <font color="#008844">; the global value of the variable</font>
+
+> (let ((*variable* 10)) <font color="#008844">; create a local binding for the variable</font>
+ (print (check-variable)) <font color="#008844">; call CHECK-VARIABLE and print the return value</font>
+ (print *variable*)) <font color="#008844">; print the local value of the variable</font>
+5 <font color="#008844">; return value of CHECK-VARIABLE</font>
+10 <font color="#008844">; variable value inside of LET</font>
+10
+</pre>
+
+<p>See <a href="../reference/defun.htm">defun</a>,
+<a href="../reference/let.htm">let</a>,
+<a href="../reference/print.htm">print</a>,
+<a href="../reference/setq.htm">setq</a>. Because the
+'<nobr>check-variable</nobr>' function was defined in global
+scope and therefore is lexically outside of the
+<a href="../reference/let.htm">let</a> form, the
+'<nobr>check-variable</nobr>' function returns the variable's global value
+<nobr>of 5</nobr>, even if called from inside the
+<a href="../reference/let.htm">let</a> form, where the variable has a
+<nobr>value of 10</nobr>.</p>
+
+<p><div class="box">
+
+<p><b>Important:</b> In Nyquist there is no way to change the scoping
+behaviour of variables, so you must be careful where you define your
+variables. With Nyquist it's generally a good idea to prefer local
+<a href="../reference/let.htm">let</a> bindings over global variables.</p>
+
+</div></p>
+
+<p>By convention, the name of a global Nyquist variable begins and ends with
+a <nobr>star *</nobr> to signal that the variable might behave differently
+than the programmer expects.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="11"></a>
+
+<hr>
+
+<h2>11 Arrays</h2>
+
+<hr>
+
+<p>The function
+<nobr><a href="../reference/make-array.htm">make-array</a></nobr> makes a
+<nobr>1-dimensional</nobr> array.
+<nobr>The <a href="../reference/aref.htm">aref</a></nobr> function accesses
+its elements. <nobr>All elements</nobr> of an array are initially set
+<nobr>to <a href="../reference/nil.htm">NIL</a></nobr>.
+<nobr>For example:</nobr></p>
+
+<pre class="example">
+> (make-array 4) <font color="#008844">; 1-D array with 4 elements</font>
+#(NIL NIL NIL NIL)
+</pre>
+
+<p>Array indices always <nobr>start at 0</nobr>. <nobr>See
+<a href="#13">below</a></nobr> for how to set the elements of an array.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="12"></a>
+
+<hr>
+
+<h2>12 Strings</h2>
+
+<hr>
+
+<p>A string is a sequence of characters between double quotes. Nyquist
+represents a string internally as a <nobr>variable-length</nobr> array of
+characters. <nobr>You can</nobr> write a string containing a double quote by
+preceding the quote with a backslash. <nobr>A double</nobr> backslash stands
+for a single backslash. <nobr>For example:</nobr></p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr valign="top">
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>"abcd"</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>has 4 characters</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>"\""</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>has 1 character, a quote</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr valign="top">
+ <td><nobr><code> </code></nobr></td>
+ <td class="button"><nobr><code>"\\"</code></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>has 1 character, a backslash</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>Here are some functions for dealing with strings:</p>
+
+<pre class="example">
+> (strcat "abcd" "efg")
+"abcdefg" <font color="#008844">; STRCAT concatenates strings</font>
+
+> (char "abc" 1)
+#\b <font color="#008844">; Lisp writes characters preceded by #\</font>
+
+> (subseq "abc" 0 2)
+"ab" <font color="#008844">; SUBSEQ extracts substrings</font>
+</pre>
+
+<p>See <a href="../reference/char.htm">char</a>,
+<a href="../reference/strcat.htm">strcat</a>,
+<a href="../reference/subseq.htm">subseq</a>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="13"></a>
+
+<hr>
+
+<h2>13 Setf</h2>
+
+<hr>
+
+<p>Certain forms in Lisp naturally define a memory location. For example, if
+the value of 'x' is a <a href="../reference/list.htm">list</a>, then
+<nobr>(<a href="../reference/nth.htm">nth</a> 4 x)</nobr> defines the fifth
+element of the <a href="../reference/list.htm">list</a>. <nobr>Or, if</nobr>
+the value of 'y' is a <nobr>one-dimensional</nobr>
+<a href="../reference/make-array.htm">array</a>,
+<nobr>(<a href="../reference/aref.htm">aref</a> y 2)</nobr> defines the
+third element of the <a href="../reference/make-array.htm">array</a>.</p>
+
+<p>The <a href="../reference/setf.htm">setf</a> special form uses its first
+argument to define a place in memory, evaluates its second argument, and
+stores the resulting value in the resulting memory location. <nobr>For
+example:</nobr></p>
+
+<pre class="example">
+> (setq a (make-array 3))
+#(NIL NIL NIL)
+
+> (aref a 1)
+NIL
+
+> (setf (aref a 1) 3) <font color="#008844">; store 3 in the second element of a</font>
+3
+
+> a
+#(NIL 3 NIL)
+
+> (aref a 1) <font color="#008844">; read the second element of a</font>
+3
+
+> (setq b (list 1 2 3 4 5))
+(1 2 3 4 5)
+
+> (nth 4 b)
+5
+
+> (setf (nth 4 b) "five") <font color="#008844">; store "five" in the fifth element of b</font>
+"five"
+
+> b
+(1 2 3 4 "five")
+
+> (nth 4 b)
+"five"
+</pre>
+
+<p>The <a href="../reference/setf.htm">setf</a> function is the only way to
+set the elements of a list or an array.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="14"></a>
+
+<hr>
+
+<h2>14 Booleans and Conditionals</h2>
+
+<hr>
+
+<p>Lisp uses the <nobr>self-evaluating</nobr> symbol
+<a href="../reference/nil.htm">NIL</a> to mean false. Anything other than
+<nobr>self-evaluating</nobr> means true. Unless we have a reason not to,
+we usually use the <nobr>self-evaluating</nobr> symbol
+<a href="../reference/t.htm"> T </a> to stand
+<nobr>for true</nobr>.</p>
+
+<p>Lisp provides a standard set of logical functions, for example
+<a href="../reference/and.htm">and</a>,
+<a href="../reference/or.htm">or</a>, and
+<a href="../reference/not.htm">not</a>.
+<nobr>The <a href="../reference/and.htm">and</a></nobr> and
+<a href="../reference/or.htm">or</a> connectives are
+<nobr>short-circuiting</nobr>, <a href="../reference/and.htm">and</a>
+will not evaluate any arguments to the right of the first one which
+evaluates <nobr>to <a href="../reference/nil.htm">NIL</a></nobr>, while
+<a href="../reference/or.htm">or</a> will not evaluate any arguments to the
+right of the first one which evaluates
+<nobr>to <a href="../reference/t.htm"> T </a></nobr>.</p>
+
+<p>Lisp also provides several special forms for conditional execution. The
+simplest of these <nobr>is
+<a href="../reference/if.htm"> if </a></nobr>. The first argument
+of <a href="../reference/if.htm"> if </a> determines whether the
+second or third argument will be executed:</p>
+
+<pre class="example">
+> (if t 5 6)
+5
+
+> (if nil 5 6)
+6
+
+> (if 4 5 6)
+5
+</pre>
+
+<p>If you need to put more than one statement in the 'then' or 'else' clause
+of an <a href="../reference/if.htm"> if </a></nobr> statement,
+you can use the <a href="../reference/progn.htm">progn</a> special form.
+<a href="../reference/progn.htm">progn</a> executes each statement in its
+body, then returns the value of the <nobr>final one</nobr>:</p>
+
+<pre class="example">
+> (setq a 7)
+7
+
+> (setq b 0)
+0
+
+> (setq c 5)
+5
+
+> (if (> a 5)
+ (progn
+ (setq a (+ b 7))
+ (setq b (+ c 8)))
+ (setq b 4))
+13
+</pre>
+
+<p>An <a href="../reference/if.htm"> if </a> statement which lacks
+either a 'then' or an 'else' clause can be written using the
+<a href="../reference/when.htm">when</a> or
+<a href="../reference/unless.htm">unless</a> special form:</p>
+
+<pre class="example">
+> (when t 3)
+3
+
+> (when nil 3)
+NIL
+
+> (unless t 3)
+NIL
+
+> (unless nil 3)
+3
+</pre>
+
+<p><a href="../reference/when.htm">when</a> and
+<a href="../reference/unless.htm">unless</a>, unlike
+<a href="../reference/if.htm"> if </a>, allow any number of
+statements in their bodies:</p>
+
+<pre class="example">
+(when x
+ a
+ b
+ c)
+</pre>
+
+<p>is equivalent to:</p>
+
+<pre class="example">
+(if x
+ (progn
+ a
+ b
+ c))
+</pre>
+
+<p>For example:</p>
+
+<pre class="example">
+> (when t
+ (setq a 5)
+ (+ a 6))
+11
+</pre>
+
+<p>More complicated conditionals can be defined using the
+<a href="../reference/cond.htm">cond</a> special form.
+<nobr>A <a href="../reference/cond.htm">cond</a></nobr> form consists of
+the symbol cond followed by a number of
+<a href="../reference/cond.htm">cond</a> clauses, each of which is a list.
+<nobr>The first</nobr> element of a <a href="../reference/cond.htm">cond</a>
+clause is the condition, the remaining elements <nobr>[if any]</nobr> are
+the actions:</p>
+
+<pre class="example">
+(cond (<font color="#0000CC">condition-1 action-1</font>)
+ (<font color="#0000CC">condition-2 action-2</font>)
+ ...
+ (t <font color="#0000CC">default-action</font>))
+</pre>
+
+<p>The <a href="../reference/cond.htm">cond</a> form finds the first clause
+whose condition evaluates to true [does not evaluate <nobr>to
+<a href="../reference/nil.htm">NIL</a>]</nobr>. <nobr>It then</nobr>
+executes the corresponding action and returns the resulting value. None of
+the remaining conditions are evaluated, nor are any actions except the one
+corresponding to the selected condition. <nobr>For example</nobr>:</p>
+
+<pre class="example">
+> (setq a 3)
+3
+
+> (cond
+ ((evenp a) a) <font color="#008844">; if a is even return a</font>
+ ((> a 7) (/ a 2)) <font color="#008844">; else if a is bigger than 7 return a/2</font>
+ ((< a 5) (- a 1)) <font color="#008844">; else if a is smaller than 5 return a-1</font>
+ (t 17)) <font color="#008844">; else return 17</font>
+2
+</pre>
+
+<p>If the action in the selected <a href="../reference/cond.htm">cond</a>
+clause is missing, then <a href="../reference/cond.htm">cond</a> returns
+what the condition <nobr>evaluated to:</nobr></p>
+
+<pre class="example">
+> (cond ((+ 3 4)))
+7
+</pre>
+
+<p>The Lisp <a href="../reference/case.htm">case</a> form is like a C
+'switch' statement:</p>
+
+<pre class="example">
+> (setq x 'b)
+B
+
+> (case x
+ (a 5)
+ ((d e) 7)
+ ((b f) 3)
+ (t 9))
+3
+</pre>
+
+<p>The <a href="../reference/t.htm"> T </a> clause at the end
+means that if 'x' is not 'a', '<nobr>d or e</nobr>', or
+'<nobr>b or f</nobr>', then the <a href="../reference/case.htm">case</a>
+form will <nobr>return 9</nobr>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="15"></a>
+
+<hr>
+
+<h2>15 Iteration</h2>
+
+<hr>
+
+<p>The simplest iteration construct in Lisp is
+<a href="../reference/loop.htm">loop</a>.
+<nobr>A <a href="../reference/loop.htm">loop</a></nobr> construct repeatedly
+executes its body until it hits a
+<a href="../reference/return.htm">return</a> special form.
+<nobr>For example</nobr>:</p>
+
+<pre class="example">
+> (setq a 4)
+4
+
+> (loop
+ (setq a (+ a 1))
+ (when (> a 7) (return a)))
+8
+
+> (loop
+ (setq a (- a 1))
+ (when (< a 3) (return)))
+NIL
+</pre>
+
+<p>The next simplest is <a href="../reference/dolist.htm">dolist</a>.
+<nobr>It binds</nobr> a variable to the elements of a list in order and
+stops when it hits the end of <nobr>the list</nobr>:</p>
+
+<pre class="example">
+> (dolist (x '(a b c))
+ (print x))
+A
+B
+C
+NIL
+</pre>
+
+<p><a href="../reference/dolist.htm">dolist</a> always
+<nobr>returns <a href="../reference/nil.htm">NIL</a></nobr>. Note that the
+value of 'x' in the above example was
+<nobr>never <a href="../reference/nil.htm">NIL</a></nobr>.
+<nobr>The <a href="../reference/nil.htm">NIL</a></nobr> below the C was the
+value that <a href="../reference/dolist.htm">dolist</a> returned, printed
+by the <nobr>read-eval-print</nobr> loop.</p>
+
+<p>The most flexible, but also most complicated iteration form is
+<nobr>called <a href="../reference/do.htm">do</a></nobr>.
+<nobr>A <a href="../reference/do.htm">do</a></nobr> form looks
+<nobr>like this</nobr>:</p>
+
+<pre class="example">
+> (do ((x 1 (+ x 1)) <font color="#008844">; variable x, initial value 1, update with (+ x 1)</font>
+ (y 1 (* y 2))) <font color="#008844">; variable y, initial value 1, update with (* y 2)</font>
+ ((> x 5) y) <font color="#008844">; terminate if (> x 5), return the value of y</font>
+ (print y)
+ (print 'working))
+1
+WORKING
+2
+WORKING
+4
+WORKING
+8
+WORKING
+16
+WORKING
+32
+</pre>
+
+<p>The first part of a <a href="../reference/do.htm">do</a> form specifies
+what variables to bind, what their initial values are, and how to update
+them. <nobr>The second</nobr> part specifies a termination condition and a
+return value. The last part is the body. <nobr>A
+<a href="../reference/do.htm">do</a></nobr> form binds its variables to
+their initial values like
+<nobr>a <a href="../reference/let.htm">let</a></nobr>, then checks the
+termination condition. <nobr>As long</nobr> as the condition is false, it
+executes the body repeatedly. When the condition becomes true, it
+returns the value of the <nobr>return-value</nobr> form.</p>
+
+<p>The <a href="../reference/do-star.htm">do*</a> form is to
+<a href="../reference/do.htm">do</a> as
+<a href="../reference/let-star.htm">let*</a> is
+<nobr>to <a href="../reference/let.htm">let</a></nobr>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="16"></a>
+
+<hr>
+
+<h2>16 Non-local Exits</h2>
+
+<hr>
+
+<p>The <a href="../reference/return.htm">return</a> special form is an
+example of a nonlocal return. Another example is
+<nobr><a href="../reference/return-from.htm">return-from</a></nobr>, which
+returns a value from the surrounding function:</p>
+
+<pre class="example">
+> (defun foo (x)
+ (return-from foo 3)
+ x)
+FOO
+
+> (foo 17)
+3
+</pre>
+
+<p>Actually, the <nobr><a
+href="../reference/return-from.htm">return-from</a></nobr> form can return
+from any named block, it's just that functions are the only blocks which are
+named by default. <nobr>You can</nobr> create a named block with the
+<a href="../reference/block.htm">block</a> special form:</p>
+
+<pre class="example">
+> (block foo
+ (return-from foo 7)
+ 3)
+7
+</pre>
+
+<p>The <a href="../reference/return.htm">return</a> special form can return
+from any block <nobr>named <a href="../reference/nil.htm">NIL</a></nobr>.
+Loops are by default
+<nobr>named <a href="../reference/nil.htm">NIL</a></nobr>, but you can
+make your own
+<nobr><a href="../reference/nil.htm">NIL</a>-named blocks</nobr>:</p>
+
+<pre class="example">
+> (block nil
+ (return 7)
+ 3)
+7
+</pre>
+
+<p>Another form which causes a nonlocal exit is the
+<nobr><a href="../reference/error.htm">error</a> form</nobr>:</p>
+
+<pre class="example">
+> (error "This is an error")
+<font color="#AA0000">error: This is an error</font>
+</pre>
+
+<p>The <a href="../reference/error.htm">error</a> form applies format to its
+arguments, then places you in the debugger.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="17"></a>
+
+<hr>
+
+<h2>17 Funcall, Apply, and Mapcar</h2>
+
+<hr>
+
+<p>Earlier I promised to give some functions which take functions as
+arguments. Here they are:</p>
+
+<pre class="example">
+> (funcall #'+ 3 4)
+7
+
+> (apply #'+ 3 4 '(3 4))
+14
+
+> (mapcar #'not '(t nil t nil t nil))
+(NIL T NIL T NIL T)
+</pre>
+
+<p><a href="../reference/funcall.htm">funcall</a> calls its first argument
+on its remaining arguments.</p>
+
+<p><a href="../reference/apply.htm">apply</a> is just like
+<a href="../reference/funcall.htm">funcall</a>, except that its final
+argument should be a list. <nobr>The elements</nobr> of that list are
+treated as if they were additional arguments to
+<nobr>a <a href="../reference/funcall.htm">funcall</a></nobr>.</p>
+
+<p>The first argument to <a href="../reference/mapcar.htm">mapcar</a> must
+be a function of one argument, <a href="../reference/mapcar.htm">mapcar</a>
+applies this function to each element of a list and collects the results in
+another list.</p>
+
+<p><a href="../reference/funcall.htm">funcall</a> and
+<a href="../reference/apply.htm">apply</a> are chiefly useful when their
+first argument is a variable. <nobr>For instance</nobr>, a search engine
+could take a heuristic function as a parameter and use
+<a href="../reference/funcall.htm">funcall</a> or
+<a href="../reference/apply.htm">apply</a> to call that function on a
+state description. <nobr>The sorting</nobr> functions described later use
+<a href="../reference/funcall.htm">funcall</a> to call their comparison
+functions.</p>
+
+<p><a href="../reference/mapcar.htm">mapcar</a>, along with nameless
+<a href="#18">lambda</a> functions, can replace many loops.</p>
+
+<p><div class="box">
+
+<p><b>Nyquist/XLISP:</b> <nobr>In XLISP</nobr>, a '<nobr>special
+form</nobr>' of type FSUBR is not a function. This means that
+<a href="../reference/apply.htm">apply</a>,
+<a href="../reference/funcall.htm">funcall</a> and
+<a href="../reference/mapcar.htm">mapcar</a> only work with functions
+of type SUBR [built-in function] or CLOSURE [function defined by
+<a href="../reference/defun.htm">defun</a>,
+<a href="../reference/flet.htm">flet</a>,
+<a href="../reference/labels.htm">labels</a>, or
+<a href="../reference/lambda.htm">lambda</a>], but with special forms
+of <nobr>type FSUBR</nobr> a 'bad argument type' error is signalled.</p>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="18"></a>
+
+<hr>
+
+<h2>18 Lambda</h2>
+
+<hr>
+
+<p>If you just want to create a temporary function and don't want to
+bother giving it a name, <a href="../reference/lambda.htm">lambda</a> is
+what you need.</p>
+
+<pre class="example">
+> #'(lambda (x)
+ (+ x 3))
+#<Closure: #88b71ece>
+
+> (funcall * 5)
+8
+</pre>
+
+<p>The combination of <a href="../reference/lambda.htm">lambda</a> and
+<a href="../reference/mapcar.htm">mapcar</a> can replace many loops.
+<nobr>For example</nobr>, the following two forms are equivalent:</p>
+
+<pre class="example">
+> (do ((x '(1 2 3 4 5) (cdr x))
+ (y nil))
+ ((null x) (reverse y))
+ (push (+ (car x) 2) y))
+(3 4 5 6 7)
+
+> (mapcar #'(lambda (x) (+ x 2)) '(1 2 3 4 5))
+(3 4 5 6 7)
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="19"></a>
+
+<hr>
+
+<h2>19 Sorting</h2>
+
+<hr>
+
+<p>Lisp provides a primitive for
+<nobr>sorting, <a href="../reference/sort.htm">sort</a></nobr>:</p>
+
+<pre class="example">
+> (sort '(2 1 5 4 6) #'<)
+(1 2 4 5 6)
+
+> (sort '(2 1 5 4 6) #'>)
+(6 5 4 2 1)
+</pre>
+
+<p>The first argument to <a href="../reference/sort.htm">sort</a> is a list,
+the second is a comparison function. <nobr>Be careful</nobr>, because
+<a href="../reference/sort.htm">sort</a> is allowed to destroy its argument,
+so if the original sequence is important to you, make a copy before sorting
+<nobr>the list</nobr>.</p>
+
+<p><div class="box">
+
+<p><b>Bug:</b> In Nyquist 3.03 [November 2010] the XLISP
+<a href="../reference/sort.htm">sort</a> function has a bug, so it's better
+to store the return value of sort in the original variable <nobr>like
+this</nobr>:</p>
+
+<pre class="example">
+(setq a '(3 1 4 1 5 9 6 7)) => (3 1 4 1 5 9 6 7)
+(setq a (sort a '<)) => (1 1 3 4 5 6 7 9)
+a => (1 1 3 4 5 6 7 9)
+</pre>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="20"></a>
+
+<hr>
+
+<h2>20 Equality</h2>
+
+<hr>
+
+<p>Lisp has many different ideas of equality. Numerical equality is
+denoted by =. Two symbols are eq if and only if they are identical. Two
+copies of the same list are not eq, but they are equal.</p>
+
+<pre class="example">
+> (eq 'a 'a)
+T
+
+> (eq 'a 'b)
+NIL
+
+> (= 3 4)
+T
+
+> (eq '(a b c) '(a b c))
+NIL
+
+> (equal '(a b c) '(a b c))
+T
+
+> (eql 'a 'a)
+T
+
+> (eql 3 3)
+T
+</pre>
+
+<p>The eql predicate is equivalent to eq for symbols and to = for numbers.</p>
+
+<p>The equal predicate is equivalent to eql for symbols and numbers. It is
+true for two conses if and only if their cars are equal and their cdrs are
+equal.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="21"></a>
+
+<hr>
+
+<h2>21 Some Useful List Functions</h2>
+
+<hr>
+
+<p>These functions all manipulate lists:</p>
+
+<pre class="example">
+> (append '(1 2 3) '(4 5 6)) ;concatenate lists
+(1 2 3 4 5 6)
+
+> (reverse '(1 2 3)) ;reverse the elements of a list
+(3 2 1)
+
+> (member 'a '(b d a c)) ;set membership -- returns the first tail
+(A C) ;whose car is the desired element
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/tutorials/nyquist.htm b/docsrc/xlisp/xlisp-doc/tutorials/nyquist.htm new file mode 100644 index 0000000..19364ea --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/tutorials/nyquist.htm @@ -0,0 +1,383 @@ +<html><head>
+
+<title>Nyquist</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Nyquist</h1>
+
+<hr>
+
+<ul>
+<li><nobr><a href="#debugger-shortcuts">Debugger Shortcuts</a></nobr></li>
+<li><nobr><a href="#grindef">grindef</a> - print the function definition of a closure</nobr></li>
+<li><nobr><a href="#args">args</a> - print the argument list of a closure</nobr></li>
+<li><nobr><a href="#setfn">setfn</a> - define 'alias' names for functions</nobr></li>
+<li><nobr><a href="#display">display</a> - framework for debug messages</nobr></li>
+</ul>
+
+<p>This page will not save you from reading the Nyquist manual, it's a list
+of things I find useful but frequently have to look them up in the manuals
+when I haven't worked with Nyquist for a while. Many more useful tricks can
+be found in the 'Developing and Debugging in Nyquist' chapter in the Nyquist
+manual.</p>
+
+<a name="debugger-shortcuts"></a>
+
+<hr>
+
+<h2>Debugger Shortcuts</h2>
+
+<hr>
+
+<p>Some Nyquist/XLISP debugger shortcuts, defined in 'xlinit.lsp' and
+'misc.lsp':</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(bt)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><a href="../reference/baktrace.htm">baktrace</a></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(co)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><a href="../reference/continue.htm">continue</a></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(top)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><a href="../reference/top-level.htm">top-level</a></td>
+</tr>
+<tr>
+ <td><nobr><font size="-2"> </font></nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(res)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><a href="../reference/clean-up.htm">clean-up</a></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(up)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><a href="../reference/clean-up.htm">clean-up</a></td>
+</tr>
+</tbody></table></p>
+
+<p>The debugger commands only work if
+<a href="../reference/global-breakenable.htm">*breakenable*</a>
+is <nobr>non-<a href="../reference/nil.htm">NIL</a></nobr>:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(bkon)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><nobr>(setq
+ <a href="../reference/global-breakenable.htm">*breakenable*</a>
+ t)</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(bkoff)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><nobr>(setq
+ <a href="../reference/global-breakenable.htm">*breakenable*</a>
+ nil)</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>You can make your own
+<a href="../reference/global-tracenable.htm">*tracenable*</a>
+shortcuts like shown here:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">tron</font> ()
+ (setq <font color="#AA5500">*tracenable*</font> t))
+
+(defun <font color="#0000CC">troff</font> ()
+ (setq <font color="#AA5500">*tracenable*</font> nil))
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr>XLISP 2.0 Manual → <a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="grindef"></a>
+
+<hr>
+
+<h2>grindef</h2>
+
+<hr>
+
+<p>The 'grindef' function prints the Lisp code of a
+<a href="../manual/xlisp.htm#data-types">closure</a> <nobr>[user-defined</nobr>
+function or macro]:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">grindef</font> (e)
+ (pprint (get-lambda-expression (symbol-function e))))
+</pre>
+
+<p>Example:</p>
+
+<pre class="example">
+> (grindef 'grindef)
+(LAMBDA (E)
+ (PPRINT (GET-LAMBDA-EXPRESSION (SYMBOL-FUNCTION E))))
+NIL
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="args"></a>
+
+<hr>
+
+<h2>args</h2>
+
+<hr>
+
+<p>The 'args' function prints the name and the argument variables of a
+<a href="../manual/xlisp.htm#data-types">closure</a> <nobr>[user-defined</nobr>
+function or macro]:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">args</font> (e)
+ (pprint (cons e (second (get-lambda-expression (symbol-function e))))))
+</pre>
+
+<p>Example:</p>
+
+<pre class="example">
+> (args 'args)
+(ARGS E)
+NIL
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="setfn"></a>
+
+<hr>
+
+<h2>setfn</h2>
+
+<hr>
+
+<p>The 'setfn' macro defines 'alias' names for functions:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">setfn</font> (a b)
+ `(setf (symbol-function ',a) (symbol-function ',b)))
+</pre>
+
+<p>Examples from 'xlinit.lsp':</p>
+
+<pre class="example">
+(setfn co continue)
+(setfn top top-level)
+(setfn res clean-up)
+(setfn up clean-up)
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="display"></a>
+
+<hr>
+
+<h2>display</h2>
+
+<hr>
+
+<p>'display' is a debugging macro, defined in 'xlinit.lsp'.</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">display-macro</font> (label &rest items)
+ (let ($res$)
+ (dolist ($item$ items)
+ (setq $res$ (cons
+ `(format t <font color="#880000">"~A = ~A "</font> ',$item$ ,$item$)
+ $res$)))
+ (append (list 'let nil `(format t <font color="#880000">"~A : "</font> ,label))
+ (reverse $res$)
+ '((terpri)))))
+
+(defun <font color="#0000CC">display-on</font> ()
+ (setfn display display-macro) t)
+
+(defun <font color="#0000CC">display-off</font> ()
+ (setfn display or) nil)
+</pre>
+
+<p>Usage:</p>
+
+<pre class="example">
+(display <font color="#880000">"heading"</font> <font color="#0000CC">var1 var2</font> ...)
+</pre>
+
+<p>expands into:</p>
+
+<pre class="example">
+(let ()
+ (format t "~A: " <font color="#880000">"heading"</font>)
+ (format t "~A = ~A " ',<font color="#0000CC">var1</font> ,<font color="#0000CC">var1</font>)
+ (format t "~A = ~A " ',<font color="#0000CC">var2</font> ,<font color="#0000CC">var2</font>)
+ ... )
+</pre>
+
+<p>and then prints:</p>
+
+<pre class="example">
+<font color="#0000CC">heading</font> : <font color="#0000CC">VAR1</font> = <font color="#0000CC">value1 VAR2</font> = <font color="#0000CC">value2</font> ...
+</pre>
+
+<p>Using the 'display' macro in a function like shown here:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">hello</font> ()
+ (let ((local-var 'hello))
+ (display <font color="#880000">"debug message"</font> local-var)
+ local-var)) <font color="#008844">; return value</font>
+</pre>
+
+<p>Now the '<nobr>debug message</nobr>' can be switched on and off without
+changing the code:</p>
+
+<pre class="example">
+> (display-on)
+T
+
+> (hello)
+debug message : LOCAL-VAR = HELLO
+HELLO
+
+> (display-off)
+NIL
+
+> (hello)
+HELLO
+</pre>
+
+
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/tutorials/shell-utilities.htm b/docsrc/xlisp/xlisp-doc/tutorials/shell-utilities.htm new file mode 100644 index 0000000..4c0a075 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/tutorials/shell-utilities.htm @@ -0,0 +1,539 @@ +<html><head>
+
+<title>Shell Utilities</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Shell Utilities</h1>
+
+<hr>
+
+<ul>
+<li><nobr><a href="#cd">cd</a> - display and change directories</nobr></li>
+<li><nobr><a href="#ls">ls</a> - display files and sub-directories</nobr></li>
+<li><nobr><a href="#hd">hd</a> - hexdump a file</nobr></li>
+</ul>
+
+<p>Nyquist is not a system programming language, so Nyquist/XLISP cannot
+create or remove files and directories, and the <a
+href="../reference/system.htm">system</a> function does not work on Windows.
+<nobr>But sometimes</nobr> it helps to know the name of the current working
+directory, the name of the directory where the soundfiles are stored, or the
+names of files and <nobr>sub-directories</nobr>.</p>
+
+<a name="cd"></a>
+
+<hr>
+
+<h2>cd</h2>
+
+<hr>
+
+<p>The 'cd' function displays or changes the current working directory, it
+also displays the name of the *<nobr>default-sf-dir</nobr>* directory, where
+Nyquist stores its sound files:</p>
+
+<pre class="example">
+> (cd)
+;; *default-sf-dir* = /tmp/
+;; working directory = /home/edgar
+NIL
+
+> (cd "test")
+;; directory changed to "test"
+;; *default-sf-dir* = /tmp/
+;; working directory = /home/edgar/test
+T
+
+> (cd "..")
+;; directory changed to "edgar"
+;; *default-sf-dir* = /tmp/
+;; working directory = /home/edgar
+T
+
+> (cd "foo")
+;; directory not changed, "foo" not found
+;; *default-sf-dir* = /tmp/
+;; working directory = /home/edgar
+NIL
+
+> (cd 123)
+;; directory not changed, 123 is not a string
+;; *default-sf-dir* = /tmp/
+;; working directory = /home/edgar
+NIL
+</pre>
+
+<p>The 'cd' function is intended for interactive use, in program code it's
+better to use the Nyquist <a href="../reference/setdir.htm">setdir</a>
+function.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">cd</font> (&optional dirname)
+ (let ((old-dir (setdir <font color="#880000">"."</font>))
+ (new-dir (when (stringp dirname) (setdir dirname))))
+ (when dirname
+ (if new-dir
+ (when (string/= old-dir new-dir)
+ (let ((string-end (length new-dir))
+ (subseq-start 0))
+ (dotimes (index string-end)
+ (when (char= (char new-dir index) <font color="#AA5500">*file-separator*</font>)
+ (setq subseq-start index)))
+ (incf subseq-start)
+ (format t <font color="#880000">";; directory changed to ~s~%"</font>
+ (if (< subseq-start string-end)
+ (subseq new-dir subseq-start)
+ (string <font color="#AA5500">*file-separator*</font>)))))
+ (format t <font color="#880000">";; directory not changed, ~s ~a~%"</font> dirname
+ (if (stringp dirname) <font color="#880000">"not found" "is not a string"</font>))))
+ (format t <font color="#880000">";; *default-sf-dir* = ~a~%"</font> <font color="#AA5500">*default-sf-dir*</font>)
+ (format t <font color="#880000">";; working directory = ~a~%"</font> (setdir <font color="#880000">"."</font>))
+ (when new-dir t)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="ls"></a>
+
+<hr>
+
+<h2>ls</h2>
+
+<hr>
+
+<p>The 'ls' function lists files and directories:</p>
+
+<pre class="example">
+> (ls)
+;;; /home/edgar/Downloads/nyquist/svn/nyquist
+;; advantages.txt cmt/ comp-ide.bat convert.dsp
+;; convert.dsw demos/ doc/ docsrc/
+;; fft/ ffts/ files.txt howtorelease.txt
+;; jny jnyqide.bat jnyqide/ lib/
+;; liblo/ license.txt lpc/ macosxproject/
+;; macproject/ Makefile misc/ nylsf/
+;; nyqide/ nyqsrc/ nyqstk/ nyquist.dsp
+;; nyquist.dsw nyquist.sln nyquist.vcproj nyqwin.dsp
+;; nyqwin.vcproj portaudio-oldv19/ portaudio/ portaudio_test/
+;; Readme.txt release.bat releasenyqide.bat releasenyqwin.bat
+;; runtime/ snd/ sys/ test/
+;; todo.txt tran/ xlisp/
+47
+</pre>
+
+<p>The algorithm to find the number of colums is
+<nobr>trial-and-error</nobr>, for example it starts with one column:</p>
+
+<pre class="example">
+<font color="#008844"><- maximum-width ->|</font>
+item-1
+item-2
+item-3
+item-4
+item-5
+</pre>
+
+<p>When no line was longer than the <nobr>maximum-width</nobr> the
+layout is saved and a new test is started with two columns:</p>
+
+<pre class="example">
+<font color="#008844"><- maximum-width ->|</font>
+item-1 item-2
+item-3 item-4
+item-5
+</pre>
+
+<p>When no line was longer than the <nobr>maximum-width</nobr> the
+layout is saved and a new test is started with three columns:</p>
+
+<pre class="example">
+<font color="#008844"><- maximum-width ->|</font>
+item-1 item-2 item-3
+</pre>
+
+<p>As soon as a line becomes longer than the <nobr>maximum-width</nobr>, the
+test is aborted and the saved layout from the previous run is used.</p>
+
+<p>The main reason why arrays are used instead of lists is that we need
+access to predefined numbers. With lists we always first need to test if an
+element exists because <nobr>non-existent</nobr> list elements are NIL and
+not numbers:</p>
+
+<pre class="example">
+(< (nth 3 '(1 2)) 0) => <font color="#AA0000">error: bad argument type - NIL</font>
+</pre>
+
+<p>It's also no good idea to use <a href="../reference/setf.htm">setf</a>
+with <nobr>non-existent</nobr> list elements:</p>
+
+<pre class="example">
+(setf (nth 2 nil) 'value) => VALUE
+(nth 2 nil) => <font color="#AA0000">error: bad argument type - NIL</font>
+</pre>
+
+<p><b>Caution:</b> The XLISP <a href="../reference/setf.htm">setf</a>
+special form does not signal an error if values are assigned to
+<nobr>non-existent</nobr> places.</p>
+
+<p>We use the Common Lisp 'incf' macro because the Nyquist
+<a href="../reference/incf.htm">incf</a> macro has no 'increment'
+argument:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:incf</font> (place &optional (increment 1))
+ `(setf ,place (+ ,place ,increment)))
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">ls</font> (&rest args)
+ (let* ((dirname (if (stringp (car args))
+ (prog1 (car args) (setq args (cdr args)))
+ (setdir ".")))
+ (show-all (car args))
+ (raw-list (listdir dirname)))
+ (cond ((null raw-list)
+ (format t <font color="#880000">";; directory ~s not found~%"</font> dirname))
+ ((<= (length raw-list) 2)
+ (format t <font color="#880000">";;; ~a~%"</font> dirname)
+ (format t <font color="#880000">";; [directory is empty]~%"</font>) 0)
+ (t
+ (format t <font color="#880000">";;; ~a~%"</font> dirname)
+ (let ((file-separator (string <font color="#AA5500">*file-separator*</font>))
+ (dir-list nil))
+ (dolist (item raw-list)
+ (when (or show-all (not (ls:hidden-p item)))
+ (if (listdir (strcat dirname file-separator item))
+ (push (strcat item <font color="#880000">"/"</font>) dir-list)
+ (push item dir-list))))
+ (ls:list-items (sort dir-list #'string-lessp)))))))
+
+(setq <font color="#AA5500">*ls-hidden-start*</font> (list <font color="#880000">"." "#"</font>))
+(setq <font color="#AA5500">*ls-hidden-end*</font> (list <font color="#880000">"~" "#"</font>))
+
+(defun <font color="#0000CC">ls:hidden-p</font> (string)
+ (let ((string-length (length string)))
+ (or (dolist (item <font color="#AA5500">*ls-hidden-start*</font> nil)
+ (let ((subseq-end (length item)))
+ (when (and (>= string-length subseq-end)
+ (string= item (subseq string 0 subseq-end)))
+ (return t))))
+ (dolist (item <font color="#AA5500">*ls-hidden-end*</font> nil)
+ (let ((subseq-start (- string-length (length item))))
+ (when (and (<= 0 subseq-start)
+ (string= item (subseq string subseq-start)))
+ (return t)))))))
+
+(defmacro <font color="#0000CC">ls:reset-array</font> (array)
+ (let ((index (gensym)))
+ `(dotimes (,index (length ,array))
+ (setf (aref ,array ,index) 0))))
+
+(defmacro <font color="#0000CC">ls:copy-array</font> (from-array to-array end)
+ (let ((index (gensym)))
+ `(dotimes (,index ,end)
+ (setf (aref ,to-array ,index)
+ (aref ,from-array ,index)))))
+
+(defun <font color="#0000CC">ls:fill-string</font> (length)
+ (let ((string <font color="#880000">""</font>))
+ (dotimes (i length)
+ (setq string (strcat string <font color="#880000">" "</font>)))
+ string))
+
+(defun <font color="#0000CC">ls:list-items</font> (item-list &optional (terminal-width 80))
+ (let* ((separator 2)
+ (width (- terminal-width 4))
+ (width-max (+ width separator))
+ (num-items (length item-list))
+ (num-columns 1) <font color="#008844">; number of columns</font>
+ (item-array (make-array num-items))
+ (length-array (make-array num-items))
+ (length-min width) <font color="#008844">; shortest item</font>
+ (length-max 0) <font color="#008844">; longest item</font>
+ (length-all 0) <font color="#008844">; all items + separators</font>
+ <font color="#008844">;; the maximum possible number of columns is</font>
+ <font color="#008844">;; width-max / (1 char + separator)</font>
+ (max-columns (/ width-max (1+ separator)))
+ (column-array (make-array max-columns)))
+
+ <font color="#008844">;; initialize the column-array</font>
+ (ls:reset-array column-array)
+
+ <font color="#008844">;; copy the items from the list into the item-array</font>
+ (let ((item-index 0))
+ (dolist (item item-list)
+ (setf (aref item-array item-index) item)
+ (incf item-index)))
+
+ <font color="#008844">;; find the length of all items and store them in the length-array</font>
+ (dotimes (item-index num-items)
+ (let ((length-item (length (aref item-array item-index))))
+ (setf (aref length-array item-index) length-item
+ length-all (+ length-all length-item separator)
+ length-min (min length-min length-item)
+ length-max (max length-max length-item))))
+
+ <font color="#008844">;; find the number and widths of the columns</font>
+ (cond ((<= length-all width-max)
+ <font color="#008844">;; if all items together fit into a single line</font>
+ (setq num-columns num-items)
+ (ls:copy-array length-array column-array num-items))
+ ((and (> num-items 1)
+ (<= (+ length-min length-max separator) width))
+ <font color="#008844">;; if there is more than one item and the</font>
+ <font color="#008844">;; longest + shortest item + separator fit into one line</font>
+ <font color="#008844">;; we start with two columns, one column is the fallback</font>
+ (incf num-columns)
+ <font color="#008844">;; the test-array must be 1+ because we need 1 failure-run</font>
+ (do ((test-array (make-array (1+ max-columns)))
+ (item-index 0 0))
+ ((progn
+ (ls:reset-array test-array)
+ <font color="#008844">;; loop until there are no more items in the list</font>
+ (do ((line-length 0 0))
+ ((>= item-index num-items))
+ <font color="#008844">;; compute a complete line</font>
+ (dotimes (column-index num-columns)
+ <font color="#008844">;; loop through all columns in the test-array</font>
+ (when (and (< item-index num-items)
+ (< (aref test-array column-index)
+ (aref length-array item-index)))
+ <font color="#008844">;; if there are still items in the list and the</font>
+ <font color="#008844">;; item is wider than the column, update the array</font>
+ (setf (aref test-array column-index)
+ (aref length-array item-index)))
+ <font color="#008844">;; compute the line-length from the value in the array</font>
+ (cl:incf line-length
+ (+ (aref test-array column-index) separator))
+ (incf item-index))
+ <font color="#008844">;; analyze the result from computing the line</font>
+ (cond ((> line-length width-max)
+ <font color="#008844">;; if the line is too long, abort completely, use</font>
+ <font color="#008844">;; the column-array values from the previous run</font>
+ (decf num-columns)
+ (return t)) <font color="#008844">; abort both 'do' loops</font>
+ ((>= item-index num-items)
+ <font color="#008844">;; if no items is left and no line was too long</font>
+ <font color="#008844">;; first save the test-array in the column-array</font>
+ (ls:copy-array test-array column-array num-columns)
+ <font color="#008844">;; then try again with one more column</font>
+ (incf num-columns)))))))))
+
+ <font color="#008844">;; print the items on the screen</font>
+ (do ((item-index 0)
+ (last-item (1- num-items))
+ (last-column (1- num-columns))
+ (line <font color="#880000">";; " ";; "</font>))
+ ((>= item-index num-items))
+ (dotimes (column-index num-columns)
+ <font color="#008844">;; loop through all columns</font>
+ (when (< item-index num-items)
+ <font color="#008844">;; if there are still items in the list</font>
+ (setq line
+ (if (and (< column-index last-column)
+ (< item-index last-item))
+ <font color="#008844">;; if not the last column and not the last item</font>
+ (strcat line (aref item-array item-index)
+ <font color="#008844">;; add a fill-string</font>
+ (let ((column (aref column-array column-index))
+ (item (aref length-array item-index)))
+ (ls:fill-string (+ (- column item) separator))))
+ <font color="#008844">;; if the last column or the last item</font>
+ (strcat line (aref item-array item-index))))
+ (incf item-index)))
+ <font color="#008844">;; display the line on the screen</font>
+ (format t <font color="#880000">"~a~%"</font> line))
+
+ <font color="#008844">;; return the number of items listed on the screen</font>
+ num-items))
+</pre>
+
+<p><b>Note:</b> The code works, but this section is still too much mess.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="hd"></a>
+
+<hr>
+
+<h2>hd</h2>
+
+<hr>
+
+<p>The 'hd' function prints the hexdump of a file on the screen:</p>
+
+<pre class="example">
+> (hd "/tmp/edgar-temp.wav")
+0000000000 52 49 46 46 ac 58 01 00 57 41 56 45 66 6d 74 20 RIFF.X..WAVEfmt
+0000000016 10 00 00 00 01 00 01 00 44 ac 00 00 88 58 01 00 ........D....X..
+0000000032 02 00 10 00 64 61 74 61 88 58 01 00 00 00 4a 04 ....data.X....J.
+0000000048 93 08 da 0c 1b 11 57 15 8b 19 b7 1d d7 21 ec 25 ......W......!.%
+0000000064 f3 29 eb 2d d3 31 a9 35 6c 39 1a 3d b3 40 35 44 .).-.1.5l9.=.@5D
+0000000080 9e 47 ee 4a 24 4e 3d 51 3a 54 19 57 d9 59 78 5c .G.J$N=Q:T.W.Yx\
+0000000096 f7 5e 54 61 8f 63 a6 65 99 67 67 69 10 6b 92 6c .^Ta.c.e.ggi.k.l
+0000000112 ee 6d 23 6f 31 70 16 71 d3 71 68 72 d4 72 17 73 .m#o1p.q.qhr.r.s
+0000000128 31 73 23 73 eb 72 8a 72 01 72 4f 71 75 70 73 6f 1s#s.r.r.rOqupso
+0000000144 49 6e f8 6c 80 6b e2 69 1f 68 36 66 29 64 f8 61 In.l.k.i.h6f)d.a
+0000000160 a5 5f 2f 5d 98 5a e2 57 0b 55 17 52 05 4f d8 4b ._/].Z.W.U.R.O.K
+0000000176 8f 48 2c 45 b1 41 1f 3e 76 3a b9 36 e8 32 05 2f .H,E.A.>v:.6.2./
+0000000192 11 2b 0e 27 fe 22 e0 1e b8 1a 86 16 4c 12 0c 0e .+.'."......L...
+0000000208 c7 09 7e 05 33 01 e9 fc 9f f8 57 f4 14 f0 d6 eb ..~.3.....W.....
+0000000224 a0 e7 72 e3 4e df 36 db 2b d7 2f d3 42 cf 67 cb ..r.N.6.+./.B.g.
+0000000240 9f c7 ea c3 4b c0 c3 bc 53 b9 fb b5 be b2 9d af ....K...S.......
+;; type "q" to quit or press Return to continue...
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">hd</font> (filename &key (start 0) end)
+ (cond
+ ((not (stringp filename))
+ (format t <font color="#880000">";; not a string ~s~%"</font> filename))
+ ((listdir filename)
+ (format t <font color="#880000">";; not a file ~s~%"</font> string))
+ ((or (not (integerp start)) (minusp start))
+ (format t <font color="#880000">";; not a non-negative integer ~s~%"</font> start))
+ ((and end (or (not (integerp end)) (minusp end)))
+ (format t <font color="#880000">";; not a non-negative integer ~s~%"</font> end))
+ ((and end (>= start end))
+ (format t <font color="#880000">";; :start ~s is greater then :end ~s~%"</font> start end))
+ (t (let ((file-stream (open-binary filename)))
+ (if (null file-stream)
+ (format t <font color="#880000">";; file not found ~s~%"</font> filename)
+ (unwind-protect
+ (hd:dump file-stream start end)
+ (when file-stream (close file-stream))))))))
+
+(defun <font color="#0000CC">hd:dump</font> (file-stream start end)
+ (let ((file-position (hd:skip file-stream start))
+ (break (+ start 255))
+ (end-of-file nil)
+ (end-of-dump nil))
+ (if (< file-position start)
+ (setq end-of-file t)
+ (flet ((read-eight-bytes (start-position)
+ (let (byte-list)
+ (dotimes (offset 8)
+ (let* ((position (+ start-position offset))
+ (read-p (and (<= start position)
+ (or (null end)
+ (>= end position))))
+ (byte (when read-p
+ (read-byte file-stream))))
+ (push byte byte-list)
+ (when byte (incf file-position))
+ (when (and read-p (null byte))
+ (setq end-of-file t))))
+ (reverse byte-list))))
+ (read-line)
+ (do ((line-start (* (/ start 16) 16) (+ line-start 16)))
+ ((or end-of-file end-of-dump))
+ (let* ((number (hd:line-number line-start))
+ (list-1 (read-eight-bytes line-start))
+ (list-2 (read-eight-bytes (+ line-start 8)))
+ (bytes-1 (hd:byte-string list-1))
+ (bytes-2 (hd:byte-string list-2))
+ (chars (hd:char-string (append list-1 list-2))))
+ (format t <font color="#880000">"~a ~a ~a ~a~%"</font> number bytes-1 bytes-2 chars)
+ (when (and end (> file-position end))
+ (setq end-of-dump t))
+ (when (> file-position break)
+ (format t <font color="#880000">";; type \"q\" to quit or press Return to continue... "</font>)
+ (if (string-equal "q" (read-line))
+ (setq end-of-dump t)
+ (setq break (+ break 256))))))))
+ (when (and end (>= file-position end))
+ (format t <font color="#880000">";; reached specified :end at byte number ~a~%"</font> end))
+ (when end-of-file
+ (format t <font color="#880000">";; end of file at byte number ~a~%"</font> file-position))))
+
+(defun <font color="#0000CC">hd:line-number</font> (integer)
+ (progv '(<font color="#AA5500">*integer-format*</font>) '(<font color="#880000">"%.10d"</font>)
+ (format nil <font color="#880000">"~s"</font> integer)))
+
+(defun <font color="#0000CC">hd:byte-string</font> (byte-list)
+ (let ((string <font color="#880000">""</font>))
+ (dolist (byte byte-list)
+ (setq string (strcat string (if byte
+ (progv '(<font color="#AA5500">*integer-format*</font>) '(<font color="#880000">"%.2x"</font>)
+ (format nil <font color="#880000">"~s "</font> byte))
+ <font color="#880000">" "</font>))))
+ (subseq string 0 (1- (length string)))))
+
+(defun <font color="#0000CC">hd:char-string</font> (byte-list)
+ (let ((string <font color="#880000">""</font>))
+ (dolist (byte byte-list)
+ (setq string (strcat string (if byte
+ (if (<= 32 byte 126)
+ (string byte)
+ <font color="#880000">"."</font>)
+ <font color="#880000">" "</font>))))
+ string))
+
+(defun <font color="#0000CC">hd:skip</font> (file-stream offset)
+ (if (= offset 0)
+ offset
+ (let ((count 0))
+ (format t <font color="#880000">";; skipping ~a bytes...~%"</font> offset)
+ (dotimes (ignore offset)
+ (if (read-byte file-stream)
+ (incf count)
+ (return)))
+ count)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/tutorials/tutorials.htm b/docsrc/xlisp/xlisp-doc/tutorials/tutorials.htm new file mode 100644 index 0000000..0e7ecf5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/tutorials/tutorials.htm @@ -0,0 +1,28 @@ +<html><head><title>Tutorials</title></head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+Tutorials |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Tutorials</h1>
+
+<hr>
+
+<ul>
+<li><nobr><a href="nyquist.htm">Nyquist</a> - things that may help in practical work</nobr></li>
+<li><nobr><a href="lisp-hints.htm">Lisp Hints</a> - Lisp and XLISP basics</nobr></li>
+<li><nobr><a href="xlisp-objects.htm">XLISP Object Primer</a> - by Tim I Mikkelsen</nobr></li>
+<li><nobr><a href="file-io.htm">File I/O Examples</a> - by David Betz</nobr></li>
+<li><nobr><a href="binary-io.htm">Binary File I/O</a></nobr></li>
+<li><nobr><a href="shell-utilities.htm">Shell Utilities</a></nobr></li>
+<li><nobr><a href="environment.htm">Environment</a></nobr></li>
+<li><nobr><a href="lisp-faq.htm">Lisp FAQ</a></nobr></li>
+</ul>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/tutorials/xlisp-objects.htm b/docsrc/xlisp/xlisp-doc/tutorials/xlisp-objects.htm new file mode 100644 index 0000000..1b02a86 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/tutorials/xlisp-objects.htm @@ -0,0 +1,839 @@ +<html><head><title>XLISP Objects Primer</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>XLISP Objects Primer</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#1">Programming Styles</a></nobr></li>
+<li><nobr><a href="#2">Object Oriented Programming</a></nobr></li>
+<li><nobr><a href="#3">Xlisp Object Terminology</a></nobr></li>
+<li><nobr><a href="#4">Sending Messages</a></nobr></li>
+<li><nobr><a href="#5">Classes</a></nobr></li>
+<li><nobr><a href="#6">A Better Class Example</a></nobr></li>
+<li><nobr><a href="#7">Instances</a></nobr></li>
+<li><nobr><a href="#8">Methods</a></nobr></li>
+<li><nobr><a href="#9">Sending Messages To A Superclass</a></nobr></li>
+<li><nobr><a href="#10">Object And Class</a></nobr></li>
+<li><nobr><a href="#11">Objects Example</a></nobr></li>
+</ol>
+
+<p>This tutorial is adapted from a '<nobr>XLISPOOP.DOC</nobr>' document with
+the following copyright:</p>
+
+<p><div class="box">
+
+<p>XLisp 2.0 Objects Primer by Tim I Mikkelsen - February 3, 1990</p>
+
+<blockquote>
+
+<p> Copyright (c) 1990 by Tim I. Mikkelsen. All Rights Reserved. No part of this
+document may be copied, reproduced or translated for commercial use without
+prior written consent of the author. Permission is granted for non-commercial
+use as long as this notice is left intact.
+
+<p> One of the features in the design of XLISP is object-oriented programming.
+This primer is intended to serve as a very brief introduction to the object
+facilities of the XLISP 2.0 dialect of LISP. Note that the object features of
+XLISP are not based on other existing object definitions in other LISP dialects.
+If you find problems in the primer, I'd appreciate hearing. </p>
+
+</blockquote>
+
+<p>Tim Mikkelsen, (tim@hpfcbig.SDE.HP.COM), 4316 Picadilly Drive, Fort Collins,
+Colorado 80526</p>
+
+</div></p>
+
+<a name="1"></a>
+
+<hr>
+
+<h2>1 Programming Styles</h2>
+
+<hr>
+
+<p>There are many programming models, some of <nobr>them are:</nobr></p>
+
+<ul>
+<li>procedural</li>
+<li>functional</li>
+<li><nobr>rule-based</nobr></li>
+<li>declarative</li>
+<li><nobr>object-oriented</nobr></li>
+</ul>
+
+<p>A language can have aspects of one or many of these programming
+models.</p>
+
+<p><div class="box">
+
+<dl>
+
+<dt><p><b>Procedure-Oriented</b></p></dt>
+
+<dd><p>The programming paradigm most people are familiar with is the
+procedural style. The primitives in procedural programming are subroutines
+and data structures. Through these primitives, programmers have some limited
+abilities to share programs and program fragments. <nobr>C and</nobr> Pascal
+are examples of procedural languages. Some procedural languages <nobr>[such
+as</nobr> Modula <nobr>and ADA]</nobr> have extensions that provide for
+better sharing <nobr>of code</nobr>.</p></dd>
+
+<dt><p><b>Object-Oriented</b></p></dt>
+
+<dd><p><nobr>Object-oriented</nobr> programming is based on the primitives
+of objects, classes and messages. Objects are defined in terms of classes.
+Actions occur by sending a message to an object. <nobr>An object's</nobr>
+definition can be inherited from more general classes.
+<nobr>Objective-C</nobr> and C++ both are <nobr>object-oriented</nobr>
+dialects of the <nobr>C language</nobr>. <nobr>Many dialects</nobr> of Lisp
+have some <nobr>object-oriented</nobr> extension [Flavors, <nobr>Common
+LOOPS</nobr>, CLOS and others]. There currently is standards work proceeding
+to add <nobr>object-oriented</nobr> programming to <nobr>Common
+Lisp</nobr>.</p></dd>
+
+</dl>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="2"></a>
+
+<hr>
+
+<h2>2 Object Oriented Programming</h2>
+
+<hr>
+
+<p>The <nobr>object-oriented</nobr> programming model is based around the
+concepts of objects, classes and messages. <nobr>An object</nobr> is
+essentially a black box that contains internal state information. <nobr>You
+send</nobr> an object a message which causes the object to perform some
+operation. Objects are defined and described through classes.</p>
+
+<p>One aspect of an object is that you do not have to know what is inside or
+how it works to be able to <nobr>use it</nobr>. From a programming point of
+view, this is very handy. <nobr>You can</nobr> develop a series of objects
+for someone to use. <nobr>If you</nobr> need to change what goes on inside,
+the users of the objects should be unaware.</p>
+
+<p>Another aspect of objects is that of inheritance. <nobr>You can</nobr>
+build up new classes from existing classes by inheriting the existing
+class's functionality and then extending the new definition. For example,
+you can define a 'tool' class with various attributes and then go about
+creating object instances like '<nobr>tool-1</nobr>', '<nobr>tool-2</nobr>',
+and <nobr>so on</nobr>. <nobr>You can</nobr> also create new
+<nobr>sub-classes</nobr> of the 'tool' class like '<nobr>power-tool</nobr>'.
+<nobr>This is</nobr> also very handy because you don't have to
+<nobr>re-implement</nobr> something if you can build it up from
+<nobr>existing code</nobr>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="3"></a>
+
+<hr>
+
+<h2>3 Xlisp Object Terminology</h2>
+
+<hr>
+
+<p>There are many different languages with <nobr>object-oriented</nobr>
+extensions and facilities. <nobr>The terminology</nobr>, operations and
+styles of these are very different. Some of the main definitions for XLISP's
+<nobr>object-oriented</nobr> extensions are:</p>
+
+<p><div class="box">
+
+<dl>
+
+<dt><p><nobr><b>object data type</b></nobr></p></dt>
+
+<dd><p>The <a href="../reference/object.htm">object</a> data type is a
+<nobr>built-in</nobr> data type of XLISP. Members of the object data type
+are object instances and classes.</p></dd>
+
+<dt><p><nobr><b>object instances</b></nobr></p></dt>
+
+<dd><p>An 'object instance' is a composite structure that contains internal
+state information, methods [the code which respond to messages], <nobr>a
+pointer</nobr> to the object instance's defining class and a pointer to the
+object's <nobr>super-class</nobr>. XLISP contains no <nobr>built-in</nobr>
+object instances.</p></dd>
+
+<dt><p><nobr><b>class objects</b></nobr></p></dt>
+
+<dd><p>A <a href="../reference/class.htm">class</a> object is, essentially,
+the template for defining the derived object instances. <nobr>A class
+object</nobr>, although used differently from a simple object instance, is
+structurally a member of the object data type. <nobr>It also</nobr> contains
+the linking mechanism that allows you to build class hierarchies
+<nobr>[sub-classes</nobr> and <nobr>super-classes]</nobr>. XLISP contains
+two <nobr>built-in</nobr> class objects, 'object' and 'class'.</p></dd>
+
+<dt><p><nobr><b>message selector</b></nobr></p></dt>
+
+<dd><p>The 'message selector' is the symbol that is used to select a
+particular action [method] from the object.</p></dd>
+
+<dt><p><b>message</b></p></dt>
+
+<dd><p>The 'message' is the combination of the message selector and the data
+<nobr>[if any]</nobr> to be sent to the object.</p></dd>
+
+<dt><p><b>method</b></p></dt>
+
+<dd><p>The 'method' is the actual code that gets executed when the object
+receives the message.</p></dd>
+
+</dl>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="4"></a>
+
+<hr>
+
+<h2>4 Sending Messages</h2>
+
+<hr>
+
+<p>The mechanism for sending messages to XLISP objects is via the
+<a href="../reference/send.htm">send</a> function. <nobr>It takes</nobr>
+an object, a message selector and various optional arguments [depending on
+the message selector].</p>
+
+<p>The way that a user creates a new object is to
+<a href="../reference/send.htm">send</a> a
+<a href="../reference/keyword-new.htm">:new</a> message to a previously
+defined class. <nobr>The result</nobr> of this
+<a href="../reference/send.htm">send</a> will return an object, so this is
+normally preceded by <nobr>a
+<a href="../reference/setq.htm">setq</a></nobr>.</p>
+
+<pre class="example">
+> (setq my-object (send object :new))
+#<Object: #2e100>
+</pre>
+
+<p><div class="box">
+
+<p><nobr>The examples</nobr> are similar to what you should see on your
+computer screen. <nobr>The '>'</nobr> is the normal XLISP prompt, the
+characters that follow the prompt is what you type in to try the examples.
+Note that XLISP prints objects together with their internal pointer, like
+#2e100 in the example above. These <nobr>#ID numbers</nobr> may not match
+with the numbers you see on the screen if you try the examples, but this is
+not an error.</nobr></p>
+
+</div></p>
+
+<p> The object created above is of limited value. Most often, you create a
+'class' object and then you create instances of that class. <nobr>So
+in</nobr> the following example, a class called '<nobr>my-class</nobr>' is
+created that inherits its definition from the a <nobr>built-in</nobr> <a
+href="../reference/class.htm">class</a> definition. Then two instances are
+created of the new class:</p>
+
+<pre class="example">
+> (setq my-class (send class :new '()))
+#<Object: #27756>
+
+> (setq my-instance (send my-class :new))
+#<Object: #27652>
+
+> (setq another-instance (send my-class :new))
+#<Object: #275da>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="5"></a>
+
+<hr>
+
+<h2>5 Classes</h2>
+
+<hr>
+
+<p> In the examples above, a <a href="../reference/keyword-new.htm">:new</a>
+message was used to create an object. <nobr>The message</nobr> used to see
+what is in an object is the
+<a href="../reference/keyword-show.htm">:show</a> message:</p>
+
+<pre class="example">
+> (send my-class :show)
+Object is #<Object: #27756>, Class is #<Object: #23fe2>
+ MESSAGES = NIL
+ IVARS = NIL
+ CVARS = NIL
+ CVALS = NIL
+ SUPERCLASS = #<Object: #23fd8>
+ IVARCNT = 0
+ IVARTOTAL = 0
+#<Object: #27756>
+</pre>
+
+<p> From the display of the 'my-class' object you can see there are a
+variety of components. The components of a class are:</p>
+
+<p><div class="box">
+
+<dl>
+
+<dt><p><nobr><b>class pointer</b></nobr></p></dt>
+
+<dd><p>This pointer shows to what class the object [instance or class]
+belongs. For a class, this always points to the <nobr>built-in</nobr> object
+<a href="../reference/class.htm">class</a>. This is also true of the
+<a href="../reference/class.htm">class</a> object, its class pointer points
+to itself.</p></dd>
+
+<dt><p><nobr><b>superclass pointer</b></nobr></p></dt>
+
+<dd><p>This pointer shows what the next class up the class <nobr>hierarchy
+is</nobr>. <nobr>If the</nobr> user does not specify what class is the
+superclass, it will point to the built-in <nobr>class
+<a href="../reference/object.htm">object</a></nobr>.</p></dd>
+
+<dt><p><b>messages</b></p></dt>
+
+<dd><p>This component shows what messages are allowed for the class, and the
+description of the method that will be used. <nobr>If the</nobr> method is
+<nobr>system-defined</nobr>, it will show up in the <nobr>form
+of:</nobr></p>
+
+<pre class="example">
+#<Subr-: #18b98>
+</pre>
+
+<p>Remember that the class hierarchy [through the superclass pointer] is
+searched if the requested message is not found in the class.</p></dd>
+
+<dt><p><nobr><b>instance variables</b></nobr></p></dt>
+
+<dd><p>The IVARS component lists what instance variables will be created
+when an object instance is created. <nobr>If no</nobr> instances of the
+class exist, there are no instance variables. <nobr>If there</nobr> are
+<nobr>5 instances</nobr> of a class, there are <nobr>5 complete</nobr> and
+different groups of the instance variables.</p></dd>
+
+<dt><p><nobr><b>class variables and values</b></nobr></p></dt>
+
+<dd><p>The CVARS component lists what class variables exist within the
+class. The CVALS component shows what the current values of the variables
+are. Class variables are used to hold state information about a class. There
+will be one of each of the class variables, independent of the number of
+instances of the class created.</p></dd>
+
+</dl>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="6"></a>
+
+<hr>
+
+<h2>6 A Better Class Example</h2>
+
+<hr>
+
+<p> The example shown in the previous section does work, but the class and
+instances created don't really do anything of interest. The following
+example sets up a tool class and creates some tool instances:</p>
+
+<pre class="example">
+> (setq my-tools (send class :new '(power moveable operation)))
+#<Object: #277a6>
+
+> (send my-tools :answer :isnew '(pow mov op)
+ '((setq power pow moveable mov operation op))
+#<Object: #277a6>
+
+> (setq drill (send my-tools :new 'AC t 'holes))
+#<Object: #2ddbc>
+
+> (setq hand-saw (send my-tools :new 'none t 'cuts))
+#<Object: #2dc40>
+
+> (setq table-saw (send my-tools :new 'AC nil 'cuts))
+#<Object: #2db00>
+</pre>
+
+<p>A class of objects called '<nobr>my-tools</nobr>' and three instances
+were created:</p>
+
+<p><nobr> <img alt="[Figure 1]" src="xobj-1.png"></nobr></p>
+
+<p>First the class '<nobr>my-tools</nobr>' was created by sending the
+<a href="../reference/keyword-new.htm">:new</a> message to the
+<nobr>built-in</nobr> <a href="../reference/class.htm">class</a> object.
+Then, within the '<nobr>my-tool</nobr>' class, three instances called
+'drill', '<nobr>hand-saw</nobr>' and '<nobr>table-saw</nobr>' were
+created by sending the <a href="../reference/keyword-new.htm">:new</a>
+message to the '<nobr>my-tools</nobr>' class. Notice the three parameters
+following the message selector. The instance variables are initialized
+from these parameters by the :isnew method, inherited from the
+'<nobr>my-tools</nobr>' class at the time when the instances were created.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="7"></a>
+
+<hr>
+
+<h2>7 Instances</h2>
+
+<hr>
+
+<p>The following is a display of the contents of some of the instances
+created above, where the XLISP object #ID numbers had been replaced by the
+respective class and instance names:</p>
+
+<pre class="example">
+> (send drill :show)
+Object is #<Object: #[<font color="#0066CC">drill</font>]>, Class is #<Object: #[<font color="#0066CC">my-tools</font>]>
+ POWER = AC
+ MOVEABLE = T
+ OPERATION = HOLES
+#<Object: #[<font color="#0066CC">drill</font>]>
+
+> (send hand-saw :show)
+Object is #<Object: #[<font color="#0066CC">hand-saw</font>]>, Class is #<Object: #[<font color="#0066CC">my-tools</font>]>
+ POWER = NONE
+ MOVEABLE = T
+ OPERATION = CUTS
+#<Object: #[<font color="#0066CC">hand-saw</font>]>
+</pre>
+
+<p>From the display of these instances you can see there are some
+components and values. The components of an instance are:</p>
+
+<p><div class="box">
+
+<dl>
+
+<dt><p><nobr><b>class pointer</b></nobr></p></dt>
+
+<dd><p>This pointer shows to which class the current object instance
+belongs. It is through this link that the system finds the methods to
+execute for the received messages.</p></dd>
+
+<dt><p><nobr><b>instance variables and values</b></nobr></p></dt>
+
+<dd><p>The variables existing within the instance are shown together with
+their values. Instance Variables are used to hold state information for each
+instance. There will be a group of instance variables for each
+instance.</p></dd>
+
+</dl>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="8"></a>
+
+<hr>
+
+<h2>8 Methods</h2>
+
+<hr>
+
+<p>There have been a few of the messages and methods in XLISP shown to this
+point like <a href="../reference/keyword-new.htm">:new</a> and
+<a href="../reference/keyword-show.htm">:show</a>. The following are the
+methods built into XLISP:</p>
+
+<p><div class="box">
+
+<dl>
+
+<dt><p><b>:answer</b></p></dt>
+
+<dd><p>The <a href="../reference/keyword-answer.htm">:answer</a> method
+allows you to define or change methods within a class.</p></dd>
+
+<dt><p><b>:class</b></p></dt>
+
+<dd><p>The <a href="../reference/keyword-class.htm">:class</a> method
+returns the class of an object.</p></dd>
+
+<dt><p><b>:isnew</b></p></dt>
+
+<dd><p>The <a href="../reference/keyword-.htm">:isnew</a> method causes an
+instance to run its initialization code. When the
+<a href="../reference/keyword-.htm">:isnew</a> method is run on a class, it
+resets the class state. This allows you to <nobr>re-define</nobr> instance
+variables, class <nobr>variables, etc.</nobr></p></dd>
+
+<dt><p><b>:new</b></p></dt>
+
+<dd><p>The <a href="../reference/keyword-new.htm">:new</a> method allows you
+to create an instance when the
+<a href="../reference/keyword-new.htm">:new</a> message is sent to a
+<nobr>user-defined</nobr> class. The
+<a href="../reference/keyword-new.htm">:new</a> method allows you to create
+a new class when the <a href="../reference/keyword-new.htm">:new</a> message
+is sent to the
+<nobr>built-in <a href="../reference/class.htm">class</a></nobr>.</p></dd>
+
+<dt><p><b>:show</b></p></dt>
+
+<dd><p>The <a href="../reference/keyword-show.htm">:show</a> method displays the instance or class.</p></dd>
+
+<dt><p><b>:isa</b></p></dt>
+
+<dd><p>The <a href="../reference/keyword-isa.htm">:isa</a> method tests if
+an object inherits from a class.</p></dd>
+
+</dl>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="9"></a>
+
+<hr>
+
+<h2>9 Sending Messages To A Superclass</h2>
+
+<hr>
+
+<p> In addition to the <a href="../reference/send.htm">send</a> function,
+there is another function called
+<nobr><a href="../reference/send-super.htm">send-super</a></nobr>. The
+<nobr><a href="../reference/send-super.htm">send-super</a></nobr>
+function causes the specified message to be performed by the superclass
+method. This is a mechanism to allow chaining of methods in a class
+hierarchy. This chaining behavior can be achieved by creating a method for a
+class with the <a href="../reference/keyword-answer.htm">:answer</a>
+message. Within the body of the method, you include a
+<nobr><a href="../reference/send-super.htm">send-super</a></nobr> form. This
+function is allowed only inside the execution of a method of an object.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="10"></a>
+
+<hr>
+
+<h2>10 Object And Class</h2>
+
+<hr>
+
+<p>The definition of the built-in class 'object' is:</p>
+
+<pre class="example">
+> (send object :show)
+Object is #<Object: #[<font color="#0066CC">built-in-object</font>]>, Class is #<Object: #[<font color="#0066CC">built-in-class</font>]>
+ MESSAGES = ((:ISA . #<Subr-: #[<font color="#0000CC">built-in-isa-method</font>]>)
+ (:SHOW . #<Subr-: #[<font color="#0000CC">built-in-show-method</font>]>)
+ (:CLASS . #<Subr-: #[<font color="#0000CC">built-in-class-method</font>]>)
+ (:ISNEW . #<Subr-: #[<font color="#0000CC">built-in-isnew-method</font>]>))
+ IVARS = NIL
+ CVARS = NIL
+ CVALS = NIL
+ SUPERCLASS = NIL <font color="#008844">; no superclass</font>
+ IVARCNT = 0
+ IVARTOTAL = 0
+#<Object: #[<font color="#0066CC">built-in-object</font>]>
+</pre>
+
+<p> Note that 'object' is a class, as opposed to an 'instance-style' object.
+'object' has no superclass, it is the top or root of the class hierarchy.
+'object's class is 'class'. </p>
+
+<pre class="example">
+> (send class :show)
+Object is #<Object: #[<font color="#0066CC">built-in-class</font>]>, Class is #<Object: #[<font color="#0066CC">built-in-class</font>]>
+ MESSAGES = ((:ANSWER . #<Subr-: #[<font color="#0000CC">built-in-answer-method</font>]>)
+ (:ISNEW . #<Subr-: #[<font color="#0000CC">built-in-isnew-method</font>]>)
+ (:NEW . #<Subr-: #[<font color="#0000CC">built-in-new-method</font>]>))
+ IVARS = (MESSAGES IVARS CVARS CVALS SUPERCLASS IVARCNT IVARTOTAL)
+ CVARS = NIL
+ CVALS = NIL
+ SUPERCLASS = #<Object: #[<font color="#0066CC">built-in-object</font>]>
+ IVARCNT = 7
+ IVARTOTAL = 7
+#<Object: #[<font color="#0066CC">built-in-class</font>]>
+</pre>
+
+<p>'class' has a superclass of 'object'. It's class is itself, 'class'.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="11"></a>
+
+<hr>
+
+<h2>11 Objects Example</h2>
+
+<hr>
+
+<p> The following is an example, using the idea of tools again. <nobr>It
+contains</nobr> a hierarchy of tool classes. <nobr>The top</nobr> of the
+class hierarchy is 'tools'. '<nobr>hand-tools</nobr>' and
+'<nobr>shop-tools</nobr>' are <nobr>sub-classes</nobr> of 'tools'. The
+example creates instances of these <nobr>sub-classes</nobr>. <nobr>It
+is</nobr> possible to extend this example in various ways. One obvious
+extension would be to create a third tier of classes under
+'<nobr>hand-tools</nobr>' that could contain classes like drills,
+screwdrivers, pliers and <nobr>so on</nobr>. </p>
+
+<pre class="example">
+<font color="#008844">;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;</font>
+<font color="#008844">;;</font>
+<font color="#008844">;; Define the superclasses and classes</font>
+<font color="#008844">;;</font>
+<font color="#008844">;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;</font>
+<font color="#008844">;;</font>
+<font color="#008844">;; make TOOLS superclass</font>
+<font color="#008844">;;</font>
+<font color="#008844">;; with a different :ISNEW method</font>
+<font color="#008844">;; added methods are :BORROW and :RETURN</font>
+<font color="#008844">;;</font>
+<font color="#008844">;; class variables NUMBER contains # of tool instances</font>
+<font color="#008844">;; ACTIVE-LIST contains list of current objects</font>
+<font color="#008844">;;</font>
+<font color="#008844">;; instance variables POWER list - (AC BATTERY HAND)</font>
+<font color="#008844">;; MOVEABLE CAN-CARRY or CAN-ROLL or FIXED</font>
+<font color="#008844">;; OPERATIONS list</font>
+<font color="#008844">;; MATERIAL list - (WOOD METAL PLASTIC ...)</font>
+<font color="#008844">;; PIECES list</font>
+<font color="#008844">;; LOCATION HOME or person's name</font>
+<font color="#008844">;;</font>
+
+(setq tools (send class :new '(power moveable operations
+ material pieces location)
+ '(number active-list)))
+
+(send tools :answer :isnew '()
+ '((setq number (if (null number) 1 (1+ number))
+ active-list (cons self active-list)
+ location 'home)))
+
+(send tools :answer :borrow '(by-who)
+ '((if (eq location 'home)
+ (setq location by-who)
+ (print <font color="#880000">"you can't"</font>))))
+
+(send tools :answer :return '()
+ '((if (eq location 'home)
+ (print <font color="#880000">"got it already"</font>)
+ (setq location 'home))))
+
+<font color="#008844">;; make HAND-TOOLS class</font>
+<font color="#008844">;; - with a different :ISNEW method</font>
+<font color="#008844">;; - new instance variable WEIGHT = <number> of pounds</font>
+<font color="#008844">;; - the rest is inherited from TOOLS</font>
+
+(setq hand-tools (send class :new '(weight) '() tools))
+
+(send hand-tools :answer :isnew '(pow op mat parts w-in)
+ '((setq power pow
+ moveable 'can-carry
+ operations op
+ material mat
+ pieces parts
+ weight w-in)
+ (send-super :isnew)))
+
+<font color="#008844">;; make SHOP-TOOLS class</font>
+<font color="#008844">;; - with a different :ISNEW method</font>
+<font color="#008844">;; - no new instance variables</font>
+<font color="#008844">;; - the rest is inherited from TOOLS</font>
+
+(setq shop-tools (send class :new '() '() tools))
+
+(send shop-tools :answer :isnew '(pow mov op mat parts)
+ '((setq power pow
+ moveable mov
+ operations op
+ material mat
+ pieces parts)
+ (send-super :isnew)))
+
+<font color="#008844">;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;</font>
+<font color="#008844">;;</font>
+<font color="#008844">;; Create instances of various tool classes</font>
+<font color="#008844">;;</font>
+<font color="#008844">;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;</font>
+
+(setq hand-drill (send hand-tools :new <font color="#008844">; make an instance - HAND-DRILL</font>
+ '(ac)
+ '(drill polish grind screw)
+ '(wood metal plastic)
+ '(drill drill-bits screw-bits buffer)
+ '2.5))
+
+(setq table-saw (send shop-tools :new <font color="#008844">; make an instance - TABLE-SAW</font>
+ '(ac)
+ 'fixed
+ '(rip cross-cut)
+ '(wood plastic)
+ '(saw blades fence)))
+
+(setq radial-arm (send shop-tools :new <font color="#008844">; make an instance = RADIAL-ARM</font>
+ '(ac)
+ 'can-roll
+ '(rip cross-cut)
+ '(wood plastic)
+ '(saw blades dust-bag)))
+</pre>
+
+<p>The following session shows how to use the tool definitions from the
+code above:</p>
+
+<pre class="example">
+> (send hand-drill :borrow 'fred)
+FRED
+
+> (send table-saw :return)
+"got it already"
+"got it already"
+
+> (send hand-drill :borrow 'joe)
+"you can't"
+"you can't"
+
+> (send hand-drill :return)
+HOME
+</pre>
+
+<p>Fred was able to borrow the '<nobr>hand-drill</nobr>'. When an attempt
+was made to return the '<nobr>table-saw</nobr>', it was already at home.
+<nobr>A second</nobr> attempt to borrow the '<nobr>hand-drill</nobr>'
+indicated that <nobr>"you can't"</nobr> because it was already
+<nobr>lent out</nobr>. Lastly, the '<nobr>hand-drill</nobr>' was returned
+successfully. <nobr>[Note that</nobr> the <nobr>"got it
+already"</nobr> and <nobr>"you can't"</nobr> strings show up
+twice in the display because the methods both print and return the
+string.)</p>
+
+<p>The following example shows the structure of the 'tools' object with the
+XLISP #ID numbers replaced by the related class and method names:</p>
+
+<pre class="example">
+> (send tools :show)
+Object is #<Object: #[<font color="#0066CC">tools</font>]>, Class is #<Object: #[<font color="#0066CC">class</font>]>
+ MESSAGES = ((:RETURN . #<Closure-:RETURN: #[<font color="#0000CC">tools-return-method</font>]>)
+ (:BORROW . #<Closure-:BORROW: #[<font color="#0000CC">tools-borrow-method</font>]>)
+ (:ISNEW . #<Closure-:ISNEW: #[<font color="#0000CC">tools-isnew-method</font>]>))
+ IVARS = (POWER MOVEABLE OPERATIONS MATERIAL PIECES LOCATION)
+ CVARS = (NUMBER ACTIVE-LIST)
+ CVALS = #(3 (#<Object: #[<font color="#0066CC">radial-arm</font>]>
+ #<Object: #[<font color="#0066CC">table-saw</font>]>
+ #<Object: #[<font color="#0066CC">hand-drill</font>]>))
+ SUPERCLASS = #<Object: #[<font color="#0066CC">object</font>]>
+ IVARCNT = 6
+ IVARTOTAL = 6
+#<Object: #[<font color="#0066CC">tools</font>]>
+</pre>
+
+<p>The two 'tools' sub-classes 'hand-tools' and 'shop-tools' structure looks
+like:</p>
+
+<pre class="example">
+> (send hand-tools :show)
+Object is #<Object: #[<font color="#0066CC">hand-tools</font>]>, Class is #<Object: #[<font color="#0066CC">class</font>]>
+ MESSAGES = ((:ISNEW . #<Closure-:ISNEW: #[<font color="#0000CC">hand-tools-isnew-method</font>]>))
+ IVARS = (WEIGHT)
+ CVARS = NIL
+ CVALS = NIL
+ SUPERCLASS = #<Object: #[<font color="#0066CC">tools</font>]>
+ IVARCNT = 1
+ IVARTOTAL = 7
+#<Object: #[<font color="#0066CC">hand-tools</font>]>
+
+> (send shop-tools :show)
+Object is #<Object: #[<font color="#0066CC">shop-tools</font>]>, Class is #<Object: #[<font color="#0066CC">class</font>]>
+ MESSAGES = ((:ISNEW . #<Closure-:ISNEW: #[<font color="#0000CC">shop-tools-isnew-method</font>]>))
+ IVARS = NIL
+ CVARS = NIL
+ CVALS = NIL
+ SUPERCLASS = #<Object: #[<font color="#0066CC">tools</font>]>
+ IVARCNT = 0
+ IVARTOTAL = 6
+#<Object: #[<font color="#0066CC">shop-tools</font>]>
+</pre>
+
+<p>The class 'hand-tools' has an instance 'hand-drill' which looks like:</p>
+
+<pre class="example">
+> (send hand-drill :show)
+Object is #<Object: #[<font color="#0066CC">hand-drill</font>]>, Class is #<Object: #[<font color="#0066CC">hand-tools</font>]>
+ WEIGHT = 2.5
+ POWER = (AC)
+ MOVEABLE = CAN-CARRY
+ OPERATIONS = (DRILL POLISH GRIND SCREW)
+ MATERIAL = (WOOD METAL PLASTIC)
+ PIECES = (DRILL DRILL-BITS SCREW-BITS BUFFER)
+ LOCATION = HOME
+#<Object: #[<font color="#0066CC">hand-drill</font>]>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="tutorials.htm">Tutorials</a> |
+<a href="../examples/examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
\ No newline at end of file diff --git a/docsrc/xlisp/xlisp-doc/tutorials/xobj-1.png b/docsrc/xlisp/xlisp-doc/tutorials/xobj-1.png Binary files differnew file mode 100644 index 0000000..b22d557 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/tutorials/xobj-1.png diff --git a/docsrc/xlisp/xlisp-no-sal.mss b/docsrc/xlisp/xlisp-no-sal.mss new file mode 100644 index 0000000..ee48721 --- /dev/null +++ b/docsrc/xlisp/xlisp-no-sal.mss @@ -0,0 +1,3339 @@ +@define(codef, FaceCode T, size 11) +@comment{In my original scribe conversion of the ascii xlisp documentation, I used + times roman fonts for xlisp function names and code text in general. To be + consistent with Nyquist documentation, I have changed the code font to xlcode + which is defined here. If this turns out to be a problem, redefine xlcode to + use the regular FaceCode. -RBD} +@define(xlcode, FaceCode T, size 11) +@textform(pragma=[]) +@section(Introduction) + XLISP is an experimental programming language combining some of + the features of Common Lisp with an object-oriented extension + capability. It was implemented to allow experimentation with + object-oriented programming on small computers. + + Implementations of XLISP run on virtually every operating system. + XLISP is completely written in the programming language + C and is easily extended with user written built-in functions + and classes. It is available in source form to non-commercial + users. + + Many Common Lisp functions are built into XLISP. In addition, + XLISP defines the objects Object and Class as primitives. + Object is the only class that has no superclass and hence is + the root of the class hierarchy tree. Class is the class of + which all classes are instances (it is the only object that is + an instance of itself). + + This document is a brief description of XLISP. It assumes some + knowledge of LISP and some understanding of the concepts of + object-oriented programming. + + I recommend the book @i(Lisp) by Winston and Horn and published by + Addison Wesley for learning Lisp. The first edition of this + book is based on MacLisp and the second edition is based on + Common Lisp. + + You will probably also need a copy of @i(Common Lisp: The + Language) by Guy L. Steele, Jr., published by Digital Press to + use as a reference for some of the Common Lisp functions that + are described only briefly in this document. + + @section(A Note From The Author) + + If you have any problems with XLISP, feel free to contact me [me being David Betz - RBD] for + help or advice. Please remember that since XLISP is available + in source form in a high level language, many users [e.g. that Dannenberg fellow - RBD] have been + making versions available on a variety of machines. If you call + to report a problem with a specific version, I may not be able + to help you if that version runs on a machine to which I don't + have access. Please have the version number of the version that + you are running readily accessible before calling me. + + If you find a bug in XLISP, first try to fix the bug yourself + using the source code provided. If you are successful in fixing + the bug, send the bug report along with the fix to me. If you + don't have access to a C compiler or are unable to fix a bug, + please send the bug report to me and I'll try to fix it. + + Any suggestions for improvements will be welcomed. Feel free to + extend the language in whatever way suits your needs. However, + PLEASE DO NOT RELEASE ENHANCED VERSIONS WITHOUT CHECKING WITH ME + FIRST!! I would like to be the clearing house for new features + added to XLISP. If you want to add features for your own + personal use, go ahead. But, if you want to distribute your + enhanced version, contact me first. Please remember that the + goal of XLISP is to provide a language to learn and experiment + with LISP and object-oriented programming on small computers. I + don't want it to get so big that it requires megabytes of memory + to run. + + + @section(XLISP Command Loop)@index(XLISP Command Loop)@index(Command Loop) + + When XLISP is started, it first tries to load the workspace + @code(xlisp.wks) from the current directory. If that file doesn't + exist, XLISP builds an initial workspace, empty except for the + built-in functions and symbols. + + Then XLISP attempts to load @code(init.lsp) from the current + directory. It then loads any files named as parameters on the + command line (after appending @code(.lsp) to their names). + + XLISP then issues the following prompt: +@begin(example) + > +@end(example) + This indicates that XLISP is waiting for an expression to be + typed. + + When a complete expression has been entered, XLISP attempts to + evaluate that expression. If the expression evaluates + successfully, XLISP prints the result and then returns to the + initial prompt waiting for another expression to be typed. + + @section(Special Characters)@index(control characters, XLISP) + + When XLISP is running from a console, some control characters invoke operations: +@begin(itemize) +Backspace and Delete characters erase the previous character on the input line (if any). + +Control-U erases the entire input line. + +Control-C executes the TOP-LEVEL function. + +Control-G executes the CLEAN-UP function. + +Control-P executes the CONTINUE function. + +Control-B stops execution and enters the break command loop. Execution can be continued by typing Control-P or (CONTINUE). + +Control-E turns on character echoing (Linux and Mac OS X only). + +Control-F turns off character echoing (Linux and Mac OS X only). + +Control-T evaluates the INFO function. +@end(itemize) + + @section(Break Command Loop)@index(break) + + When XLISP encounters an error while evaluating an expression, + it attempts to handle the error in the following way: + + If the symbol @xlcode(*breakenable*@index(*breakenable*)) is + true, the message corresponding to the error is printed. If + the error is correctable, the correction message is printed. + + If the symbol @xlcode(*tracenable*@index(*tracenable*)) is true, a trace back is printed. + The number of entries printed depends on the value of the symbol + @xlcode(*tracelimit*@index(*tracelimit*)). If this symbol is set to something other than a + number, the entire trace back stack is printed. + + XLISP then enters a read/eval/print loop to allow the user to + examine the state of the interpreter in the context of the + error. This loop differs from the normal top-level + read/eval/print loop in that if the user invokes the function + @xlcode(continue), XLISP will continue from a correctable error. If + the user invokes the function @xlcode(clean-up), XLISP will abort the + break loop and return to the top level or the next lower + numbered break loop. When in a break loop, XLISP prefixes the + break level to the normal prompt. + + If the symbol @xlcode(*breakenable*@index(*breakenable*)) is @xlcode(nil), XLISP looks for a + surrounding errset function. If one is found, XLISP examines + the value of the print flag. If this flag is true, the error + message is printed. In any case, XLISP causes the errset + function call to return @xlcode(nil). + + If there is no surrounding errset function, XLISP prints the + error message and returns to the top level. + + @section(Data Types)@index(XLISP Data Types)@index(Data Types) + + There are several different data types available to XLISP + programmers. + +@begin(itemize) +lists + +symbols + +strings + +integers + +characters + +floats + +objects + +arrays + +streams + +subrs (built-in functions) + +fsubrs (special forms) + +closures (user defined functions) +@end(itemize) + + + + +@section(The Evaluator)@index(evaluator)@index(XLISP evaluator) + + The process of evaluation in XLISP: +@begin(itemize) + Strings, integers, characters, floats, objects, arrays, streams, + subrs, fsubrs and closures evaluate to themselves. + + Symbols act as variables and are evaluated by retrieving the + value associated with their current binding. + + Lists are evaluated by examining the first element of the list + and then taking one of the following actions: +@begin(itemize) + If it is a symbol, the functional binding of the symbol is + retrieved. + + If it is a lambda expression, a closure is constructed for + the function described by the lambda expression. + + If it is a subr, fsubr or closure, it stands for itself. + + Any other value is an error. +@end(itemize) + Then, the value produced by the previous step is examined: +@begin(itemize) + If it is a subr or closure, the remaining list elements are + evaluated and the subr or closure is called with these + evaluated expressions as arguments. + + If it is an fsubr, the fsubr is called using the remaining + list elements as arguments (unevaluated). + + If it is a macro, the macro is expanded using the remaining + list elements as arguments (unevaluated). The macro + expansion is then evaluated in place of the original macro + call. +@end(itemize) +@end(itemize) + +@section(Lexical Conventions)@index(Lexical conventions)@index(XLISP Lexical Conventions) + + The following conventions must be followed when entering XLISP + programs: + + Comments in XLISP code begin with a semi-colon character and + continue to the end of the line. + + Symbol names in XLISP can consist of any sequence of non-blank + printable characters except the following: +@begin(example) + ( ) ' ` , " ; +@end(example) + Uppercase and lowercase characters are not distinguished within + symbol names. All lowercase characters are mapped to uppercase + on input. + + Integer literals consist of a sequence of digits optionally + beginning with a @code(+) or @code(-). The range of values an integer can + represent is limited by the size of a C @code(long) on the machine on + which XLISP is running. + + Floating point literals consist of a sequence of digits + optionally beginning with a @code(+) or @code(-) and including an embedded + decimal point. The range of values a floating point number can + represent is limited by the size of a C @code(float) (@code(double) on + machines with 32 bit addresses) on the machine on which XLISP is + running. + + Literal strings are sequences of characters surrounded by double + quotes. Within quoted strings the ``@code(\)'' character is used to + allow non-printable characters to be included. The codes + recognized are: +@begin(itemize) +@code(\\) means the character ``@code(\)'' + +@code(\n) means newline + +@code(\t) means tab + +@code(\r) means return + +@code(\f) means form feed + +@code(\nnn) means the character whose octal code is nnn +@end(itemize) + +@section(Readtables)@index(Readtables) + + The behavior of the reader is controlled by a data structure + called a @i(readtable). The reader uses the symbol @xlcode(*readtable*@index(*readtable*)) to + locate the current readtable. This table controls the + interpretation of input characters. It is an array with 128 + entries, one for each of the ASCII character codes. Each entry + contains one of the following things: +@begin(itemize) + @xlcode(NIL) @itemsep Indicating an invalid character + + @xlcode(:CONSTITUENT) @itemsep Indicating a symbol constituent + + @xlcode(:WHITE-SPACE) @itemsep Indicating a whitespace character + + @xlcode[(:TMACRO . @i(fun))] @itemsep Terminating readmacro + + @xlcode[(:NMACRO . @i(fun))] @itemsep Non-terminating readmacro + + @xlcode(:SESCAPE) @itemsep Single escape character ('\') + + @xlcode(:MESCAPE) @itemsep Multiple escape character ('|') +@end(itemize) + + In the case of @xlcode(:TMACRO) and @xlcode(:NMACRO), the @i(fun) component is a + function. This can either be a built-in readmacro function or a + lambda expression. The function should take two parameters. + The first is the input stream and the second is the character + that caused the invocation of the readmacro. The readmacro + function should return @xlcode(NIL) to indicate that the character should + be treated as white space or a value consed with @xlcode(NIL) to indicate + that the readmacro should be treated as an occurence of the + specified value. Of course, the readmacro code is free to read + additional characters from the input stream. + + XLISP defines several useful read macros@index(read macros): +@begin(itemize) + @xlcode(')@i[<expr>] == @xlcode{(quote} @i[<expr>]@xlcode{)} + + @xlcode(#')@i[<expr>] == @xlcode{(function} @i[<expr>]@xlcode{)} + + @xlcode{#(}@i[<expr>]...@xlcode{)} == an array of the specified expressions + + @xlcode(#x)@i[<hdigits>] == a hexadecimal number (0-9,A-F) + + @xlcode(#o)@i[<odigits>] == an octal number (0-7) + + @xlcode(#b)@i[<bdigits>] == a binary number (0-1) + + @xlcode(#\)@i[<char>] == the ASCII code of the character + + @xlcode(#|) ... @xlcode(|#) == a comment + + @xlcode(#:)@i[<symbol>] == an uninterned symbol + + @xlcode(`)@i[<expr>] == @xlcode{(backquote} @i[<expr>]@xlcode{)} + + @xlcode(,)@i[<expr>] == @xlcode{(comma} @i[<expr>]@xlcode{)} + + @xlcode(,@@)@i[<expr>] == @xlcode{(comma-at} @i[<expr>]@xlcode{)} + +@end(itemize) +@section(Lambda Lists)@index(Lambda Lists) + + There are several forms in XLISP that require that a ``lambda + list'' be specified. A lambda list is a definition of the + arguments accepted by a function. There are four different + types of arguments. + + The lambda list starts with required arguments. Required + arguments must be specified in every call to the function. + + The required arguments are followed by the @xlcode(&optional) arguments. + Optional arguments may be provided or omitted in a call. An + initialization expression may be specified to provide a default + value for an @xlcode(&optional) argument if it is omitted from a call. + If no initialization expression is specified, an omitted + argument is initialized to @xlcode(NIL). It is also possible to provide + the name of a @xlcode(supplied-p) variable that can be used to + determine if a call provided a value for the argument or if the + initialization expression was used. If specified, the supplied- + p variable will be bound to T if a value was specified in the + call and @xlcode(NIL) if the default value was used. + + The @xlcode(&optional) arguments are followed by the @xlcode(&rest) argument. The + @xlcode(&rest) argument gets bound to the remainder of the argument list + after the required and @xlcode(&optional) arguments have been removed. + + The @xlcode(&rest) argument is followed by the @xlcode(&key) arguments. When a + keyword argument is passed to a function, a pair of values + appears in the argument list. The first expression in the pair + should evaluate to a keyword symbol (a symbol that begins with a + ``@code(:)''). The value of the second expression is the value of the + keyword argument. Like @xlcode(&optional) arguments, @xlcode(&key) arguments can + have initialization expressions and supplied-p variables. In + addition, it is possible to specify the keyword to be used in a + function call. If no keyword is specified, the keyword obtained + by adding a ``@code(:)'' to the beginning of the keyword argument symbol + is used. In other words, if the keyword argument symbol is + @xlcode(foo), the keyword will be @xlcode(:foo). + + The @xlcode(&key) arguments are followed by the @xlcode(&aux) variables. These + are local variables that are bound during the evaluation of the + function body. It is possible to have initialization + expressions for the @xlcode(&aux) variables. + + Here is the complete syntax for lambda lists: +@begin(display) + (@i<rarg>... + [@xlcode(&optional) [@i<oarg> | (@i<oarg> [@i<init> [@i<svar>]])]...] + [@xlcode(&rest) @i<rarg>] + [@xlcode(&key) + [@i<karg> | ([@i<karg> | (@i<key> @i<karg>)] [@i<init> [@i<svar>]])]... + @xlcode(&allow)-other-keys] + [@xlcode(&aux) + [@i<aux> | (@i<aux> [@i<init>])]...]) + + where: + + @i<rarg> is a required argument symbol + @i<oarg> is an @xlcode(&optional) argument symbol + @i<rarg> is the @xlcode(&rest) argument symbol + @i<karg> is a @xlcode(&key) argument symbol + @i<key> is a keyword symbol + @i<aux> is an auxiliary variable symbol + @i<init> is an initialization expression + @i<svar> is a supplied-p variable symbol +@end(display) + + +@section(Objects)@index(Objects)@label(objects-sec) + + Definitions: +@begin(itemize) +selector @itemsep a symbol used to select an appropriate method + +message @itemsep a selector and a list of actual arguments + +method @itemsep the code that implements a message +@end(itemize) + Since XLISP was created to provide a simple basis for + experimenting with object-oriented programming, one of the + primitive data types included is @i(object). In XLISP, an object + consists of a data structure containing a pointer to the + object's class as well as an array containing the values of the + object's instance variables. + + Officially, there is no way to see inside an object (look at the + values of its instance variables). The only way to communicate + with an object is by sending it a message. + + You can send a message to an object using the @xlcode(send) function. + This function takes the object as its first argument, the + message selector as its second argument (which must be a symbol) + and the message arguments as its remaining arguments. + + The @xlcode(send) function determines the class of the receiving object + and attempts to find a method corresponding to the message + selector in the set of messages defined for that class. If the + message is not found in the object's class and the class has a + super-class, the search continues by looking at the messages + defined for the super-class. This process continues from one + super-class to the next until a method for the message is found. + If no method is found, an error occurs. + +@begin(comment) +THIS IS WRONG -- I DON'T KNOW IF IT WAS CORRECT IN THE ORIGINAL XLISP. -RBD + A message can also be sent from the body of a method by using + the current object, but the method lookup starts with the + object's superclass rather than its class. This allows a + subclass to invoke a standard method in its parent class even + though it overrides that method with its own specialized + version. +@end(comment) + + When a method is found, the evaluator binds the receiving object + to the symbol @xlcode(self) and evaluates the method using the + remaining elements of the original list as arguments to the + method. These arguments are always evaluated prior to being + bound to their corresponding formal arguments. The result of + evaluating the method becomes the result of the expression. + + Within the body of a method, a message can be sent to the current + object by calling the @xlcode[(send self ...)]. The method lookup + starts with the object's class regardless of the class containing + the current method. + + Sometimes it is desirable to invoke a general method in a superclass + even when it is overridden by a more specific method in a subclass. + This can be accomplished by calling @xlcode(send-super), which begins + the method lookup in the superclass of the class defining the current + method rather than in the class of the current object. + + The @xlcode(send-super) function takes a selector as its first argument + (which must be a symbol) and the message arguments as its remaining + arguments. Notice that @xlcode(send-super) can only be sent from within + a method, and the target of the message is always the current object + (@xlcode(self)). @xlcode[(send-super ...)] is similar to + @xlcode[(send self ...)] except that method lookup begins in the + superclass of the class containing the current method + rather than the class of the current object. + +@section(The ``Object'' Class)@index(Object Class) + +@xlcode(Object)@index(Object) @itemsep the top of the class hierarchy. + +Messages: +@begin(fdescription) +@xlcode(:show@index(:show)) @itemsep show an object's instance variables. +@begin(pdescription) +returns @itemsep the object +@end(pdescription) +@blankspace(1) + +@xlcode{:class@index(:class)} @itemsep return the class of an object +@begin(pdescription) +returns @itemsep the class of the object +@end(pdescription) +@blankspace(1) + +@xlcode{:isa@index(:isa)} @i(class) @itemsep test if object inherits from class +@begin(pdescription) +returns @itemsep @xlcode(t) if object is an instance of @i(class) or a subclass of @i(class), otherwise @xlcode(nil) +@end(pdescription) +@blankspace(1) + +@xlcode(:isnew@index(:isnew)) @itemsep the default object initialization routine +@begin(pdescription) +returns @itemsep the object +@end(pdescription) +@end(fdescription) + +@section(The ``Class'' Class)@index(Class class) + +@xlcode(Class@index(Class)) @itemsep class of all object classes (including itself) + + Messages: + +@begin(fdescription) + @xlcode(:new@index(:new)) @itemsep create a new instance of a class +@begin(pdescription) + returns @itemsep the new class object +@end(pdescription) +@blankspace(1) + + @xlcode(:isnew@index(:isnew)) @i<ivars> [@i<cvars> [@i<super>]] @itemsep initialize a new class +@begin(pdescription) + @i<ivars> @itemsep the list of instance variable symbols + + @i<cvars> @itemsep the list of class variable symbols + + @i<super> @itemsep the superclass (default is object) + + returns @itemsep the new class object +@end(pdescription) +@blankspace(1) + + @xlcode(:answer@index(:answer)) @i<msg> @i<fargs> @i<code> @itemsep add a message to a class +@begin(pdescription) + @i<msg> @itemsep the message symbol + + @i<fargs> @itemsep the formal argument list (lambda list) + + @i<code> @itemsep a list of executable expressions + + returns @itemsep the object +@end(pdescription) +@blankspace(1) +@end(fdescription) + + When a new instance of a class is created by sending the message + @xlcode(:new) to an existing class, the message @xlcode(:isnew) followed by + whatever parameters were passed to the @xlcode(:new) message is sent to + the newly created object. + + When a new class is created by sending the @xlcode(:new) message to the + object @xlcode(Class), an optional parameter may be specified + indicating the superclass of the new class. If this parameter + is omitted, the new class will be a subclass of @xlcode(Object). A + class inherits all instance variables, class variables, and + methods from its super-class. + +@section(Profiling)@index(profiling) +The Xlisp 2.0 release has been extended with a profiling facility, which counts how many times and where @xlcode(eval) is executed. A separate count is maintained for each named function, closure, or macro, and a count indicates an @xlcode(eval) in the immediately (lexically) enclosing named function, closure, or macro. Thus, the count gives an indication of the amount of time spent in a function, not counting nested function calls. The list of all functions executed is maintained on the global @xlcode(*profile*) variable. These functions in turn have @xlcode(*profile*) properties, which maintain the counts. The profile system merely increments counters and puts symbols on the @xlcode(*profile*) list. It is up to the user to initialize data and gather results. Profiling is turned on or off with the @xlcode(profile) function. Unfortunately, methods cannot be profiled with this facility. + +@label(symbols-sec) +@section(Symbols)@index(symbols) +@begin(itemize) +@codef(self)@pragma(defn)@index(self) @dash the current object (within a method context) + +@codef(*obarray*@pragma(defn)@index(*obarray*)) @dash the object hash table + +@codef(*standard-input*@pragma(defn)@index(*standard-input*)) @dash the standard input stream + +@codef(*standard-output*@pragma(defn)@index(*standard-output*)) @dash the standard output stream + +@codef(*error-output*@pragma(defn)@index(*error-output*)) @dash the error output stream + +@codef(*trace-output*@pragma(defn)@index(*trace-output*)) @dash the trace output stream + +@codef(*debug-io*@pragma(defn)@index(*debug-io*)) @dash the debug i/o stream + +@codef(*breakenable*@pragma(defn)@index(*breakenable*)) @dash flag controlling entering break loop on errors + +@codef(*tracelist*@pragma(defn)@index(*tracelist*)) @dash list of names of functions to trace + +@codef(*tracenable*@pragma(defn)@index(*tracenable*)) @dash enable trace back printout on errors + +@codef(*tracelimit*@pragma(defn)@index(*tracelimit*)) @dash number of levels of trace back information + +@codef(*evalhook*@pragma(defn)@index(*evalhook*)) @dash user substitute for the evaluator function + +@codef(*applyhook*@pragma(defn)@index(*applyhook*)) @dash (not yet implemented) + +@codef(*readtable*@pragma(defn)@index(*readtable*)) @dash the current readtable + +@codef(*unbound*@pragma(defn)@index(*unbound*)) @dash indicator for unbound symbols + +@codef(*gc-flag*@pragma(defn)@index(*gc-flag*)) @dash controls the printing of gc messages + +@codef(*gc-hook*@pragma(defn)@index(*gc-hook*)) @dash function to call after garbage collection + +@codef(*integer-format*@pragma(defn)@index(*integer-format*)) @dash format for printing integers (``%d'' or ``%ld'') + +@codef(*float-format*@pragma(defn)@index(*float-format*)) @dash format for printing floats (``%g'') + +@codef(*print-case*@pragma(defn)@index(*print-case*)) @dash symbol output case (:upcase or :downcase) +@end(itemize) + + There are several symbols maintained by the read/eval/print + loop. The symbols @code(+), @code(++), and @code(+++) are bound to the most + recent three input expressions. The symbols @code(*), @code(**) and @code(***) + are bound to the most recent three results. The symbol @code(-) is + bound to the expression currently being evaluated. It becomes + the value of @code(+) at the end of the evaluation. +@section(Evaluation Functions)@index(evaluation functions) +@begin(fdescription) + (eval@pragma(defn)@index(eval) @i<expr>) @itemsep evaluate an xlisp expression +@begin(pdescription) + @i<expr> @itemsep the expression to be evaluated + + returns @itemsep the result of evaluating the expression +@end(pdescription) +@blankspace(1) + + (apply@pragma(defn)@index(apply) @i<fun> @i<args>) @itemsep apply a function to a list of arguments +@begin(pdescription) + @i<fun> @itemsep the function to apply (or function symbol) + + @i<args> @itemsep the argument list + + returns @itemsep the result of applying the function to the arguments +@end(pdescription) +@blankspace(1) + + (funcall@pragma(defn)@index(funcall) @i<fun> @i<arg>...) @itemsep call a function with arguments +@begin(pdescription) + @i<fun> @itemsep the function to call (or function symbol) + + @i<arg> @itemsep arguments to pass to the function + + returns @itemsep the result of calling the function with the arguments +@end(pdescription) +@blankspace(1) + + (quote@pragma(defn)@index(quote) @i<expr>) @itemsep return an expression unevaluated +@begin(pdescription) + @i<expr> @itemsep the expression to be quoted (quoted) + + returns @itemsep @i<expr> unevaluated +@end(pdescription) +@blankspace(1) + + (function@pragma(defn)@index(function) @i<expr>) @itemsep get the functional interpretation + +@begin(pdescription) + @i<expr> @itemsep the symbol or lambda expression (quoted) + + returns @itemsep the functional interpretation + +@end(pdescription) +@blankspace(1) + + (backquote@pragma(defn)@index(backquote) @i<expr>) @itemsep fill in a template + +@begin(pdescription) + @i<expr> @itemsep the template + + returns @itemsep a copy of the template with comma and comma-at + + expressions expanded +@end(pdescription) +@blankspace(1) + + (lambda@pragma(defn)@index(lambda) @i<args> @i<expr>...) @itemsep make a function closure + +@begin(pdescription) + @i<args> @itemsep formal argument list (lambda list) (quoted) + + @i<expr> @itemsep expressions of the function body + + returns @itemsep the function closure + +@end(pdescription) +@blankspace(1) + + (get-lambda-expression@pragma(defn)@index(get-lambda-expression) @i<closure>) @itemsep get the lambda expression + +@begin(pdescription) + @i<closure> @itemsep the closure + + returns @itemsep the original lambda expression + +@end(pdescription) +@blankspace(1) + + (macroexpand@pragma(defn)@index(macroexpand) @i<form>) @itemsep recursively expand macro calls + +@begin(pdescription) + @i<form> @itemsep the form to expand + + returns @itemsep the macro expansion + +@end(pdescription) +@blankspace(1) + + (macroexpand-1@pragma(defn)@index(macroexpand-1) @i<form>) @itemsep expand a macro call + +@begin(pdescription) + @i<form> @itemsep the macro call form + + returns @itemsep the macro expansion + +@end(pdescription) +@blankspace(1) +@end(fdescription) + + +@section(Symbol Functions)@index(Symbol Functions) +@begin(fdescription) + (set@pragma(defn)@index(set) @i<sym> @i<expr>) @itemsep set the value of a symbol +@begin(pdescription) + @i<sym> @itemsep the symbol being set + + @i<expr> @itemsep the new value + + returns @itemsep the new value + +@end(pdescription) +@blankspace(1) + + (setq@pragma(defn)@index(setq) [@i<sym> @i<expr>]...) @itemsep set the value of a symbol +@begin(pdescription) + @i<sym> @itemsep the symbol being set (quoted) + + @i<expr> @itemsep the new value + + returns @itemsep the new value + +@end(pdescription) +@blankspace(1) + + (psetq@pragma(defn)@index(psetq) [@i<sym> @i<expr>]...) @itemsep parallel version of setq +@begin(pdescription) + @i<sym> @itemsep the symbol being set (quoted) + + @i<expr> @itemsep the new value + + returns @itemsep the new value + +@end(pdescription) +@blankspace(1) + + (setf@pragma(defn)@index(setf) [@i<place> @i<expr>]...) @itemsep set the value of a field +@begin(pdescription) + @i<place> @itemsep the field specifier (quoted): + +@begin(pdescription) + @i<sym> @itemsep set value of a symbol + + (car @i<expr>) @itemsep set car of a cons node + + (cdr @i<expr>) @itemsep set cdr of a cons node + + (nth @i<n> @i<expr>) @itemsep set nth car of a list + + (aref @i<expr> @i<n>) @itemsep set nth element of an array + + (get @i<sym> @i<prop>) @itemsep set value of a property + + (symbol-value @i<sym>) @itemsep set value of a symbol + + (symbol-function @i<sym>) @itemsep set functional value of a symbol + + (symbol-plist @i<sym>) @itemsep set property list of a symbol + +@end(pdescription)@pragma(stopcodef) + @i<expr> @itemsep the new value + + returns @itemsep the new value + +@end(pdescription) +@blankspace(1) +@begin(fgroup) + (defun@pragma(defn)@index(defun) @i<sym> @i<fargs> @i<expr>...) @itemsep define a function + +@pragma(startcodef) + (defmacro@pragma(defn)@index(defmacro) @i<sym> @i<fargs> @i<expr>...) @itemsep define a macro +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep symbol being defined (quoted) + + @i<fargs> @itemsep formal argument list (lambda list) (quoted) + + @i<expr> @itemsep expressions constituting the body of the + + function (quoted) + returns @itemsep the function symbol + +@end(pdescription) +@blankspace(1) + + (gensym@pragma(defn)@index(gensym) [@i<tag>]) @itemsep generate a symbol +@begin(pdescription) + @i<tag> @itemsep string or number + + returns @itemsep the new symbol + +@end(pdescription) +@blankspace(1) + +(intern@pragma(defn)@index(intern) @i<pname>) @itemsep make an interned symbol +@begin(pdescription) + @i<pname> @itemsep the symbol's print name string + + returns @itemsep the new symbol + +@end(pdescription) +@blankspace(1) + + (make-symbol@pragma(defn)@index(make-symbol) @i<pname>) @itemsep make an uninterned symbol +@begin(pdescription) + @i<pname> @itemsep the symbol's print name string + + returns @itemsep the new symbol + +@end(pdescription) +@blankspace(1) + + (symbol-name@pragma(defn)@index(symbol-name) @i<sym>) @itemsep get the print name of a symbol +@begin(pdescription) + @i<sym> @itemsep the symbol + + returns @itemsep the symbol's print name + +@end(pdescription) +@blankspace(1) + + (symbol-value@pragma(defn)@index(symbol-value) @i<sym>) @itemsep get the value of a symbol +@begin(pdescription) + @i<sym> @itemsep the symbol + + returns @itemsep the symbol's value + +@end(pdescription) +@blankspace(1) + + (symbol-function@pragma(defn)@index(symbol-function) @i<sym>) @itemsep get the functional value of a symbol +@begin(pdescription) + @i<sym> @itemsep the symbol + + returns @itemsep the symbol's functional value + +@end(pdescription) +@blankspace(1) + + (symbol-plist@pragma(defn)@index(symbol-plist) @i<sym>) @itemsep get the property list of a symbol +@begin(pdescription) + @i<sym> @itemsep the symbol + + returns @itemsep the symbol's property list + +@end(pdescription) +@blankspace(1) + + (hash@pragma(defn)@index(hash) @i<sym> @i<n>) @itemsep compute the hash index for a symbol +@begin(pdescription) + @i<sym> @itemsep the symbol or string + + @i<n> @itemsep the table size (integer) + + returns @itemsep the hash index (integer) + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Property List Functions)@index(Property List Functions) +@begin(fdescription) + (get@pragma(defn)@index(get) @i<sym> @i<prop>) @itemsep get the value of a property +@begin(pdescription) + @i<sym> @itemsep the symbol + + @i<prop> @itemsep the property symbol + + returns @itemsep the property value or @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + (putprop@pragma(defn)@index(putprop) @i<sym> @i<val> @i<prop>) @itemsep put a property onto a property list +@begin(pdescription) + @i<sym> @itemsep the symbol + + @i<val> @itemsep the property value + + @i<prop> @itemsep the property symbol + + returns @itemsep the property value + +@end(pdescription) +@blankspace(1) + + (remprop@pragma(defn)@index(remprop) @i<sym> @i<prop>) @itemsep remove a property +@begin(pdescription) + @i<sym> @itemsep the symbol + + @i<prop> @itemsep the property symbol + + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Array Functions)@index(Array Functions) +@begin(fdescription) + (aref@pragma(defn)@index(aref) @i<array> @i<n>) @itemsep get the nth element of an array +@begin(pdescription) + @i<array> @itemsep the array + + @i<n> @itemsep the array index (integer) + + returns @itemsep the value of the array element + +@end(pdescription) +@blankspace(1) + + (make-array@pragma(defn)@index(make-array) @i<size>) @itemsep make a new array +@begin(pdescription) + @i<size> @itemsep the size of the new array (integer) + + returns @itemsep the new array + +@end(pdescription) +@blankspace(1) + + (vector@pragma(defn)@index(vector) @i<expr>...) @itemsep make an initialized vector +@begin(pdescription) + @i<expr> @itemsep the vector elements + + returns @itemsep the new vector + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(List Functions)@index(List Functions) +@begin(fdescription) + (car@pragma(defn)@index(car) @i<expr>) @itemsep return the car of a list node +@begin(pdescription) + @i<expr> @itemsep the list node + + returns @itemsep the car of the list node + +@end(pdescription) +@blankspace(1) + + (cdr@pragma(defn)@index(cdr) @i<expr>) @itemsep return the cdr of a list node +@begin(pdescription) + @i<expr> @itemsep the list node + + returns @itemsep the cdr of the list node + +@end(pdescription) +@blankspace(1) + + (c@i(xx)r@index(cxxr) @i<expr>) @itemsep all c@i(xx)r combinations +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + (c@i(xxx)r@index(cxxxr) @i<expr>) @itemsep all c@i(xxx)r combinations +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + (c@i(xxxx)r@index(cxxxxr) @i<expr>) @itemsep all c@i(xxxx)r combinations +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + (first@pragma(defn)@index(first) @i<expr>) @itemsep a synonym for car +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + (second@pragma(defn)@index(second) @i<expr>) @itemsep a synonym for cadr +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + (third@pragma(defn)@index(third) @i<expr>) @itemsep a synonym for caddr +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + (fourth@pragma(defn)@index(fourth) @i<expr>) @itemsep a synonym for cadddr +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + (rest@pragma(defn)@index(rest) @i<expr>) @itemsep a synonym for cdr +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + (cons@pragma(defn)@index(cons) @i<expr1> @i<expr2>) @itemsep construct a new list node +@begin(pdescription) + @i<expr1> @itemsep the car of the new list node + + @i<expr2> @itemsep the cdr of the new list node + + returns @itemsep the new list node + +@end(pdescription) +@blankspace(1) + + (list@pragma(defn)@index(list) @i<expr>...) @itemsep create a list of values +@begin(pdescription) + @i<expr> @itemsep expressions to be combined into a list + + returns @itemsep the new list + +@end(pdescription) +@blankspace(1) + + (append@pragma(defn)@index(append) @i<expr>...) @itemsep append lists +@begin(pdescription) + @i<expr> @itemsep lists whose elements are to be appended + + returns @itemsep the new list + +@end(pdescription) +@blankspace(1) + + (reverse@pragma(defn)@index(reverse) @i<expr>) @itemsep reverse a list +@begin(pdescription) + @i<expr> @itemsep the list to reverse + + returns @itemsep a new list in the reverse order + +@end(pdescription) +@blankspace(1) + + (last@pragma(defn)@index(last) @i<list>) @itemsep return the last list node of a list +@begin(pdescription) + @i<list> @itemsep the list + + returns @itemsep the last list node in the list + +@end(pdescription) +@blankspace(1) + + (member@pragma(defn)@index(member) @i<expr> @i<list> &key :test :test-not) @itemsep find an expression in a list +@begin(pdescription) + @i<expr> @itemsep the expression to find + + @i<list> @itemsep the list to search + + :test @itemsep the test function (defaults to eql) + + :test-not @itemsep the test function (sense inverted) + + returns @itemsep the remainder of the list starting with the expression + +@end(pdescription) +@blankspace(1) + + (assoc@pragma(defn)@index(assoc) @i<expr> @i<alist> &key :test :test-not) @itemsep find an expression in an a-list +@begin(pdescription) + @i<expr> @itemsep the expression to find + + @i<alist> @itemsep the association list + + :test @itemsep the test function (defaults to eql) + + :test-not @itemsep the test function (sense inverted) + + returns @itemsep the alist entry or @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + (remove@pragma(defn)@index(remove) @i<expr> @i<list> &key :test :test-not) @itemsep remove elements from a list +@begin(pdescription) + @i<expr> @itemsep the element to remove + + @i<list> @itemsep the list + + :test @itemsep the test function (defaults to eql) + + :test-not @itemsep the test function (sense inverted) + + returns @itemsep copy of list with matching expressions removed + +@end(pdescription) +@blankspace(1) + + (remove-if@pragma(defn)@index(remove-if) @i<test> @i<list>) @itemsep remove elements that pass test +@begin(pdescription) + @i<test> @itemsep the test predicate + + @i<list> @itemsep the list + + returns @itemsep copy of list with matching elements removed + +@end(pdescription) +@blankspace(1) + + (remove-if-not@pragma(defn)@index(remove-if-not) @i<test> @i<list>) @itemsep remove elements that fail test +@begin(pdescription) + @i<test> @itemsep the test predicate + + @i<list> @itemsep the list + + returns @itemsep copy of list with non-matching elements removed + +@end(pdescription) +@blankspace(1) + + (length@pragma(defn)@index(length) @i<expr>) @itemsep find the length of a list, vector or string +@begin(pdescription) + @i<expr> @itemsep the list, vector or string + + returns @itemsep the length of the list, vector or string + +@end(pdescription) +@blankspace(1) + + (nth@pragma(defn)@index(nth) @i<n> @i<list>) @itemsep return the nth element of a list +@begin(pdescription) + @i<n> @itemsep the number of the element to return (zero origin) + + @i<list> @itemsep the list + + returns @itemsep the nth element or @xlcode(nil) if the list isn't that long + +@end(pdescription) +@blankspace(1) + + (nthcdr@pragma(defn)@index(nthcdr) @i<n> @i<list>) @itemsep return the nth cdr of a list +@begin(pdescription) + @i<n> @itemsep the number of the element to return (zero origin) + + @i<list> @itemsep the list + + returns @itemsep the nth cdr or @xlcode(nil) if the list isn't that long + +@end(pdescription) +@blankspace(1) + + (mapc@pragma(defn)@index(mapc) @i<fcn> @i<list1> @i<list>...) @itemsep apply function to successive cars +@begin(pdescription) + @i<fcn> @itemsep the function or function name + + @i<listn> @itemsep a list for each argument of the function + + returns @itemsep the first list of arguments + +@end(pdescription) +@blankspace(1) + + (mapcar@pragma(defn)@index(mapcar) @i<fcn> @i<list1> @i<list>...) @itemsep apply function to successive cars +@begin(pdescription) + @i<fcn> @itemsep the function or function name + + @i<listn> @itemsep a list for each argument of the function + + returns @itemsep a list of the values returned + +@end(pdescription) +@blankspace(1) + + (mapl@pragma(defn)@index(mapl) @i<fcn> @i<list1> @i<list>...) @itemsep apply function to successive cdrs +@begin(pdescription) + @i<fcn> @itemsep the function or function name + + @i<listn> @itemsep a list for each argument of the function + + returns @itemsep the first list of arguments + +@end(pdescription) +@blankspace(1) + + (maplist@pragma(defn)@index(maplist) @i<fcn> @i<list1> @i<list>...) @itemsep apply function to successive cdrs +@begin(pdescription) + @i<fcn> @itemsep the function or function name + + @i<listn> @itemsep a list for each argument of the function + + returns @itemsep a list of the values returned + +@end(pdescription) +@blankspace(1) + + (subst@pragma(defn)@index(subst) @i<to> @i<from> @i<expr> &key :test :test-not) @itemsep substitute expressions +@begin(pdescription) + @i<to> @itemsep the new expression + + @i<from> @itemsep the old expression + + @i<expr> @itemsep the expression in which to do the substitutions + + :test @itemsep the test function (defaults to eql) + + :test-not @itemsep the test function (sense inverted) + + returns @itemsep the expression with substitutions + +@end(pdescription) +@blankspace(1) + + (sublis@pragma(defn)@index(sublis) @i<alist> @i<expr> &key :test :test-not) @itemsep substitute with an a-list +@begin(pdescription) + @i<alist> @itemsep the association list + + @i<expr> @itemsep the expression in which to do the substitutions + + :test @itemsep the test function (defaults to eql) + + :test-not @itemsep the test function (sense inverted) + + returns @itemsep the expression with substitutions + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Destructive List Functions)@index(Destructive List Functions) +@begin(fdescription) + (rplaca@pragma(defn)@index(rplaca) @i<list> @i<expr>) @itemsep replace the car of a list node +@begin(pdescription) + @i<list> @itemsep the list node + + @i<expr> @itemsep the new value for the car of the list node + + returns @itemsep the list node after updating the car + +@end(pdescription) +@blankspace(1) + + (rplacd@pragma(defn)@index(rplacd) @i<list> @i<expr>) @itemsep replace the cdr of a list node +@begin(pdescription) + @i<list> @itemsep the list node + + @i<expr> @itemsep the new value for the cdr of the list node + + returns @itemsep the list node after updating the cdr + +@end(pdescription) +@blankspace(1) + + (nconc@pragma(defn)@index(nconc) @i<list>...) @itemsep destructively concatenate lists +@begin(pdescription) + @i<list> @itemsep lists to concatenate + + returns @itemsep the result of concatenating the lists + +@end(pdescription) +@blankspace(1) + + (delete@pragma(defn)@index(delete) @i<expr> &key :test :test-not) @itemsep delete elements from a list +@begin(pdescription) + @i<expr> @itemsep the element to delete + + @i<list> @itemsep the list + + :test @itemsep the test function (defaults to eql) + + :test-not @itemsep the test function (sense inverted) + + returns @itemsep the list with the matching expressions deleted + +@end(pdescription) +@blankspace(1) + + (delete-if@pragma(defn)@index(delete-if) @i<test> @i<list>) @itemsep delete elements that pass test +@begin(pdescription) + @i<test> @itemsep the test predicate + + @i<list> @itemsep the list + + returns @itemsep the list with matching elements deleted + +@end(pdescription) +@blankspace(1) + + (delete-if-not@pragma(defn)@index(delete-if-not) @i<test> @i<list>) @itemsep delete elements that fail test +@begin(pdescription) + @i<test> @itemsep the test predicate + + @i<list> @itemsep the list + + returns @itemsep the list with non-matching elements deleted + +@end(pdescription) +@blankspace(1) + + (sort@pragma(defn)@index(sort) @i<list> @i<test>) @itemsep sort a list +@begin(pdescription) + @i<list> @itemsep the list to sort + + @i<test> @itemsep the comparison function + + returns @itemsep the sorted list + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Predicate Functions)@index(Predicate Functions) +@begin(fdescription) + (atom@pragma(defn)@index(atom) @i<expr>) @itemsep is this an atom? +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is an atom, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (symbolp@pragma(defn)@index(symbolp) @i<expr>) @itemsep is this a symbol? +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the expression is a symbol, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (numberp@pragma(defn)@index(numberp) @i<expr>) @itemsep is this a number? +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the expression is a number, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (null@pragma(defn)@index(null) @i<expr>) @itemsep is this an empty list? +@begin(pdescription) + @i<expr> @itemsep the list to check + + returns @itemsep @xlcode(t) if the list is empty, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (not@pragma(defn)@index(not) @i<expr>) @itemsep is this false? +@begin(pdescription) + @i<expr> @itemsep the expression to check + + return @itemsep @xlcode(t) if the value is @xlcode(nil), @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (listp@pragma(defn)@index(listp) @i<expr>) @itemsep is this a list? +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is a cons or @xlcode(nil), @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (endp@pragma(defn)@index(endp) @i<list>) @itemsep is this the end of a list +@begin(pdescription) + @i<list> @itemsep the list + + returns @itemsep @xlcode(t) if the value is @xlcode(nil), @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (consp@pragma(defn)@index(consp) @i<expr>) @itemsep is this a non-empty list? +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is a cons, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (integerp@pragma(defn)@index(integerp) @i<expr>) @itemsep is this an integer? +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is an integer, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (floatp@pragma(defn)@index(floatp) @i<expr>) @itemsep is this a float? +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is a float, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (stringp@pragma(defn)@index(stringp) @i<expr>) @itemsep is this a string? +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is a string, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (characterp@pragma(defn)@index(characterp) @i<expr>) @itemsep is this a character? +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is a character, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (arrayp@pragma(defn)@index(arrayp) @i<expr>) @itemsep is this an array? +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is an array, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (streamp@pragma(defn)@index(streamp) @i<expr>) @itemsep is this a stream? +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is a stream, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (objectp@pragma(defn)@index(objectp) @i<expr>) @itemsep is this an object? +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is an object, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (filep@pragma(defn)@index(filep) @i<expr>)@foot(This is not part of standard XLISP nor is it built-in. Nyquist defines it though.) @itemsep is this a file? +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is an object, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (boundp@pragma(defn)@index(boundp) @i<sym>) @itemsep is a value bound to this symbol? +@begin(pdescription) + @i<sym> @itemsep the symbol + + returns @itemsep @xlcode(t) if a value is bound to the symbol, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (fboundp@pragma(defn)@index(fboundp) @i<sym>) @itemsep is a functional value bound to this symbol? +@begin(pdescription) + @i<sym> @itemsep the symbol + + returns @itemsep @xlcode(t) if a functional value is bound to the symbol, + + @xlcode(nil) otherwise +@end(pdescription) +@blankspace(1) + + (minusp@pragma(defn)@index(minusp) @i<expr>) @itemsep is this number negative? +@begin(pdescription) + @i<expr> @itemsep the number to test + + returns @itemsep @xlcode(t) if the number is negative, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (zerop@pragma(defn)@index(zerop) @i<expr>) @itemsep is this number zero? +@begin(pdescription) + @i<expr> @itemsep the number to test + + returns @itemsep @xlcode(t) if the number is zero, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (plusp@pragma(defn)@index(plusp) @i<expr>) @itemsep is this number positive? +@begin(pdescription) + @i<expr> @itemsep the number to test + + returns @itemsep @xlcode(t) if the number is positive, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (evenp@pragma(defn)@index(evenp) @i<expr>) @itemsep is this integer even? +@begin(pdescription) + @i<expr> @itemsep the integer to test + + returns @itemsep @xlcode(t) if the integer is even, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (oddp@pragma(defn)@index(oddp) @i<expr>) @itemsep is this integer odd? +@begin(pdescription) + @i<expr> @itemsep the integer to test + + returns @itemsep @xlcode(t) if the integer is odd, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (eq@pragma(defn)@index(eq) @i<expr1> @i<expr2>) @itemsep are the expressions identical? +@begin(pdescription) + @i<expr1> @itemsep the first expression + + @i<expr2> @itemsep the second expression + + returns @itemsep @xlcode(t) if they are equal, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + +(eql@pragma(defn)@index(eql) @i<expr1> @i<expr2>) @itemsep are the expressions identical? (works with all numbers) +@begin(pdescription) + @i<expr1> @itemsep the first expression + + @i<expr2> @itemsep the second expression + + returns @itemsep @xlcode(t) if they are equal, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (equal@pragma(defn)@index(equal) @i<expr1> @i<expr2>) @itemsep are the expressions equal? +@begin(pdescription) + @i<expr1> @itemsep the first expression + + @i<expr2> @itemsep the second expression + + returns @itemsep @xlcode(t) if they are equal, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Control Constructs)@index(Control Constructs) +@begin(fdescription) + (cond@pragma(defn)@index(cond) @i<pair>...) @itemsep evaluate conditionally +@begin(pdescription) + @i<pair> @itemsep pair consisting of: + +@begin(pdescription) + (@i<pred> @i<expr>...) +@end(pdescription)@pragma(stopcodef) + where: +@begin(pdescription) + @i<pred> @itemsep is a predicate expression + + @i<expr> @itemsep evaluated if the predicate + is not @xlcode(nil) +@end(pdescription)@pragma(stopcodef) +returns @itemsep the value of the first expression whose predicate is not +@xlcode(nil) +@end(pdescription) +@blankspace(1) + + (and@pragma(defn)@index(and) @i<expr>...) @itemsep the logical and of a list of expressions +@begin(pdescription) + @i<expr> @itemsep the expressions to be anded + + returns @itemsep @xlcode(nil) if any expression evaluates to @xlcode(nil), + otherwise the value of the last expression + (evaluation of expressions stops after the first + expression that evaluates to @xlcode(nil)) +@end(pdescription) +@blankspace(1) + + (or@pragma(defn)@index(or) @i<expr>...) @itemsep the logical or of a list of expressions +@begin(pdescription) + @i<expr> @itemsep the expressions to be ored + + returns @itemsep @xlcode(nil) if all expressions evaluate to @xlcode(nil), + otherwise the value of the first non-@xlcode(nil) expression + (evaluation of expressions stops after the first + expression that does not evaluate to @xlcode(nil)) +@end(pdescription) +@blankspace(1) + + (if@pragma(defn)@index(if) @i<texpr> @i<expr1> [@i<expr2>]) @itemsep evaluate expressions conditionally +@begin(pdescription) + @i<texpr> @itemsep the test expression + + @i<expr1> @itemsep the expression to be evaluated if texpr is non-@xlcode(nil) + + @i<expr2> @itemsep the expression to be evaluated if texpr is @xlcode(nil) + + returns @itemsep the value of the selected expression + +@end(pdescription) +@blankspace(1) + + (when@pragma(defn)@index(when) @i<texpr> @i<expr>...) @itemsep evaluate only when a condition is true +@begin(pdescription) + @i<texpr> @itemsep the test expression + + @i<expr> @itemsep the expression(s) to be evaluated if texpr is non-@xlcode(nil) + + returns @itemsep the value of the last expression or @xlcode(nil) +@end(pdescription) +@blankspace(1) + + (unless@pragma(defn)@index(unless) @i<texpr> @i<expr>...) @itemsep evaluate only when a condition is false +@begin(pdescription) + @i<texpr> @itemsep the test expression + + @i<expr> @itemsep the expression(s) to be evaluated if texpr is @xlcode(nil) + + returns @itemsep the value of the last expression or @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + (case@pragma(defn)@index(case) @i<expr> @i<case>...) @itemsep select by case +@begin(pdescription) + @i<expr> @itemsep the selection expression + + @i<case> @itemsep pair consisting of: + +@begin(pdescription) + (@i<value> @i<expr>...) +@end(pdescription)@pragma(stopcodef) + where: +@begin(pdescription) + @i<value> @itemsep is a single expression or a list of + expressions (unevaluated) + + @i<expr> @itemsep are expressions to execute if the + case matches +@end(pdescription)@pragma(stopcodef) + returns @itemsep the value of the last expression of the matching case + +@end(pdescription) +@blankspace(1) +@begin(fgroup) + (let@pragma(defn)@index(let) (@i<binding>...) @i<expr>...) @itemsep create local bindings + +@pragma(startcodef) + (let*@pragma(defn)@index(let*) (@i<binding>...) @i<expr>...) @itemsep let with sequential binding +@end(fgroup) +@begin(pdescription) + @i<binding> @itemsep the variable bindings each of which is either: + +@begin(pdescription) + 1) a symbol (which is initialized to @xlcode(nil)) + + 2) a list whose car is a symbol and whose cadr + is an initialization expression +@end(pdescription)@pragma(stopcodef) + @i<expr> @itemsep the expressions to be evaluated + + returns @itemsep the value of the last expression + +@end(pdescription) +@blankspace(1) +@begin(fgroup) + (flet@pragma(defn)@index(flet) (@i<binding>...) @i<expr>...) @itemsep create local functions + +@pragma(startcodef) + (labels@pragma(defn)@index(labels) (@i<binding>...) @i<expr>...) @itemsep flet with recursive functions + +@pragma(startcodef) + (macrolet@pragma(defn)@index(macrolet) (@i<binding>...) @i<expr>...) @itemsep create local macros +@end(fgroup) +@begin(pdescription) + @i<binding> @itemsep the function bindings each of which is: + +@begin(pdescription) + (@i<sym> @i<fargs> @i<expr>...) +@end(pdescription)@pragma(stopcodef) + where: +@begin(pdescription) + @i<sym> @itemsep the function/macro name + + @i<fargs> @itemsep formal argument list (lambda list) + + @i<expr> @itemsep expressions constituting the body of + the function/macro +@end(pdescription)@pragma(stopcodef) + @i<expr> @itemsep the expressions to be evaluated + + returns @itemsep the value of the last expression +@end(pdescription) +@blankspace(1) + + (catch@pragma(defn)@index(catch) @i<sym> @i<expr>...) @itemsep evaluate expressions and catch throws +@begin(pdescription) + @i<sym> @itemsep the catch tag + + @i<expr> @itemsep expressions to evaluate + + returns @itemsep the value of the last expression the throw expression + +@end(pdescription) +@blankspace(1) + + (throw@pragma(defn)@index(throw) @i<sym> [@i<expr>]) @itemsep throw to a catch +@begin(pdescription) + @i<sym> @itemsep the catch tag + + @i<expr> @itemsep the value for the catch to return (defaults to @xlcode(nil)) + + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + (unwind-protect@pragma(defn)@index(unwind-protect) @i<expr> @i<cexpr>...) @itemsep protect evaluation of an expression +@begin(pdescription) + @i<expr> @itemsep the expression to protect + + @i<cexpr> @itemsep the cleanup expressions + + returns @itemsep the value of the expression@* + + Note: unwind-protect guarantees to execute the cleanup expressions + even if a non-local exit terminates the evaluation of the + protected expression +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Looping Constructs)@index(Looping Constructs) +@begin(fdescription) + (loop@pragma(defn)@index(loop) @i<expr>...) @itemsep basic looping form +@begin(pdescription) + @i<expr> @itemsep the body of the loop + + returns @itemsep never returns (must use non-local exit) + +@end(pdescription) +@blankspace(1) +@begin(fgroup) + (do@pragma(defn)@index(do) (@i<binding>...) (@i<texpr> @i<rexpr>...) @i<expr>...) +@pragma(endcodef) + (do*@pragma(defn)@index(do*) (@i<binding>...) (@i<texpr> @i<rexpr>...) @i<expr>...) +@end(fgroup) +@begin(pdescription) + @i<binding> @itemsep the variable bindings each of which is either: + +@begin(pdescription) + 1) a symbol (which is initialized to @xlcode(nil)) + + 2) a list of the form: (@i<sym> @i<init> [@i<step>]) + where: +@begin(pdescription) + @i<sym> @itemsep is the symbol to bind + + @i<init> @itemsep is the initial value of the symbol + + @i<step> @itemsep is a step expression + +@end(pdescription) +@end(pdescription)@pragma(stopcodef) + @i<texpr> @itemsep the termination test expression + + @i<rexpr> @itemsep result expressions (the default is @xlcode(nil)) + + @i<expr> @itemsep the body of the loop (treated like an implicit prog) + + returns @itemsep the value of the last result expression + +@end(pdescription) +@blankspace(1) + + (dolist@pragma(defn)@index(dolist) (@i<sym> @i<expr> [@i<rexpr>]) @i<expr>...) @itemsep loop through a list +@begin(pdescription) + @i<sym> @itemsep the symbol to bind to each list element + + @i<expr> @itemsep the list expression + + @i<rexpr> @itemsep the result expression (the default is @xlcode(nil)) + + @i<expr> @itemsep the body of the loop (treated like an implicit prog) + +@end(pdescription) +@blankspace(1) + + (dotimes@pragma(defn)@index(dotimes) (@i<sym> @i<expr> [@i<rexpr>]) @i<expr>...) @itemsep loop from zero to n-1 +@begin(pdescription) + @i<sym> @itemsep the symbol to bind to each value from 0 to n-1 + + @i<expr> @itemsep the number of times to loop + + @i<rexpr> @itemsep the result expression (the default is @xlcode(nil)) + + @i<expr> @itemsep the body of the loop (treated like an implicit prog) + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(The Program Feature)@index(The Program Feature) +@begin(fdescription) +@begin(fgroup) +(prog@pragma(defn)@index(prog) (@i<binding>...) @i<expr>...) @itemsep the program feature + +@pragma(startcodef) +(prog*@pragma(defn)@index(prog*) (@i<binding>...) @i<expr>...) @itemsep prog with sequential binding +@end(fgroup) +@begin(pdescription) + @i<binding> @itemsep the variable bindings each of which is either: + +@begin(pdescription) + 1) a symbol (which is initialized to @xlcode(nil)) + + 2) a list whose car is a symbol and whose cadr + is an initialization expression +@end(pdescription)@pragma(stopcodef) + @i<expr> @itemsep expressions to evaluate or tags (symbols) + + returns @itemsep @xlcode(nil) or the argument passed to the return function + +@end(pdescription) +@blankspace(1) + + (block@pragma(defn)@index(block) @i<name> @i<expr>...) @itemsep named block +@begin(pdescription) + @i<name> @itemsep the block name (symbol) + + @i<expr> @itemsep the block body + + returns @itemsep the value of the last expression + +@end(pdescription) +@blankspace(1) + + (return@pragma(defn)@index(return) [@i<expr>]) @itemsep cause a prog construct to return a value +@begin(pdescription) + @i<expr> @itemsep the value (defaults to @xlcode(nil)) + + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + (return-from@pragma(defn)@index(return-from) @i<name> [@i<value>]) @itemsep return from a named block +@begin(pdescription) + @i<name> @itemsep the block name (symbol) + + @i<value> @itemsep the value to return (defaults to @xlcode(nil)) + + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + (tagbody@pragma(defn)@index(tagbody) @i<expr>...) @itemsep block with labels +@begin(pdescription) + @i<expr> @itemsep expression(s) to evaluate or tags (symbols) + + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + (go@pragma(defn)@index(go) @i<sym>) @itemsep go to a tag within a tagbody or prog +@begin(pdescription) + @i<sym> @itemsep the tag (quoted) + + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + (progv@pragma(defn)@index(progv) @i<slist> @i<vlist> @i<expr>...) @itemsep dynamically bind symbols +@begin(pdescription) + @i<slist> @itemsep list of symbols + + @i<vlist> @itemsep list of values to bind to the symbols + + @i<expr> @itemsep expression(s) to evaluate + + returns @itemsep the value of the last expression + +@end(pdescription) +@blankspace(1) + + (prog1@pragma(defn)@index(prog1) @i<expr1> @i<expr>...) @itemsep execute expressions sequentially +@begin(pdescription) + @i<expr1> @itemsep the first expression to evaluate + + @i<expr> @itemsep the remaining expressions to evaluate + + returns @itemsep the value of the first expression + +@end(pdescription) +@blankspace(1) + + (prog2@pragma(defn)@index(prog2) @i<expr1> @i<expr2> @i<expr>...) @itemsep execute expressions sequentially +@begin(pdescription) + @i<expr1> @itemsep the first expression to evaluate + + @i<expr2> @itemsep the second expression to evaluate + + @i<expr> @itemsep the remaining expressions to evaluate + + returns @itemsep the value of the second expression + +@end(pdescription) +@blankspace(1) + + (progn@pragma(defn)@index(progn) @i<expr>...) @itemsep execute expressions sequentially +@begin(pdescription) + @i<expr> @itemsep the expressions to evaluate + + returns @itemsep the value of the last expression (or @xlcode(nil)) + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Debugging and Error Handling)@index(Debugging)@index(Error Handling) +@begin(fdescription) + (trace@pragma(defn)@index(trace) @i<sym>) @itemsep add a function to the trace list +@begin(pdescription) + @i<sym> @itemsep the function to add (quoted) + + returns @itemsep the trace list + +@end(pdescription) +@blankspace(1) + + (untrace@pragma(defn)@index(untrace) @i<sym>) @itemsep remove a function from the trace list +@begin(pdescription) + @i<sym> @itemsep the function to remove (quoted) + + returns @itemsep the trace list + +@end(pdescription) +@blankspace(1) + + (error@pragma(defn)@index(error) @i<emsg> [@i<arg>]) @itemsep signal a non-correctable error +@begin(pdescription) + @i<emsg> @itemsep the error message string + + @i<arg> @itemsep the argument expression (printed after the message) + + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + (cerror@pragma(defn)@index(cerror) @i<cmsg> @i<emsg> [@i<arg>]) @itemsep signal a correctable error +@begin(pdescription) + @i<cmsg> @itemsep the continue message string + + @i<emsg> @itemsep the error message string + + @i<arg> @itemsep the argument expression (printed after the message) + + returns @itemsep @xlcode(nil) when continued from the break loop + +@end(pdescription) +@blankspace(1) + + (break@pragma(defn)@index(break) [@i<bmsg> [@i<arg>]]) @itemsep enter a break loop +@begin(pdescription) + @i<bmsg> @itemsep the break message string (defaults to @xlcode(**break**)) + + @i<arg> @itemsep the argument expression (printed after the message) + + returns @itemsep @xlcode(nil) when continued from the break loop + +@end(pdescription) +@blankspace(1) + + (clean-up@pragma(defn)@index(clean-up)) @itemsep clean-up after an error +@begin(pdescription) + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + (top-level@pragma(defn)@index(top-level)) @itemsep clean-up after an error and return to the top level +@begin(pdescription) + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + (continue@pragma(defn)@index(continue)) @itemsep continue from a correctable error +@begin(pdescription) + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + (errset@pragma(defn)@index(errset) @i<expr> [@i<pflag>]) @itemsep trap errors +@begin(pdescription) + @i<expr> @itemsep the expression to execute + + @i<pflag> @itemsep flag to control printing of the error message + + returns @itemsep the value of the last expression consed with @xlcode(nil) + + or @xlcode(nil) on error +@end(pdescription) +@blankspace(1) + + (baktrace@pragma(defn)@index(baktrace)@index(debugging)@index(stack trace) [@i<n>]) @itemsep print n levels of trace back information +@begin(pdescription) + @i<n> @itemsep the number of levels (defaults to all levels) + + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + (evalhook@pragma(defn)@index(evalhook) @i<expr> @i<ehook> @i<ahook> [@i<env>]) @itemsep evaluate with hooks +@begin(pdescription) + @i<expr> @itemsep the expression to evaluate + + @i<ehook> @itemsep the value for @xlcode(*evalhook*) + + @i<ahook> @itemsep the value for @xlcode(*applyhook*) + + @i<env> @itemsep the environment (default is @xlcode(nil)) + + returns @itemsep the result of evaluating the expression + +@end(pdescription) +@blankspace(1) + + (profile@pragma(defn)@index(profile) @i(flag))@foot(This is not a standard XLISP 2.0 function.) @itemsep turn profiling on or off. +@begin(pdescription) + @i<flag> @itemsep @xlcode(nil) turns profiling off, otherwise on + + returns @itemsep the previous state of profiling. + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Arithmetic Functions)@index(Arithmetic Functions) +@begin(fdescription) + (truncate@pragma(defn)@index(truncate) @i<expr>) @itemsep truncates a floating point number to an integer +@begin(pdescription) + @i<expr> @itemsep the number + + returns @itemsep the result of truncating the number + +@end(pdescription) +@blankspace(1) + + (float@pragma(defn)@index(float) @i<expr>) @itemsep converts an integer to a floating point number +@begin(pdescription) + @i<expr> @itemsep the number + + returns @itemsep the result of floating the integer + +@end(pdescription) +@blankspace(1) + + (+@pragma(defn)@index(+) @i<expr>...) @itemsep add a list of numbers +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the addition + +@end(pdescription) +@blankspace(1) + + (-@pragma(defn)@index(-) @i<expr>...) @itemsep subtract a list of numbers or negate a single number +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the subtraction + +@end(pdescription) +@blankspace(1) + + (*@pragma(defn)@index(*) @i<expr>...) @itemsep multiply a list of numbers +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the multiplication + +@end(pdescription) +@blankspace(1) + + (/@pragma(defn)@index(/) @i<expr>...) @itemsep divide a list of numbers +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the division + +@end(pdescription) +@blankspace(1) + + (1+@pragma(defn)@index(1+) @i<expr>) @itemsep add one to a number +@begin(pdescription) + @i<expr> @itemsep the number + + returns @itemsep the number plus one + +@end(pdescription) +@blankspace(1) + + (1-@pragma(defn)@index(1-) @i<expr>) @itemsep subtract one from a number +@begin(pdescription) + @i<expr> @itemsep the number + + returns @itemsep the number minus one + +@end(pdescription) +@blankspace(1) + + (rem@pragma(defn)@index(rem)@index(remainder)@index(modulo (rem) function) @i<expr>...) @itemsep remainder of a list of numbers +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the remainder operation + +@end(pdescription) +@blankspace(1) + + (min@pragma(defn)@index(min)@index(minimum) @i<expr>...) @itemsep the smallest of a list of numbers +@begin(pdescription) + @i<expr> @itemsep the expressions to be checked + + returns @itemsep the smallest number in the list + +@end(pdescription) +@blankspace(1) + + (max@pragma(defn)@index(max)@index(maximum) @i<expr>...) @itemsep the largest of a list of numbers +@begin(pdescription) + @i<expr> @itemsep the expressions to be checked + + returns @itemsep the largest number in the list + +@end(pdescription) +@blankspace(1) + + (abs@pragma(defn)@index(abs) @i<expr>) @itemsep the absolute value of a number +@begin(pdescription) + @i<expr> @itemsep the number + + returns @itemsep the absolute value of the number + +@end(pdescription) +@blankspace(1) + + (gcd@pragma(defn)@index(gcd) @i<n1> @i<n2>...) @itemsep compute the greatest common divisor +@begin(pdescription) + @i<n1> @itemsep the first number (integer) + + @i<n2> @itemsep the second number(s) (integer) + + returns @itemsep the greatest common divisor + +@end(pdescription) +@blankspace(1) + + (random@pragma(defn)@index(random) @i<n>) @itemsep compute a random number between 0 and n-1 inclusive +@begin(pdescription) + @i<n> @itemsep the upper bound (integer) + + returns @itemsep a random number + +@end(pdescription) +@blankspace(1) + + (rrandom@pragma(defn)@index(rrandom)@index(uniform random)) @itemsep compute a random real number between 0 and 1 inclusive +@begin(pdescription) + returns @itemsep a random floating point number + +@end(pdescription) +@blankspace(1) + + (sin@pragma(defn)@index(sin) @i<expr>) @itemsep compute the sine of a number +@begin(pdescription) + @i<expr> @itemsep the floating point number + + returns @itemsep the sine of the number + +@end(pdescription) +@blankspace(1) + + (cos@pragma(defn)@index(cos) @i<expr>) @itemsep compute the cosine of a number +@begin(pdescription) + @i<expr> @itemsep the floating point number + + returns @itemsep the cosine of the number + +@end(pdescription) +@blankspace(1) + + (tan@pragma(defn)@index(tan) @i<expr>) @itemsep compute the tangent of a number +@begin(pdescription) + @i<expr> @itemsep the floating point number + + returns @itemsep the tangent of the number + +@end(pdescription) +@blankspace(1) + + (atan@pragma(defn)@index(atan) @i<expr> [@i<expr2>])@foot(This is not a standard XLISP 2.0 function.) @itemsep compute the arctangent +@begin(pdescription) + @i<expr> @itemsep the value of @i(x) + + @i<expr2> @itemsep the value of @i(y) (default value is 1.0) + + returns @itemsep the arctangent of @i(x)/@i(y) + +@end(pdescription) +@blankspace(1) + + (expt@pragma(defn)@index(expt) @i<x-expr> @i<y-expr>) @itemsep compute x to the y power +@begin(pdescription) + @i<x-expr> @itemsep the floating point number + + @i<y-expr> @itemsep the floating point exponent + + returns @itemsep x to the y power + +@end(pdescription) +@blankspace(1) + + (exp@pragma(defn)@index(exp) @i<x-expr>) @itemsep compute e to the x power +@begin(pdescription) + @i<x-expr> @itemsep the floating point number + + returns @itemsep e to the x power + +@end(pdescription) +@blankspace(1) + + (sqrt@pragma(defn)@index(sqrt) @i<expr>) @itemsep compute the square root of a number +@begin(pdescription) + @i<expr> @itemsep the floating point number + + returns @itemsep the square root of the number + +@end(pdescription) +@blankspace(1) +@begin(fgroup) +(<@pragma(defn)@index(<) @i<n1> @i<n2>...) @itemsep test for less than + +(<=@pragma(defn)@index(<=) @i<n1> @i<n2>...) @itemsep test for less than or equal to + +(=@pragma(defn)@index(=) @i<n1> @i<n2>...) @itemsep test for equal to + +(/=@pragma(defn)@index(/=) @i<n1> @i<n2>...) @itemsep test for not equal to + +(>=@pragma(defn)@index(>=) @i<n1> @i<n2>...) @itemsep test for greater than or equal to + +(>@pragma(defn)@index(>) @i<n1> @i<n2>...) @itemsep test for greater than +@end(fgroup) +@begin(pdescription) + @i<n1> @itemsep the first number to compare + + @i<n2> @itemsep the second number to compare + +returns @itemsep @xlcode(t) if the results of comparing @i<n1> with @i<n2>, +@i<n2> with @i<n3>, etc., are all true. + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Bitwise Logical Functions)@index(Bitwise Logical Functions) +@begin(fdescription) + (logand@pragma(defn)@index(logand) @i<expr>...) @itemsep the bitwise and of a list of numbers +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the and operation + +@end(pdescription) +@blankspace(1) + + (logior@pragma(defn)@index(logior) @i<expr>...) @itemsep the bitwise inclusive or of a list of numbers +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the inclusive or operation + +@end(pdescription) +@blankspace(1) + + (logxor@pragma(defn)@index(logxor) @i<expr>...) @itemsep the bitwise exclusive or of a list of numbers +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the exclusive or operation + +@end(pdescription) +@blankspace(1) + + (lognot@pragma(defn)@index(lognot) @i<expr>) @itemsep the bitwise not of a number +@begin(pdescription) + @i<expr> @itemsep the number + + returns @itemsep the bitwise inversion of number + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(String Functions)@index(String Functions) +@begin(fdescription) + (string@pragma(defn)@index(string) @i<expr>) @itemsep make a string from a value +@begin(pdescription) + @i<expr> @itemsep an integer (which is first converted into its ASCII character value), string, character, or symbol + + returns @itemsep the string representation of the argument + +@end(pdescription) +@blankspace(1) + + (string-search@pragma(defn)@index(string-search)@index(find string) @i<pat> @i<str> &key :start :end)@foot(This is not a standard XLISP 2.0 function.) @itemsep search for pattern in string +@begin(pdescription) + @i<pat> @itemsep a string to search for + + @i<str> @itemsep the string to be searched + + :start @itemsep the starting offset in str + + :end @itemsep the ending offset + 1 + + returns @itemsep index of pat in str or NIL if not found + +@end(pdescription) +@blankspace(1) + + (string-trim@pragma(defn)@index(string-trim) @i<bag> @i<str>) @itemsep trim both ends of a string +@begin(pdescription) + @i<bag> @itemsep a string containing characters to trim + + @i<str> @itemsep the string to trim + + returns @itemsep a trimed copy of the string + +@end(pdescription) +@blankspace(1) + + (string-left-trim@pragma(defn)@index(string-left-trim) @i<bag> @i<str>) @itemsep trim the left end of a string +@begin(pdescription) + @i<bag> @itemsep a string containing characters to trim + + @i<str> @itemsep the string to trim + + returns @itemsep a trimed copy of the string + +@end(pdescription) +@blankspace(1) + + (string-right-trim@pragma(defn)@index(string-right-trim) @i<bag> @i<str>) @itemsep trim the right end of a string +@begin(pdescription) + @i<bag> @itemsep a string containing characters to trim + + @i<str> @itemsep the string to trim + + returns @itemsep a trimed copy of the string + +@end(pdescription) +@blankspace(1) + + (string-upcase@pragma(defn)@index(string-upcase) @i<str> &key :start :end) @itemsep convert to uppercase +@begin(pdescription) + @i<str> @itemsep the string + + :start @itemsep the starting offset + + :end @itemsep the ending offset + 1 + + returns @itemsep a converted copy of the string + +@end(pdescription) +@blankspace(1) + + (string-downcase@pragma(defn)@index(string-downcase) @i<str> &key :start :end) @itemsep convert to lowercase +@begin(pdescription) + @i<str> @itemsep the string + + :start @itemsep the starting offset + + :end @itemsep the ending offset + 1 + + returns @itemsep a converted copy of the string + +@end(pdescription) +@blankspace(1) + + (nstring-upcase@pragma(defn)@index(nstring-upcase) @i<str> &key :start :end) @itemsep convert to uppercase +@begin(pdescription) + @i<str> @itemsep the string + + :start @itemsep the starting offset + + :end @itemsep the ending offset + 1 + + returns @itemsep the converted string (not a copy) + +@end(pdescription) +@blankspace(1) + + (nstring-downcase@pragma(defn)@index(nstring-downcase) @i<str> &key :start :end) @itemsep convert to lowercase +@begin(pdescription) + @i<str> @itemsep the string + + :start @itemsep the starting offset + + :end @itemsep the ending offset + 1 + + returns @itemsep the converted string (not a copy) + +@end(pdescription) +@blankspace(1) + + (strcat@pragma(defn)@index(strcat)@index(concatenate strings) @i<expr>...) @itemsep concatenate strings +@begin(pdescription) + @i<expr> @itemsep the strings to concatenate + + returns @itemsep the result of concatenating the strings + +@end(pdescription) +@blankspace(1) + + (subseq@pragma(defn)@index(subseq) @i<string> @i<start> [@i<end>]) @itemsep extract a substring +@begin(pdescription) + @i<string> @itemsep the string + + @i<start> @itemsep the starting position (zero origin) + + @i<end> @itemsep the ending position + 1 (defaults to end) + + returns @itemsep substring between @i<start> and @i<end> + +@end(pdescription) +@blankspace(1) +@begin(fgroup) + (string<@pragma(defn)@index(string<) @i<str1> @i<str2> &key :start1 :end1 :start2 :end2) +@pragma(endcodef) + (string<=@pragma(defn)@index(string<=) @i<str1> @i<str2> &key :start1 :end1 :start2 :end2) +@pragma(endcodef) + + (string=@pragma(defn)@index(string=) @i<str1> @i<str2> &key :start1 :end1 :start2 :end2) +@pragma(endcodef) + + (string/=@pragma(defn)@index(string/=) @i<str1> @i<str2> &key :start1 :end1 :start2 :end2) +@pragma(endcodef) + + (string>=@pragma(defn)@index(string>=) @i<str1> @i<str2> &key :start1 :end1 :start2 :end2) +@pragma(endcodef) + + (string>@pragma(defn)@index(string>) @i<str1> @i<str2> &key :start1 :end1 :start2 :end2) +@end(fgroup) +@begin(pdescription) + @i<str1> @itemsep the first string to compare + + @i<str2> @itemsep the second string to compare + + :start1 @itemsep first substring starting offset + + :end1 @itemsep first substring ending offset + 1 + + :start2 @itemsep second substring starting offset + + :end2 @itemsep second substring ending offset + 1 + + returns @itemsep @xlcode(t) if predicate is true, @xlcode(nil) otherwise + + Note: case is significant with these comparison functions. +@end(pdescription) +@blankspace(1) +@begin(fgroup) +(string-lessp@pragma(defn)@index(string-lessp) @i<str1> @i<str2> &key :start1 :end1 :start2 :end2) +@pragma(endcodef) + +(string-not-greaterp@pragma(defn)@index(string-not-greaterp) @i<str1> @i<str2> &key :start1 :end1 :start2 :end2) +@pragma(endcodef) + +(string-equalp@pragma(defn)@index(string-equalp) @i<str1> @i<str2> &key :start1 :end1 :start2 :end2) +@pragma(endcodef) + +(string-not-equalp@pragma(defn)@index(string-not-equalp) @i<str1> @i<str2> &key :start1 :end1 :start2 :end2) +@pragma(endcodef) + +(string-not-lessp@pragma(defn)@index(string-not-lessp) @i<str1> @i<str2> &key :start1 :end1 :start2 :end2) +@pragma(endcodef) + +(string-greaterp@pragma(defn)@index(string-greaterp) @i<str1> @i<str2> &key :start1 :end1 :start2 :end2) +@end(fgroup) +@begin(pdescription) + @i<str1> @itemsep the first string to compare + + @i<str2> @itemsep the second string to compare + + :start1 @itemsep first substring starting offset + + :end1 @itemsep first substring ending offset + 1 + + :start2 @itemsep second substring starting offset + + :end2 @itemsep second substring ending offset + 1 + + returns @itemsep @xlcode(t) if predicate is true, @xlcode(nil) otherwise + + Note: case is not significant with these comparison functions. +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Character Functions)@index(Character Functions) +@begin(fdescription) + (char@pragma(defn)@index(char) @i<string> @i<index>) @itemsep extract a character from a string +@begin(pdescription) + @i<string> @itemsep the string + + @i<index> @itemsep the string index (zero relative) + + returns @itemsep the ascii code of the character + +@end(pdescription) +@blankspace(1) + + (upper-case-p@pragma(defn)@index(upper-case-p) @i<chr>) @itemsep is this an upper case character? +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep @xlcode(t) if the character is upper case, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (lower-case-p@pragma(defn)@index(lower-case-p) @i<chr>) @itemsep is this a lower case character? +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep @xlcode(t) if the character is lower case, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (both-case-p@pragma(defn)@index(both-case-p) @i<chr>) @itemsep is this an alphabetic (either case) character? +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep @xlcode(t) if the character is alphabetic, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (digit-char-p@pragma(defn)@index(digit-char-p) @i<chr>) @itemsep is this a digit character? +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep the digit weight if character is a digit, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (char-code@pragma(defn)@index(char-code) @i<chr>) @itemsep get the ascii code of a character +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep the ascii character code (integer) + +@end(pdescription) +@blankspace(1) + + (code-char@pragma(defn)@index(code-char) @i<code>) @itemsep get the character with a specified ascii code +@begin(pdescription) + @i<code> @itemsep the ascii code (integer) + + returns @itemsep the character with that code or @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + (char-upcase@pragma(defn)@index(char-upcase) @i<chr>) @itemsep convert a character to upper case +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep the upper case character + +@end(pdescription) +@blankspace(1) + + (char-downcase@pragma(defn)@index(char-downcase) @i<chr>) @itemsep convert a character to lower case +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep the lower case character + +@end(pdescription) +@blankspace(1) + + (digit-char@pragma(defn)@index(digit-char) @i<n>) @itemsep convert a digit weight to a digit +@begin(pdescription) + @i<n> @itemsep the digit weight (integer) + + returns @itemsep the digit character or @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + (char-int@pragma(defn)@index(char-int) @i<chr>) @itemsep convert a character to an integer +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep the ascii character code + +@end(pdescription) +@blankspace(1) + + (int-char@pragma(defn)@index(int-char) @i<int>) @itemsep convert an integer to a character +@begin(pdescription) + @i<int> @itemsep the ascii character code + + returns @itemsep the character with that code + +@end(pdescription) +@blankspace(1) +@begin(fgroup) + (char<@pragma(defn)@index(char<) @i<chr1> @i<chr2>...) +@pragma(endcodef) + + (char<=@pragma(defn)@index(char<=) @i<chr1> @i<chr2>...) +@pragma(endcodef) + + (char=@pragma(defn)@index(char=) @i<chr1> @i<chr2>...) +@pragma(endcodef) + + (char/=@pragma(defn)@index(char/=) @i<chr1> @i<chr2>...) +@pragma(endcodef) + + (char>=@pragma(defn)@index(char>=) @i<chr1> @i<chr2>...) +@pragma(endcodef) + + (char>@pragma(defn)@index(char>) @i<chr1> @i<chr2>...) +@end(fgroup) +@begin(pdescription) + @i<chr1> @itemsep the first character to compare + + @i<chr2> @itemsep the second character(s) to compare + + returns @itemsep @xlcode(t) if predicate is true, @xlcode(nil) otherwise + + Note: case is significant with these comparison functions. +@end(pdescription) +@blankspace(1) +@begin(fgroup) +(char-lessp@pragma(defn)@index(char-lessp) @i<chr1> @i<chr2>...) +@pragma(endcodef) + +(char-not-greaterp@pragma(defn)@index(char-not-greaterp) @i<chr1> @i<chr2>...) +@pragma(endcodef) + +(char-equalp@pragma(defn)@index(char-equalp) @i<chr1> @i<chr2>...) +@pragma(endcodef) + +(char-not-equalp@pragma(defn)@index(char-not-equalp) @i<chr1> @i<chr2>...) +@pragma(endcodef) + +(char-not-lessp@pragma(defn)@index(char-not-lessp) @i<chr1> @i<chr2>...) +@pragma(endcodef) + +(char-greaterp@pragma(defn)@index(char-greaterp) @i<chr1> @i<chr2>...) +@end(fgroup) +@begin(pdescription) +@i<chr1> @itemsep the first string to compare + +@i<chr2> @itemsep the second string(s) to compare + +returns @itemsep @xlcode(t) if predicate is true, @xlcode(nil) otherwise + + Note: case is not significant with these comparison functions. +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Input/Output Functions)@index(Input/Output Functions) +@begin(fdescription) + (read@pragma(defn)@index(read) [@i<stream> [@i<eof> [@i<rflag>]]]) @itemsep read an expression +@begin(pdescription) + @i<stream> @itemsep the input stream (default is standard input) + + @i<eof> @itemsep the value to return on end of file (default is @xlcode(nil)) + + @i<rflag> @itemsep recursive read flag (default is @xlcode(nil)) + + returns @itemsep the expression read + +@end(pdescription) +@blankspace(1) + + (print@pragma(defn)@index(print) @i<expr> [@i<stream>]) @itemsep print an expression on a new line +@begin(pdescription) + @i<expr> @itemsep the expression to be printed + + @i<stream> @itemsep the output stream (default is standard output) + + returns @itemsep the expression + +@end(pdescription) +@blankspace(1) + + (prin1@pragma(defn)@index(prin1) @i<expr> [@i<stream>]) @itemsep print an expression +@begin(pdescription) + @i<expr> @itemsep the expression to be printed + + @i<stream> @itemsep the output stream (default is standard output) + + returns @itemsep the expression + +@end(pdescription) +@blankspace(1) + + (princ@pragma(defn)@index(princ) @i<expr> [@i<stream>]) @itemsep print an expression without quoting +@begin(pdescription) + @i<expr> @itemsep the expressions to be printed + + @i<stream> @itemsep the output stream (default is standard output) + + returns @itemsep the expression + +@end(pdescription) +@blankspace(1) + + (pprint@pragma(defn)@index(pprint) @i<expr> [@i<stream>]) @itemsep pretty print an expression +@begin(pdescription) + @i<expr> @itemsep the expressions to be printed + + @i<stream> @itemsep the output stream (default is standard output) + + returns @itemsep the expression + +@end(pdescription) +@blankspace(1) + + (terpri@pragma(defn)@index(terpri) [@i<stream>]) @itemsep terminate the current print line +@begin(pdescription) + @i<stream> @itemsep the output stream (default is standard output) + + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + (flatsize@pragma(defn)@index(flatsize) @i<expr>) @itemsep length of printed representation using prin1 +@begin(pdescription) + @i<expr> @itemsep the expression + + returns @itemsep the length + +@end(pdescription) +@blankspace(1) + + (flatc@pragma(defn)@index(flatc) @i<expr>) @itemsep length of printed representation using princ +@begin(pdescription) + @i<expr> @itemsep the expression + + returns @itemsep the length +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(The Format Function)@index(The Format Function) +@begin(fdescription) +(format@pragma(defn)@index(format) @i<stream> @i<fmt> @i<arg>...) @itemsep do formated +output +@begin(pdescription) + @i<stream> @itemsep the output stream + + @i<fmt> @itemsep the format string + + @i<arg> @itemsep the format arguments + + returns @itemsep output string if @i<stream> is @xlcode(nil), @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) +@end(fdescription) + The format string can contain characters that should be copied + directly to the output and formatting directives. The + formatting directives are: +@begin(display) +@xlcode(~A) @itemsep print next argument using princ +@xlcode(~S) @itemsep print next argument using prin1 +@xlcode(~%) @itemsep start a new line +@xlcode(~~) @itemsep print a tilde character +@xlcode(~)<newline> @itemsep ignore this one newline and white space on the +next line up to the first non-white-space character or newline. This +allows strings to continue across multiple lines +@end(display) + +@section(File I/O Functions)@index(File I/O Functions) +Note that files are ordinarily opened as text. Binary files (such as standard midi files) must be opened with @xlcode(open-binary) on non-unix systems. +@begin(fdescription) + (open@pragma(defn)@index(open) @i<fname> &key :direction) @itemsep open a file stream +@begin(pdescription) + @i<fname> @itemsep the file name string or symbol + + :direction @itemsep :input or :output (default is :input) + + returns @itemsep a stream + +@end(pdescription) +@blankspace(1) + (open-binary@pragma(defn)@index(open-binary)@index(open)@index(binary files) @i<fname> &key :direction) @itemsep open a binary file stream +@begin(pdescription) + @i<fname> @itemsep the file name string or symbol + + :direction @itemsep :input or :output (default is :input) + + returns @itemsep a stream + +@end(pdescription) +@blankspace(1) + + (close@pragma(defn)@index(close) @i<stream>) @itemsep close a file stream +@begin(pdescription) + @i<stream> @itemsep the stream + + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + (setdir@pragma(defn)@index(setdir)@index(change directory) @i<path>)@foot(This is not a standard XLISP 2.0 function.) @itemsep set current directory +@begin(pdescription) + @i<path> @itemsep the path of the new directory + + returns @itemsep the resulting full path, e.g. (setdir ".") gets the current working directory, or @xlcode(nil) if an error occurs + +@end(pdescription) +@blankspace(1) + + (listdir@pragma(defn)@index(listdir)@index(directory listing)@index(scan directory)@index(read directory)@index(list directory) @i<path>)@foot(This is not a standard XLISP 2.0 function.) @itemsep get a directory listing +@begin(pdescription) + @i<path> @itemsep the path of the directory to be listed + + returns @itemsep list of filenames in the directory + +@end(pdescription) +@blankspace(1) + + (get-temp-path@pragma(defn)@index(get-temp-path)@index(temporary files)@index(temp file))@foot(This is not a standard XLISP 2.0 function.) @itemsep get a path where a temporary file can be created. Under Windows, this is based on environment variables. If XLISP is running as a sub-process to Java, the environment may not exist, in which case the default result is the unfortunate choice @xlcode(c:\windows\). +@begin(pdescription) + returns @itemsep the resulting full path as a string + +@end(pdescription) +@blankspace(1) + + (get-user@pragma(defn)@index(get-user)@index(user name)@index(temp file))@foot(This is not a standard XLISP 2.0 function.) @itemsep get the user ID. In Unix systems (including OS X and Linux), this is the value of the USER environment variable. In Windows, this is currently just ``nyquist'', which is also returned if the environment variable cannot be accessed. This function is used to avoid the case of two users creating files of the same name in the same temp directory. +@begin(pdescription) + returns @itemsep the string naming the user + +@end(pdescription) +@blankspace(1) + (find-in-xlisp-path@pragma(defn)@index(find-in-xlisp-path) @i<filename>)@foot(This is not a standard XLISP 2.0 function.) @itemsep search the XLISP search path (e.g. @xlcode(XLISPPATH) from the environment) for @i(filename). If @i(filename) is not found as is, and there is no file extension, append "@code(.lsp)" to @i(filename) and search again. The current directory is not searched. +@begin(pdescription) + @i<filename> @itemsep the name of the file to search for + + returns @itemsep a full path name to the first occurrence found + +@end(pdescription) +@blankspace(1) + + (read-char@pragma(defn)@index(read-char)@index(get char) [@i<stream>]) @itemsep read a character from a stream +@begin(pdescription) + @i<stream> @itemsep the input stream (default is standard input) + + returns @itemsep the character + +@end(pdescription) +@blankspace(1) + + (peek-char@pragma(defn)@index(peek-char) [@i<flag> [@i<stream>]]) @itemsep peek at the next character +@begin(pdescription) + @i<flag> @itemsep flag for skipping white space (default is @xlcode(nil)) + + @i<stream> @itemsep the input stream (default is standard input) + + returns @itemsep the character (integer) + +@end(pdescription) +@blankspace(1) + + (write-char@pragma(defn)@index(write-char) @i<ch> [@i<stream>]) @itemsep write a character to a stream +@begin(pdescription) + @i<ch> @itemsep the character to write + + @i<stream> @itemsep the output stream (default is standard output) + + returns @itemsep the character + +@end(pdescription) +@blankspace(1) + + (read-int@pragma(defn)@index(read-int) [@i<stream> [@i<length>]]) @itemsep read a binary integer from a stream +@begin(pdescription) + @i<stream> @itemsep the input stream (default is standard input) + + @i<length> @itemsep the length of the integer in bytes (default is 4) + + returns @itemsep the integer + +Note: Integers are assumed to be big-endian (high-order byte first) and +signed, regardless of the platform. To read little-endian format, use a +negative number for the length, e.g. -4 indicates a 4-bytes, low-order +byte first. The file should be opened in binary mode. + +@end(pdescription) +@blankspace(1) + + (write-int@pragma(defn)@index(write-int) @i<ch> [@i<stream> [@i<length>]]) @itemsep write a binary integer to a stream +@begin(pdescription) + @i<ch> @itemsep the character to write + + @i<stream> @itemsep the output stream (default is standard output) + + @i<length> @itemsep the length of the integer in bytes (default is 4) + + returns @itemsep the integer + +Note: Integers are assumed to be big-endian (high-order byte first) and +signed, regardless of the platform. To write in little-endian format, use a +negative number for the length, e.g. -4 indicates a 4-bytes, low-order +byte first. The file should be opened in binary mode. + +@end(pdescription) +@blankspace(1) + + (read-float@pragma(defn)@index(read-float) [@i<stream> [@i<length>]]) @itemsep read a binary floating-point number from a stream +@begin(pdescription) + @i<stream> @itemsep the input stream (default is standard input) + + @i<length> @itemsep the length of the float in bytes (default is 4, legal values are -4, -8, 4, and 8) + + returns @itemsep the integer + +Note: Floats are assumed to be big-endian (high-order byte first) and +signed, regardless of the platform. To read little-endian format, use a +negative number for the length, e.g. -4 indicates a 4-bytes, low-order +byte first. The file should be opened in binary mode. + +@end(pdescription) +@blankspace(1) + + (write-float@pragma(defn)@index(write-float) @i<ch> [@i<stream> [@i<length>]]) @itemsep write a binary floating-point number to a stream +@begin(pdescription) + @i<ch> @itemsep the character to write + + @i<stream> @itemsep the output stream (default is standard output) + + @i<length> @itemsep the length of the float in bytes (default is 4, legal values are -4, -8, 4, and 8) + + returns @itemsep the integer + +Note: Floats are assumed to be big-endian (high-order byte first) and +signed, regardless of the platform. To write in little-endian format, use a +negative number for the length, e.g. -4 indicates a 4-bytes, low-order +byte first. The file should be opened in binary mode. + +@end(pdescription) +@blankspace(1) + + (read-line@pragma(defn)@index(read-line) [@i<stream>]) @itemsep read a line from a stream +@begin(pdescription) + @i<stream> @itemsep the input stream (default is standard input) + + returns @itemsep the string + +@end(pdescription) +@blankspace(1) + + (read-byte@pragma(defn)@index(read-byte) [@i<stream>]) @itemsep read a byte from a stream +@begin(pdescription) + @i<stream> @itemsep the input stream (default is standard input) + + returns @itemsep the byte (integer) + +@end(pdescription) +@blankspace(1) + + (write-byte@pragma(defn)@index(write-byte) @i<byte> [@i<stream>]) @itemsep write a byte to a stream +@begin(pdescription) + @i<byte> @itemsep the byte to write (integer) + + @i<stream> @itemsep the output stream (default is standard output) + + returns @itemsep the byte (integer) + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(String Stream Functions)@index(String Stream Functions) + These functions operate on unnamed streams. An unnamed output + stream collects characters sent to it when it is used as the + destination of any output function. The functions +@xlcode(get-output-stream-string) and @xlcode(get-output-stream-list) return a string or a list of characters. + +An unnamed input stream is setup with the + @xlcode(make-string-input-stream) function and returns each character of the string when + it is used as the source of any input function. + +@begin(fdescription) +@blankspace(1) + (make-string-input-stream@pragma(defn)@index(make-string-input-stream) @i<str> [@i<start> [@i<end>]]) +@begin(pdescription) + @i<str> @itemsep the string + + @i<start> @itemsep the starting offset + + @i<end> @itemsep the ending offset + 1 + + returns @itemsep an unnamed stream that reads from the string + +@end(pdescription) +@blankspace(1) + + (make-string-output-stream)@pragma(defn)@index(make-string-output-stream) +@begin(pdescription) + returns @itemsep an unnamed output stream + +@end(pdescription) +@blankspace(1) + + (get-output-stream-string@pragma(defn)@index(get-output-stream-string) @i<stream>) +@begin(pdescription) + @i<stream> @itemsep the output stream + + returns @itemsep the output so far as a string + + Note: the output stream is emptied by this function +@end(pdescription) +@blankspace(1) + + (get-output-stream-list@pragma(defn)@index(get-output-stream-list) @i<stream>) +@begin(pdescription) + @i<stream> @itemsep the output stream + + returns @itemsep the output so far as a list + + Note: the output stream is emptied by this function +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(System Functions)@index(System Functions) +Note: the @xlcode(load) function first tries to load a file from the current directory. A @code(.lsp) extension is added if there is not already an alphanumeric extension following a period. If that fails, XLISP searches the path, which is obtained from the XLISPPATH environment variable in Unix and HKEY_LOCAL_MACHINE\SOFTWARE\CMU\Nyquist\XLISPPATH under Win32. (The Macintosh version has no search path.) + +@begin(fdescription) + (get-env@pragma(defn)@index(get-env)@index(getenv)@index(environment variables) @i<name>) @itemsep get from an environment variable +@begin(pdescription) + @i<name> @itemsep the name of the environment variable + + returns @itemsep string value of the environment variable, @xlcode(nil) if variable does not exist + +@end(pdescription) +@blankspace(1) + + (load@pragma(defn)@index(load) @i<fname> &key :verbose :print) @itemsep load a source file +@begin(pdescription) + @i<fname> @itemsep the filename string or symbol + + :verbose @itemsep the verbose flag (default is t) + + :print @itemsep the print flag (default is @xlcode(nil)) + + returns @itemsep the filename + +@end(pdescription) +@blankspace(1) + + (save@pragma(defn)@index(save) @i<fname>) @itemsep save workspace to a file +@begin(pdescription) + @i<fname> @itemsep the filename string or symbol + + returns @itemsep @xlcode(t) if workspace was written, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + (restore@pragma(defn)@index(restore) @i<fname>) @itemsep restore workspace from a file +@begin(pdescription) + @i<fname> @itemsep the filename string or symbol + + returns @itemsep @xlcode(nil) on failure, otherwise never returns + +@end(pdescription) +@blankspace(1) + + (dribble@pragma(defn)@index(dribble) [@i<fname>]) @itemsep create a file with a transcript of a session +@begin(pdescription) + @i<fname> @itemsep file name string or symbol + (if missing, close current transcript) + + returns @itemsep @xlcode(t) if the transcript is opened, @xlcode(nil) if it is closed + +@end(pdescription) +@blankspace(1) + + (gc@pragma(defn)@index(gc)) @itemsep force garbage collection +@begin(pdescription) + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + (expand@pragma(defn)@index(expand) @i<num>) @itemsep expand memory by adding segments +@begin(pdescription) + @i<num> @itemsep the number of segments to add + + returns @itemsep the number of segments added + +@end(pdescription) +@blankspace(1) + + (alloc@pragma(defn)@index(alloc) @i<num>) @itemsep change number of nodes to allocate in each segment +@begin(pdescription) + @i<num> @itemsep the number of nodes to allocate + + returns @itemsep the old number of nodes to allocate + +@end(pdescription) +@blankspace(1) + + (info@pragma(defn)@index(info)) @itemsep show information about memory usage. +@begin(pdescription) + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + (room@pragma(defn)@index(room)) @itemsep show memory allocation statistics +@begin(pdescription) + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + (type-of@pragma(defn)@index(type-of) @i<expr>) @itemsep returns the type of the expression +@begin(pdescription) + @i<expr> @itemsep the expression to return the type of + + returns @itemsep @xlcode(nil) if the value is @xlcode(nil) otherwise one of the symbols: + +@begin(pdescription) + SYMBOL @itemsep for symbols + + OBJECT @itemsep for objects + + CONS @itemsep for conses + + SUBR @itemsep for built-in functions + + FSUBR @itemsep for special forms + + CLOSURE @itemsep for defined functions + + STRING @itemsep for strings + + FIXNUM @itemsep for integers + + FLONUM @itemsep for floating point numbers + + CHARACTER @itemsep for characters + + FILE-STREAM @itemsep for file pointers + + UNNAMED-STREAM @itemsep for unnamed streams + + ARRAY @itemsep for arrays + +@end(pdescription) +@end(pdescription) +@blankspace(1) + + (peek@pragma(defn)@index(peek) @i<addrs>) @itemsep peek at a location in memory +@begin(pdescription) + @i<addrs> @itemsep the address to peek at (integer) + + returns @itemsep the value at the specified address (integer) + +@end(pdescription) +@blankspace(1) + + (poke@pragma(defn)@index(poke) @i<addrs> @i<value>) @itemsep poke a value into memory +@begin(pdescription) + @i<addrs> @itemsep the address to poke (integer) + + @i<value> @itemsep the value to poke into the address (integer) + + returns @itemsep the value + +@end(pdescription) +@blankspace(1) + + (bigendianp@pragma(defn)@index(bigendianp)@index(endian)@index(big endian)@index(little endian)) @itemsep is this a big-endian machine? +@begin(pdescription) + returns @itemsep T if this a big-endian architecture, storing the high-order byte of an integer at the lowest byte address of the integer; otherwise, NIL. +@foot(This is not a standard XLISP 2.0 function.) + +@end(pdescription) +@blankspace(1) + + (address-of@pragma(defn)@index(address-of) @i<expr>) @itemsep get the address of an xlisp node +@begin(pdescription) + @i<expr> @itemsep the node + + returns @itemsep the address of the node (integer) + +@end(pdescription) +@blankspace(1) + + (exit@pragma(defn)@index(exit)) @itemsep exit xlisp +@begin(pdescription) + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + (setup-console@pragma(defn)@index(setup-console)@index(window initialization)) @itemsep set default console attributes +@begin(pdescription) + returns @itemsep NIL + +Note: Under Windows, Nyquist normally starts up in a medium-sized console window with black text and a white background, with a window title of ``Nyquist.'' This is normally accomplished by calling @xlcode(setup-console) in @code(system.lsp). In Nyquist, you can avoid this behavior by setting @xlcode(*setup-console*) to NIL in your @code(init.lsp) file. If @xlcode(setup-console) is not called, Nyquist uses standard input and output as is. This is what you want if you are running Nyquist inside of emacs, for example.@index(emacs, using Nyquist with) + +@end(pdescription) +@blankspace(1) + + (echoenabled@pragma(defn)@index(echoenabled)@index(console, XLISP) @i<flag>) @itemsep turn console input echoing on or off +@begin(pdescription) + @i<flag> @itemsep T to enable echo, NIL to disable + + returns @itemsep NIL + +Note: This function is only implemented under Linux and Mac OS X. If Nyquist I/O is redirected through pipes, +the Windows version does not echo the input, but the Linux and Mac versions do. You can turn off echoing with +this function. Under windows it is defined to do nothing. + +@end(pdescription) +@end(fdescription) + +@section(File I/O Functions)@index(File I/O Functions) + +@subsection(Input from a File)@index(Input from a File) + +To open a file for input, use the @xlcode(open) function with the keyword +argument @xlcode(:direction) set to @xlcode(:input). To open a file for output, +use the @xlcode(open) function with the keyword argument @xlcode(:direction) set +to @xlcode(:output). The @xlcode(open) function takes a single required argument which +is the name of the file to be opened. This name can be in the form of a +string or a symbol. The @xlcode(open) function returns an object of type +@xlcode(FILE-STREAM) if it succeeds in opening the specified file. It returns the +value @xlcode(nil) if it fails. In order to manipulate the file, it is +necessary to save the value returned by the @xlcode(open) function. This is +usually done by assigning it to a variable with the @xlcode(setq) special form or by +binding it using @xlcode(let) or @xlcode(let*). Here is an example: +@begin(example) +(setq fp (open "init.lsp" :direction :input)) +@end(example) + Evaluating this expression will result in the file @code(init.lsp) + being opened. The file object that will be returned by the @xlcode(open) + function will be assigned to the variable @xlcode(fp). + + It is now possible to use the file for input. To read an + expression from the file, just supply the value of the @xlcode(fp) + variable as the optional @i(stream) argument to @xlcode(read). +@begin(example) +(read fp) +@end(example) + Evaluating this expression will result in reading the first + expression from the file @code(init.lsp). The expression will be + returned as the result of the @xlcode(read) function. More expressions + can be read from the file using further calls to the @xlcode(read) + function. When there are no more expressions to read, the @xlcode(read) + function will return @xlcode(nil) (or whatever value was supplied as the + second argument to @xlcode(read)). + + Once you are done reading from the file, you should close it. + To close the file, use the following expression: +@begin(example) +(close fp) +@end(example) + Evaluating this expression will cause the file to be closed. + +@subsection(Output to a File)@index(Output to a File) + + Writing to a file is pretty much the same as reading from one. + You need to open the file first. This time you should use the + @xlcode(open) function to indicate that you will do output to the file. + For example: +@begin(example) +(setq fp (open "test.dat" :direction :output)) +@end(example) + Evaluating this expression will open the file @code(test.dat) for + output. If the file already exists, its current contents will + be discarded. If it doesn't already exist, it will be created. + In any case, a @xlcode(FILE-STREAM) object will be returned by the @xlcode(OPEN) + function. This file object will be assigned to the @xlcode(fp) + variable. + + It is now possible to write to this file by supplying the value + of the @xlcode(fp) variable as the optional @i(stream) parameter in the @xlcode(print) function. +@begin(example) +(print "Hello there" fp) +@end(example) + Evaluating this expression will result in the string ``Hello + there'' being written to the file @code(test.dat). More data can be + written to the file using the same technique. + + Once you are done writing to the file, you should close it. + Closing an output file is just like closing an input file. +@begin(example) +(close fp) +@end(example) + Evaluating this expression will close the output file and make + it permanent. + +@subsection(A Slightly More Complicated File Example) + + This example shows how to open a file, read each Lisp expression + from the file and print it. It demonstrates the use of files + and the use of the optional @i(stream) argument to the @xlcode(read) + function. +@begin(programexample) +(do* ((fp (open "test.dat" :direction :input)) + (ex (read fp) (read fp))) + ((null ex) nil) + (print ex)) +@end(programexample) + diff --git a/docsrc/xlisp/xlisp.mss b/docsrc/xlisp/xlisp.mss new file mode 100644 index 0000000..cc00251 --- /dev/null +++ b/docsrc/xlisp/xlisp.mss @@ -0,0 +1,4016 @@ +@define(codef, FaceCode T, size 11) +@comment{In my original scribe conversion of the ascii xlisp documentation, I used + times roman fonts for xlisp function names and code text in general. To be + consistent with Nyquist documentation, I have changed the code font to xlcode + which is defined here. If this turns out to be a problem, redefine xlcode to + use the regular FaceCode. -RBD} +@define(xlcode, FaceCode T, size 11) +@textform(pragma=[]) +@section(Introduction) + XLISP is an experimental programming language combining some of + the features of Common Lisp with an object-oriented extension + capability. It was implemented to allow experimentation with + object-oriented programming on small computers. + + Implementations of XLISP run on virtually every operating system. + XLISP is completely written in the programming language + C and is easily extended with user written built-in functions + and classes. It is available in source form to non-commercial + users. + + Many Common Lisp functions are built into XLISP. In addition, + XLISP defines the objects Object and Class as primitives. + Object is the only class that has no superclass and hence is + the root of the class hierarchy tree. Class is the class of + which all classes are instances (it is the only object that is + an instance of itself). + + This document is a brief description of XLISP. It assumes some + knowledge of LISP and some understanding of the concepts of + object-oriented programming. + + I recommend the book @i(Lisp) by Winston and Horn and published by + Addison Wesley for learning Lisp. The first edition of this + book is based on MacLisp and the second edition is based on + Common Lisp. + + You will probably also need a copy of @i(Common Lisp: The + Language) by Guy L. Steele, Jr., published by Digital Press to + use as a reference for some of the Common Lisp functions that + are described only briefly in this document. + + @section(A Note From The Author) + + If you have any problems with XLISP, feel free to contact me [me being David Betz - RBD] for + help or advice. Please remember that since XLISP is available + in source form in a high level language, many users [e.g. that Dannenberg fellow - RBD] have been + making versions available on a variety of machines. If you call + to report a problem with a specific version, I may not be able + to help you if that version runs on a machine to which I don't + have access. Please have the version number of the version that + you are running readily accessible before calling me. + + If you find a bug in XLISP, first try to fix the bug yourself + using the source code provided. If you are successful in fixing + the bug, send the bug report along with the fix to me. If you + don't have access to a C compiler or are unable to fix a bug, + please send the bug report to me and I'll try to fix it. + + Any suggestions for improvements will be welcomed. Feel free to + extend the language in whatever way suits your needs. However, + PLEASE DO NOT RELEASE ENHANCED VERSIONS WITHOUT CHECKING WITH ME + FIRST!! I would like to be the clearing house for new features + added to XLISP. If you want to add features for your own + personal use, go ahead. But, if you want to distribute your + enhanced version, contact me first. Please remember that the + goal of XLISP is to provide a language to learn and experiment + with LISP and object-oriented programming on small computers. I + don't want it to get so big that it requires megabytes of memory + to run. + + + @section(XLISP Command Loop)@index(XLISP Command Loop)@index(Command Loop) + + When XLISP is started, it first tries to load the workspace + @code(xlisp.wks) from the current directory. If that file doesn't + exist, XLISP builds an initial workspace, empty except for the + built-in functions and symbols. + + Then XLISP attempts to load @code(init.lsp) from the current + directory. It then loads any files named as parameters on the + command line (after appending @code(.lsp) to their names). + + XLISP then issues the following prompt: +@begin(example) + > +@end(example) + This indicates that XLISP is waiting for an expression to be + typed. + + When a complete expression has been entered, XLISP attempts to + evaluate that expression. If the expression evaluates + successfully, XLISP prints the result and then returns to the + initial prompt waiting for another expression to be typed. + + @section(Special Characters)@index(control characters, XLISP) + + When XLISP is running from a console, some control characters invoke operations: +@begin(itemize) +Backspace and Delete characters erase the previous character on the input line (if any). + +Control-U erases the entire input line. + +Control-C executes the TOP-LEVEL function. + +Control-G executes the CLEAN-UP function. + +Control-P executes the CONTINUE function. + +Control-B stops execution and enters the break command loop. Execution can be continued by typing Control-P or (CONTINUE). + +Control-E turns on character echoing (Linux and Mac OS X only). + +Control-F turns off character echoing (Linux and Mac OS X only). + +Control-T evaluates the INFO function. +@end(itemize) + + @section(Break Command Loop)@index(break) + + When XLISP encounters an error while evaluating an expression, + it attempts to handle the error in the following way: + + If the symbol @xlcode(*breakenable*@index(*breakenable*)) is + true, the message corresponding to the error is printed. If + the error is correctable, the correction message is printed. + + If the symbol @xlcode(*tracenable*@index(*tracenable*)) is true, a trace back is printed. + The number of entries printed depends on the value of the symbol + @xlcode(*tracelimit*@index(*tracelimit*)). If this symbol is set to something other than a + number, the entire trace back stack is printed. + + XLISP then enters a read/eval/print loop to allow the user to + examine the state of the interpreter in the context of the + error. This loop differs from the normal top-level + read/eval/print loop in that if the user invokes the function + @xlcode(continue), XLISP will continue from a correctable error. If + the user invokes the function @xlcode(clean-up), XLISP will abort the + break loop and return to the top level or the next lower + numbered break loop. When in a break loop, XLISP prefixes the + break level to the normal prompt. + + If the symbol @xlcode(*breakenable*@index(*breakenable*)) is @xlcode(nil), XLISP looks for a + surrounding errset function. If one is found, XLISP examines + the value of the print flag. If this flag is true, the error + message is printed. In any case, XLISP causes the errset + function call to return @xlcode(nil). + + If there is no surrounding errset function, XLISP prints the + error message and returns to the top level. + + @section(Data Types)@index(XLISP Data Types)@index(Data Types) + + There are several different data types available to XLISP + programmers. + +@begin(itemize) +lists + +symbols + +strings + +integers + +characters + +floats + +objects + +arrays + +streams + +subrs (built-in functions) + +fsubrs (special forms) + +closures (user defined functions) +@end(itemize) + + + + +@section(The Evaluator)@index(evaluator)@index(XLISP evaluator) + + The process of evaluation in XLISP: +@begin(itemize) + Strings, integers, characters, floats, objects, arrays, streams, + subrs, fsubrs and closures evaluate to themselves. + + Symbols act as variables and are evaluated by retrieving the + value associated with their current binding. + + Lists are evaluated by examining the first element of the list + and then taking one of the following actions: +@begin(itemize) + If it is a symbol, the functional binding of the symbol is + retrieved. + + If it is a lambda expression, a closure is constructed for + the function described by the lambda expression. + + If it is a subr, fsubr or closure, it stands for itself. + + Any other value is an error. +@end(itemize) + Then, the value produced by the previous step is examined: +@begin(itemize) + If it is a subr or closure, the remaining list elements are + evaluated and the subr or closure is called with these + evaluated expressions as arguments. + + If it is an fsubr, the fsubr is called using the remaining + list elements as arguments (unevaluated). + + If it is a macro, the macro is expanded using the remaining + list elements as arguments (unevaluated). The macro + expansion is then evaluated in place of the original macro + call. +@end(itemize) +@end(itemize) + +@section(Lexical Conventions)@index(Lexical conventions)@index(XLISP Lexical Conventions) + + The following conventions must be followed when entering XLISP + programs: + + Comments in XLISP code begin with a semi-colon character and + continue to the end of the line. + + Symbol names in XLISP can consist of any sequence of non-blank + printable characters except the following: +@begin(example) + ( ) ' ` , " ; +@end(example) + Uppercase and lowercase characters are not distinguished within + symbol names. All lowercase characters are mapped to uppercase + on input. + + Integer literals consist of a sequence of digits optionally + beginning with a @code(+) or @code(-). The range of values an integer can + represent is limited by the size of a C @code(long) on the machine on + which XLISP is running. + + Floating point literals consist of a sequence of digits + optionally beginning with a @code(+) or @code(-) and including an embedded + decimal point. The range of values a floating point number can + represent is limited by the size of a C @code(float) (@code(double) on + machines with 32 bit addresses) on the machine on which XLISP is + running. + + Literal strings are sequences of characters surrounded by double + quotes. Within quoted strings the ``@code(\)'' character is used to + allow non-printable characters to be included. The codes + recognized are: +@begin(itemize) +@code(\\) means the character ``@code(\)'' + +@code(\n) means newline + +@code(\t) means tab + +@code(\r) means return + +@code(\f) means form feed + +@code(\nnn) means the character whose octal code is nnn +@end(itemize) + +@section(Readtables)@index(Readtables) + + The behavior of the reader is controlled by a data structure + called a @i(readtable). The reader uses the symbol @xlcode(*readtable*@index(*readtable*)) to + locate the current readtable. This table controls the + interpretation of input characters. It is an array with 128 + entries, one for each of the ASCII character codes. Each entry + contains one of the following things: +@begin(itemize) + @xlcode(NIL) @itemsep Indicating an invalid character + + @xlcode(:CONSTITUENT) @itemsep Indicating a symbol constituent + + @xlcode(:WHITE-SPACE) @itemsep Indicating a whitespace character + + @xlcode[(:TMACRO . @i(fun))] @itemsep Terminating readmacro + + @xlcode[(:NMACRO . @i(fun))] @itemsep Non-terminating readmacro + + @xlcode(:SESCAPE) @itemsep Single escape character ('\') + + @xlcode(:MESCAPE) @itemsep Multiple escape character ('|') +@end(itemize) + + In the case of @xlcode(:TMACRO) and @xlcode(:NMACRO), the @i(fun) component is a + function. This can either be a built-in readmacro function or a + lambda expression. The function should take two parameters. + The first is the input stream and the second is the character + that caused the invocation of the readmacro. The readmacro + function should return @xlcode(NIL) to indicate that the character should + be treated as white space or a value consed with @xlcode(NIL) to indicate + that the readmacro should be treated as an occurence of the + specified value. Of course, the readmacro code is free to read + additional characters from the input stream. + + XLISP defines several useful read macros@index(read macros): +@begin(itemize) + @xlcode(')@i[<expr>] == @xlcode{(quote} @i[<expr>]@xlcode{)} + + @xlcode(#')@i[<expr>] == @xlcode{(function} @i[<expr>]@xlcode{)} + + @xlcode{#(}@i[<expr>]...@xlcode{)} == an array of the specified expressions + + @xlcode(#x)@i[<hdigits>] == a hexadecimal number (0-9,A-F) + + @xlcode(#o)@i[<odigits>] == an octal number (0-7) + + @xlcode(#b)@i[<bdigits>] == a binary number (0-1) + + @xlcode(#\)@i[<char>] == the ASCII code of the character + + @xlcode(#|) ... @xlcode(|#) == a comment + + @xlcode(#:)@i[<symbol>] == an uninterned symbol + + @xlcode(`)@i[<expr>] == @xlcode{(backquote} @i[<expr>]@xlcode{)} + + @xlcode(,)@i[<expr>] == @xlcode{(comma} @i[<expr>]@xlcode{)} + + @xlcode(,@@)@i[<expr>] == @xlcode{(comma-at} @i[<expr>]@xlcode{)} + +@end(itemize) +@section(Lambda Lists)@index(Lambda Lists) + + There are several forms in XLISP that require that a ``lambda + list'' be specified. A lambda list is a definition of the + arguments accepted by a function. There are four different + types of arguments. + + The lambda list starts with required arguments. Required + arguments must be specified in every call to the function. + + The required arguments are followed by the @xlcode(&optional) arguments. + Optional arguments may be provided or omitted in a call. An + initialization expression may be specified to provide a default + value for an @xlcode(&optional) argument if it is omitted from a call. + If no initialization expression is specified, an omitted + argument is initialized to @xlcode(NIL). It is also possible to provide + the name of a @xlcode(supplied-p) variable that can be used to + determine if a call provided a value for the argument or if the + initialization expression was used. If specified, the supplied- + p variable will be bound to T if a value was specified in the + call and @xlcode(NIL) if the default value was used. + + The @xlcode(&optional) arguments are followed by the @xlcode(&rest) argument. The + @xlcode(&rest) argument gets bound to the remainder of the argument list + after the required and @xlcode(&optional) arguments have been removed. + + The @xlcode(&rest) argument is followed by the @xlcode(&key) arguments. When a + keyword argument is passed to a function, a pair of values + appears in the argument list. The first expression in the pair + should evaluate to a keyword symbol (a symbol that begins with a + ``@code(:)''). The value of the second expression is the value of the + keyword argument. Like @xlcode(&optional) arguments, @xlcode(&key) arguments can + have initialization expressions and supplied-p variables. In + addition, it is possible to specify the keyword to be used in a + function call. If no keyword is specified, the keyword obtained + by adding a ``@code(:)'' to the beginning of the keyword argument symbol + is used. In other words, if the keyword argument symbol is + @xlcode(foo), the keyword will be @xlcode(:foo). + + The @xlcode(&key) arguments are followed by the @xlcode(&aux) variables. These + are local variables that are bound during the evaluation of the + function body. It is possible to have initialization + expressions for the @xlcode(&aux) variables. + + Here is the complete syntax for lambda lists: +@begin(display) + (@i<rarg>... + [@xlcode(&optional) [@i<oarg> | (@i<oarg> [@i<init> [@i<svar>]])]...] + [@xlcode(&rest) @i<rarg>] + [@xlcode(&key) + [@i<karg> | ([@i<karg> | (@i<key> @i<karg>)] [@i<init> [@i<svar>]])]... + @xlcode(&allow)-other-keys] + [@xlcode(&aux) + [@i<aux> | (@i<aux> [@i<init>])]...]) + + where: + + @i<rarg> is a required argument symbol + @i<oarg> is an @xlcode(&optional) argument symbol + @i<rarg> is the @xlcode(&rest) argument symbol + @i<karg> is a @xlcode(&key) argument symbol + @i<key> is a keyword symbol + @i<aux> is an auxiliary variable symbol + @i<init> is an initialization expression + @i<svar> is a supplied-p variable symbol +@end(display) + + +@section(Objects)@index(Objects)@label(objects-sec) + + Definitions: +@begin(itemize) +selector @itemsep a symbol used to select an appropriate method + +message @itemsep a selector and a list of actual arguments + +method @itemsep the code that implements a message +@end(itemize) + Since XLISP was created to provide a simple basis for + experimenting with object-oriented programming, one of the + primitive data types included is @i(object). In XLISP, an object + consists of a data structure containing a pointer to the + object's class as well as an array containing the values of the + object's instance variables. + + Officially, there is no way to see inside an object (look at the + values of its instance variables). The only way to communicate + with an object is by sending it a message. + + You can send a message to an object using the @xlcode(send) function. + This function takes the object as its first argument, the + message selector as its second argument (which must be a symbol) + and the message arguments as its remaining arguments. + + The @xlcode(send) function determines the class of the receiving object + and attempts to find a method corresponding to the message + selector in the set of messages defined for that class. If the + message is not found in the object's class and the class has a + super-class, the search continues by looking at the messages + defined for the super-class. This process continues from one + super-class to the next until a method for the message is found. + If no method is found, an error occurs. + +@begin(comment) +THIS IS WRONG -- I DON'T KNOW IF IT WAS CORRECT IN THE ORIGINAL XLISP. -RBD + A message can also be sent from the body of a method by using + the current object, but the method lookup starts with the + object's superclass rather than its class. This allows a + subclass to invoke a standard method in its parent class even + though it overrides that method with its own specialized + version. +@end(comment) + + When a method is found, the evaluator binds the receiving object + to the symbol @xlcode(self) and evaluates the method using the + remaining elements of the original list as arguments to the + method. These arguments are always evaluated prior to being + bound to their corresponding formal arguments. The result of + evaluating the method becomes the result of the expression. + + Within the body of a method, a message can be sent to the current + object by calling the @xlcode[(send self ...)]. The method lookup + starts with the object's class regardless of the class containing + the current method. + + Sometimes it is desirable to invoke a general method in a superclass + even when it is overridden by a more specific method in a subclass. + This can be accomplished by calling @xlcode(send-super), which begins + the method lookup in the superclass of the class defining the current + method rather than in the class of the current object. + + The @xlcode(send-super) function takes a selector as its first argument + (which must be a symbol) and the message arguments as its remaining + arguments. Notice that @xlcode(send-super) can only be sent from within + a method, and the target of the message is always the current object + (@xlcode(self)). @xlcode[(send-super ...)] is similar to + @xlcode[(send self ...)] except that method lookup begins in the + superclass of the class containing the current method + rather than the class of the current object. + +@section(The ``Object'' Class)@index(Object Class) + +@xlcode(Object)@index(Object) @itemsep the top of the class hierarchy. + +Messages: +@begin(fdescription) +@xlcode(:show@index(:show)) @itemsep show an object's instance variables. +@begin(pdescription) +returns @itemsep the object +@end(pdescription) +@blankspace(1) + +@xlcode{:class@index(:class)} @itemsep return the class of an object +@begin(pdescription) +returns @itemsep the class of the object +@end(pdescription) +@blankspace(1) + +@xlcode{:isa@index(:isa)} @i(class) @itemsep test if object inherits from class +@begin(pdescription) +returns @itemsep @xlcode(t) if object is an instance of @i(class) or a subclass of @i(class), otherwise @xlcode(nil) +@end(pdescription) +@blankspace(1) + +@xlcode(:isnew@index(:isnew)) @itemsep the default object initialization routine +@begin(pdescription) +returns @itemsep the object +@end(pdescription) +@end(fdescription) + +@section(The ``Class'' Class)@index(Class class) + +@xlcode(Class@index(Class)) @itemsep class of all object classes (including itself) + + Messages: + +@begin(fdescription) + @xlcode(:new@index(:new)) @itemsep create a new instance of a class +@begin(pdescription) + returns @itemsep the new class object +@end(pdescription) +@blankspace(1) + + @xlcode(:isnew@index(:isnew)) @i<ivars> [@i<cvars> [@i<super>]] @itemsep initialize a new class +@begin(pdescription) + @i<ivars> @itemsep the list of instance variable symbols + + @i<cvars> @itemsep the list of class variable symbols + + @i<super> @itemsep the superclass (default is object) + + returns @itemsep the new class object +@end(pdescription) +@blankspace(1) + + @xlcode(:answer@index(:answer)) @i<msg> @i<fargs> @i<code> @itemsep add a message to a class +@begin(pdescription) + @i<msg> @itemsep the message symbol + + @i<fargs> @itemsep the formal argument list (lambda list) + + @i<code> @itemsep a list of executable expressions + + returns @itemsep the object +@end(pdescription) +@blankspace(1) +@end(fdescription) + + When a new instance of a class is created by sending the message + @xlcode(:new) to an existing class, the message @xlcode(:isnew) followed by + whatever parameters were passed to the @xlcode(:new) message is sent to + the newly created object. + + When a new class is created by sending the @xlcode(:new) message to the + object @xlcode(Class), an optional parameter may be specified + indicating the superclass of the new class. If this parameter + is omitted, the new class will be a subclass of @xlcode(Object). A + class inherits all instance variables, class variables, and + methods from its super-class. + +@section(Profiling)@index(profiling) +The Xlisp 2.0 release has been extended with a profiling facility, which counts how many times and where @xlcode(eval) is executed. A separate count is maintained for each named function, closure, or macro, and a count indicates an @xlcode(eval) in the immediately (lexically) enclosing named function, closure, or macro. Thus, the count gives an indication of the amount of time spent in a function, not counting nested function calls. The list of all functions executed is maintained on the global @xlcode(*profile*) variable. These functions in turn have @xlcode(*profile*) properties, which maintain the counts. The profile system merely increments counters and puts symbols on the @xlcode(*profile*) list. It is up to the user to initialize data and gather results. Profiling is turned on or off with the @xlcode(profile) function. Unfortunately, methods cannot be profiled with this facility. + +@label(symbols-sec) +@section(Symbols)@index(symbols) +@begin(itemize) +@codef(self)@pragma(defn)@index(self) @dash the current object (within a method context) + +@codef(*obarray*@pragma(defn)@index(*obarray*)) @dash the object hash table + +@codef(*standard-input*@pragma(defn)@index(*standard-input*)) @dash the standard input stream + +@codef(*standard-output*@pragma(defn)@index(*standard-output*)) @dash the standard output stream + +@codef(*error-output*@pragma(defn)@index(*error-output*)) @dash the error output stream + +@codef(*trace-output*@pragma(defn)@index(*trace-output*)) @dash the trace output stream + +@codef(*debug-io*@pragma(defn)@index(*debug-io*)) @dash the debug i/o stream + +@codef(*breakenable*@pragma(defn)@index(*breakenable*)) @dash flag controlling entering break loop on errors + +@codef(*tracelist*@pragma(defn)@index(*tracelist*)) @dash list of names of functions to trace + +@codef(*tracenable*@pragma(defn)@index(*tracenable*)) @dash enable trace back printout on errors + +@codef(*tracelimit*@pragma(defn)@index(*tracelimit*)) @dash number of levels of trace back information + +@codef(*evalhook*@pragma(defn)@index(*evalhook*)) @dash user substitute for the evaluator function + +@codef(*applyhook*@pragma(defn)@index(*applyhook*)) @dash (not yet implemented) + +@codef(*readtable*@pragma(defn)@index(*readtable*)) @dash the current readtable + +@codef(*unbound*@pragma(defn)@index(*unbound*)) @dash indicator for unbound symbols + +@codef(*gc-flag*@pragma(defn)@index(*gc-flag*)) @dash controls the printing of gc messages + +@codef(*gc-hook*@pragma(defn)@index(*gc-hook*)) @dash function to call after garbage collection + +@codef(*integer-format*@pragma(defn)@index(*integer-format*)) @dash format for printing integers (``%d'' or ``%ld'') + +@codef(*float-format*@pragma(defn)@index(*float-format*)) @dash format for printing floats (``%g'') + +@codef(*print-case*@pragma(defn)@index(*print-case*)) @dash symbol output case (:upcase or :downcase) +@end(itemize) + + There are several symbols maintained by the read/eval/print + loop. The symbols @code(+), @code(++), and @code(+++) are bound to the most + recent three input expressions. The symbols @code(*), @code(**) and @code(***) + are bound to the most recent three results. The symbol @code(-) is + bound to the expression currently being evaluated. It becomes + the value of @code(+) at the end of the evaluation. +@section(Evaluation Functions)@index(evaluation functions) +@begin(fdescription) + @begin(fgroup)@xlcode{eval(@i(expr))} @c{[sal]} + + @xlcode{(eval@pragma(defn)@index(eval) @t(@i(expr)))} @c{[lisp]} @itemsep evaluate an xlisp expression +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to be evaluated + + returns @itemsep the result of evaluating the expression +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{apply(@i(fun), @i(args))} @c{[sal]} + + @xlcode{(apply@pragma(defn)@index(apply) @t(@i(fun)) @t(@i(args)))} @c{[lisp]} @itemsep apply a function to a list of arguments +@end(fgroup) +@begin(pdescription) + @i<fun> @itemsep the function to apply (or function symbol) + + @i<args> @itemsep the argument list + + returns @itemsep the result of applying the function to the arguments +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{funcall(@i(fun), @i(arg)@r(...))} @c{[sal]} + + @xlcode{(funcall@pragma(defn)@index(funcall) @t(@i(fun)) @t(@i(arg))@r(...))} @c{[lisp]} @itemsep call a function with arguments +@end(fgroup) +@begin(pdescription) + @i<fun> @itemsep the function to call (or function symbol) + + @i<arg> @itemsep arguments to pass to the function + + returns @itemsep the result of calling the function with the arguments +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{quote(@i(expr))} @c{[sal]} + + @xlcode{(quote@pragma(defn)@index(quote) @t(@i(expr)))} @c{[lisp]} @itemsep return an expression unevaluated +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to be quoted (quoted) + + returns @itemsep @i<expr> unevaluated +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{function(@i(expr))} @c{[sal]} + + @xlcode{(function@pragma(defn)@index(function) @t(@i(expr)))} @c{[lisp]} @itemsep get the functional interpretation +@end(fgroup) + +@begin(pdescription) + @i<expr> @itemsep the symbol or lambda expression (quoted) + + returns @itemsep the functional interpretation + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{backquote(@i(expr))} @c{[sal]} + + @xlcode{(backquote@pragma(defn)@index(backquote) @t(@i(expr)))} @c{[lisp]} @itemsep fill in a template +@end(fgroup) + +@begin(pdescription) + @i<expr> @itemsep the template + + returns @itemsep a copy of the template with comma and comma-at + + expressions expanded +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{lambda(@i(args), @i(expr)@r(...))} @c{[sal]} + + @xlcode{(lambda@pragma(defn)@index(lambda) @t(@i(args)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep make a function closure +@end(fgroup) + +@begin(pdescription) + @i<args> @itemsep formal argument list (lambda list) (quoted) + + @i<expr> @itemsep expressions of the function body + + returns @itemsep the function closure + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{get-lambda-expression(@i(closure))} @c{[sal]} + + @xlcode{(get-lambda-expression@pragma(defn)@index(get-lambda-expression) @t(@i(closure)))} @c{[lisp]} @itemsep get the lambda expression +@end(fgroup) + +@begin(pdescription) + @i<closure> @itemsep the closure + + returns @itemsep the original lambda expression + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{macroexpand(@i(form))} @c{[sal]} + + @xlcode{(macroexpand@pragma(defn)@index(macroexpand) @t(@i(form)))} @c{[lisp]} @itemsep recursively expand macro calls +@end(fgroup) + +@begin(pdescription) + @i<form> @itemsep the form to expand + + returns @itemsep the macro expansion + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{macroexpand-1(@i(form))} @c{[sal]} + + @xlcode{(macroexpand-1@pragma(defn)@index(macroexpand-1) @t(@i(form)))} @c{[lisp]} @itemsep expand a macro call +@end(fgroup) + +@begin(pdescription) + @i<form> @itemsep the macro call form + + returns @itemsep the macro expansion + +@end(pdescription) +@blankspace(1) +@end(fdescription) + + +@section(Symbol Functions)@index(Symbol Functions) +@begin(fdescription) + @begin(fgroup)@xlcode{set(@i(sym), @i(expr))} @c{[sal]} + + @xlcode{(set@pragma(defn)@index(set) @t(@i(sym)) @t(@i(expr)))} @c{[lisp]} @itemsep set the value of a symbol +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the symbol being set + + @i<expr> @itemsep the new value + + returns @itemsep the new value + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{setq([@i(sym), @i(expr)]@r(...))} @c{[sal]} + + @xlcode{(setq@pragma(defn)@index(setq) [@t(@i(sym)) @t(@i(expr))]@r(...))} @c{[lisp]} @itemsep set the value of a symbol +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the symbol being set (quoted) + + @i<expr> @itemsep the new value + + returns @itemsep the new value + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{psetq([@i(sym), @i(expr)]@r(...))} @c{[sal]} + + @xlcode{(psetq@pragma(defn)@index(psetq) [@t(@i(sym)) @t(@i(expr))]@r(...))} @c{[lisp]} @itemsep parallel version of setq +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the symbol being set (quoted) + + @i<expr> @itemsep the new value + + returns @itemsep the new value + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{setf([@i(place), @i(expr)]@r(...))} @c{[sal]} + + @xlcode{(setf@pragma(defn)@index(setf) [@t(@i(place)) @t(@i(expr))]@r(...))} @c{[lisp]} @itemsep set the value of a field +@end(fgroup) +@begin(pdescription) + @i<place> @itemsep the field specifier (quoted): + +@begin(pdescription) + @i<sym> @itemsep set value of a symbol + + (car @i<expr>) @itemsep set car of a cons node + + (cdr @i<expr>) @itemsep set cdr of a cons node + + (nth @i<n> @i<expr>) @itemsep set nth car of a list + + (aref @i<expr> @i<n>) @itemsep set nth element of an array + + (get @i<sym> @i<prop>) @itemsep set value of a property + + (symbol-value @i<sym>) @itemsep set value of a symbol + + (symbol-function @i<sym>) @itemsep set functional value of a symbol + + (symbol-plist @i<sym>) @itemsep set property list of a symbol + +@end(pdescription)@pragma(stopcodef) + @i<expr> @itemsep the new value + + returns @itemsep the new value + +@end(pdescription) +@blankspace(1) +@begin(fgroup) + @xlcode{(defun@pragma(defn)@index(defun) @t(@i(sym)) @t(@i(fargs)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep define a function + +@pragma(startcodef) + @xlcode{(defmacro@pragma(defn)@index(defmacro) @t(@i(sym)) @t(@i(fargs)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep define a macro +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep symbol being defined (quoted) + + @i<fargs> @itemsep formal argument list (lambda list) (quoted) + + @i<expr> @itemsep expressions constituting the body of the + + function (quoted) + returns @itemsep the function symbol + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{gensym([@i(tag)])} @c{[sal]} + + @xlcode{(gensym@pragma(defn)@index(gensym) [@t(@i(tag))])} @c{[lisp]} @itemsep generate a symbol +@end(fgroup) +@begin(pdescription) + @i<tag> @itemsep string or number + + returns @itemsep the new symbol + +@end(pdescription) +@blankspace(1) + +@begin(fgroup)@xlcode{intern(@i(pname))} @c{[sal]} + + @xlcode{(intern@pragma(defn)@index(intern) @t(@i(pname)))} @c{[lisp]} @itemsep make an interned symbol +@end(fgroup) +@begin(pdescription) + @i<pname> @itemsep the symbol's print name string + + returns @itemsep the new symbol + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{make-symbol(@i(pname))} @c{[sal]} + + @xlcode{(make-symbol@pragma(defn)@index(make-symbol) @t(@i(pname)))} @c{[lisp]} @itemsep make an uninterned symbol +@end(fgroup) +@begin(pdescription) + @i<pname> @itemsep the symbol's print name string + + returns @itemsep the new symbol + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{symbol-name(@i(sym))} @c{[sal]} + + @xlcode{(symbol-name@pragma(defn)@index(symbol-name) @t(@i(sym)))} @c{[lisp]} @itemsep get the print name of a symbol +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the symbol + + returns @itemsep the symbol's print name + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{symbol-value(@i(sym))} @c{[sal]} + + @xlcode{(symbol-value@pragma(defn)@index(symbol-value) @t(@i(sym)))} @c{[lisp]} @itemsep get the value of a symbol +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the symbol + + returns @itemsep the symbol's value + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{symbol-function(@i(sym))} @c{[sal]} + + @xlcode{(symbol-function@pragma(defn)@index(symbol-function) @t(@i(sym)))} @c{[lisp]} @itemsep get the functional value of a symbol +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the symbol + + returns @itemsep the symbol's functional value + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{symbol-plist(@i(sym))} @c{[sal]} + + @xlcode{(symbol-plist@pragma(defn)@index(symbol-plist) @t(@i(sym)))} @c{[lisp]} @itemsep get the property list of a symbol +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the symbol + + returns @itemsep the symbol's property list + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{hash(@i(sym), @i(n))} @c{[sal]} + + @xlcode{(hash@pragma(defn)@index(hash) @t(@i(sym)) @t(@i(n)))} @c{[lisp]} @itemsep compute the hash index for a symbol +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the symbol or string + + @i<n> @itemsep the table size (integer) + + returns @itemsep the hash index (integer) + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Property List Functions)@index(Property List Functions) +@begin(fdescription) + @begin(fgroup)@xlcode{get(@i(sym), @i(prop))} @c{[sal]} + + @xlcode{(get@pragma(defn)@index(get) @t(@i(sym)) @t(@i(prop)))} @c{[lisp]} @itemsep get the value of a property +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the symbol + + @i<prop> @itemsep the property symbol + + returns @itemsep the property value or @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{putprop(@i(sym), @i(val), @i(prop))} @c{[sal]} + + @xlcode{(putprop@pragma(defn)@index(putprop) @t(@i(sym)) @t(@i(val)) @t(@i(prop)))} @c{[lisp]} @itemsep put a property onto a property list +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the symbol + + @i<val> @itemsep the property value + + @i<prop> @itemsep the property symbol + + returns @itemsep the property value + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{remprop(@i(sym), @i(prop))} @c{[sal]} + + @xlcode{(remprop@pragma(defn)@index(remprop) @t(@i(sym)) @t(@i(prop)))} @c{[lisp]} @itemsep remove a property +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the symbol + + @i<prop> @itemsep the property symbol + + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Array Functions)@index(Array Functions) +@begin(fdescription) + @begin(fgroup)@xlcode{aref(@i(array), @i(n))} @c{[sal]} + + @xlcode{(aref@pragma(defn)@index(aref) @t(@i(array)) @t(@i(n)))} @c{[lisp]} @itemsep get the nth element of an array +@end(fgroup) +@begin(pdescription) + @i<array> @itemsep the array + + @i<n> @itemsep the array index (integer) + + returns @itemsep the value of the array element + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{make-array(@i(size))} @c{[sal]} + + @xlcode{(make-array@pragma(defn)@index(make-array) @t(@i(size)))} @c{[lisp]} @itemsep make a new array +@end(fgroup) +@begin(pdescription) + @i<size> @itemsep the size of the new array (integer) + + returns @itemsep the new array + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{vector(@i(expr)@r(...))} @c{[sal]} + + @xlcode{(vector@pragma(defn)@index(vector) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep make an initialized vector +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the vector elements + + returns @itemsep the new vector + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(List Functions)@index(List Functions) +@begin(fdescription) + @begin(fgroup)@xlcode{car(@i(expr))} @c{[sal]} + + @xlcode{(car@pragma(defn)@index(car) @t(@i(expr)))} @c{[lisp]} @itemsep return the car of a list node +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the list node + + returns @itemsep the car of the list node + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{cdr(@i(expr))} @c{[sal]} + + @xlcode{(cdr@pragma(defn)@index(cdr) @t(@i(expr)))} @c{[lisp]} @itemsep return the cdr of a list node +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the list node + + returns @itemsep the cdr of the list node + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{c@i(xx)r(@i(expr))} @c{[sal]} + + @xlcode{(c@i(xx)r@index(cxxr) @t(@i(expr)))} @c{[lisp]} @itemsep all c@i(xx)r combinations +@end(fgroup) +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{c@i(xxx)r(@i(expr))} @c{[sal]} + + @xlcode{(c@i(xxx)r@index(cxxxr) @t(@i(expr)))} @c{[lisp]} @itemsep all c@i(xxx)r combinations +@end(fgroup) +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{c@i(xxxx)r(@i(expr))} @c{[sal]} + + @xlcode{(c@i(xxxx)r@index(cxxxxr) @t(@i(expr)))} @c{[lisp]} @itemsep all c@i(xxxx)r combinations +@end(fgroup) +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{first(@i(expr))} @c{[sal]} + + @xlcode{(first@pragma(defn)@index(first) @t(@i(expr)))} @c{[lisp]} @itemsep a synonym for car +@end(fgroup) +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{second(@i(expr))} @c{[sal]} + + @xlcode{(second@pragma(defn)@index(second) @t(@i(expr)))} @c{[lisp]} @itemsep a synonym for cadr +@end(fgroup) +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{third(@i(expr))} @c{[sal]} + + @xlcode{(third@pragma(defn)@index(third) @t(@i(expr)))} @c{[lisp]} @itemsep a synonym for caddr +@end(fgroup) +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{fourth(@i(expr))} @c{[sal]} + + @xlcode{(fourth@pragma(defn)@index(fourth) @t(@i(expr)))} @c{[lisp]} @itemsep a synonym for cadddr +@end(fgroup) +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{rest(@i(expr))} @c{[sal]} + + @xlcode{(rest@pragma(defn)@index(rest) @t(@i(expr)))} @c{[lisp]} @itemsep a synonym for cdr +@end(fgroup) +@begin(pdescription) +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{cons(@i(expr1), @i(expr2))} @c{[sal]} + + @xlcode{(cons@pragma(defn)@index(cons) @t(@i(expr1)) @t(@i(expr2)))} @c{[lisp]} @itemsep construct a new list node +@end(fgroup) +@begin(pdescription) + @i<expr1> @itemsep the car of the new list node + + @i<expr2> @itemsep the cdr of the new list node + + returns @itemsep the new list node + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{list(@i(expr)@r(...))} @c{[sal]} + + @xlcode{(list@pragma(defn)@index(list) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep create a list of values +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep expressions to be combined into a list + + returns @itemsep the new list + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{append(@i(expr)@r(...))} @c{[sal]} + + @xlcode{(append@pragma(defn)@index(append) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep append lists +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep lists whose elements are to be appended + + returns @itemsep the new list + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{reverse(@i(expr))} @c{[sal]} + + @xlcode{(reverse@pragma(defn)@index(reverse) @t(@i(expr)))} @c{[lisp]} @itemsep reverse a list +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the list to reverse + + returns @itemsep a new list in the reverse order + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{last(@i(list))} @c{[sal]} + + @xlcode{(last@pragma(defn)@index(last) @t(@i(list)))} @c{[lisp]} @itemsep return the last list node of a list +@end(fgroup) +@begin(pdescription) + @i<list> @itemsep the list + + returns @itemsep the last list node in the list + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{member(@i(expr), @i(list), test: @i(test), test-not: @i(test-not))} @c{[sal]} + + @xlcode{(member@pragma(defn)@index(member) @t(@i(expr)) @t(@i(list)) @t(&key )@t(:test) @t(:test-not))} @c{[lisp]} @itemsep find an expression in a list +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to find + + @i<list> @itemsep the list to search + + :test @itemsep the test function (defaults to eql) + + :test-not @itemsep the test function (sense inverted) + + returns @itemsep the remainder of the list starting with the expression + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{assoc(@i(expr), @i(alist), test: @i(test), test-not: @i(test-not))} @c{[sal]} + + @xlcode{(assoc@pragma(defn)@index(assoc) @t(@i(expr)) @t(@i(alist)) @t(&key )@t(:test) @t(:test-not))} @c{[lisp]} @itemsep find an expression in an a-list +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to find + + @i<alist> @itemsep the association list + + :test @itemsep the test function (defaults to eql) + + :test-not @itemsep the test function (sense inverted) + + returns @itemsep the alist entry or @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{remove(@i(expr), @i(list), test: @i(test), test-not: @i(test-not))} @c{[sal]} + + @xlcode{(remove@pragma(defn)@index(remove) @t(@i(expr)) @t(@i(list)) @t(&key )@t(:test) @t(:test-not))} @c{[lisp]} @itemsep remove elements from a list +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the element to remove + + @i<list> @itemsep the list + + :test @itemsep the test function (defaults to eql) + + :test-not @itemsep the test function (sense inverted) + + returns @itemsep copy of list with matching expressions removed + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{remove-if(@i(test), @i(list))} @c{[sal]} + + @xlcode{(remove-if@pragma(defn)@index(remove-if) @t(@i(test)) @t(@i(list)))} @c{[lisp]} @itemsep remove elements that pass test +@end(fgroup) +@begin(pdescription) + @i<test> @itemsep the test predicate + + @i<list> @itemsep the list + + returns @itemsep copy of list with matching elements removed + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{remove-if-not(@i(test), @i(list))} @c{[sal]} + + @xlcode{(remove-if-not@pragma(defn)@index(remove-if-not) @t(@i(test)) @t(@i(list)))} @c{[lisp]} @itemsep remove elements that fail test +@end(fgroup) +@begin(pdescription) + @i<test> @itemsep the test predicate + + @i<list> @itemsep the list + + returns @itemsep copy of list with non-matching elements removed + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{length(@i(expr))} @c{[sal]} + + @xlcode{(length@pragma(defn)@index(length) @t(@i(expr)))} @c{[lisp]} @itemsep find the length of a list, vector or string +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the list, vector or string + + returns @itemsep the length of the list, vector or string + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{nth(@i(n), @i(list))} @c{[sal]} + + @xlcode{(nth@pragma(defn)@index(nth) @t(@i(n)) @t(@i(list)))} @c{[lisp]} @itemsep return the nth element of a list +@end(fgroup) +@begin(pdescription) + @i<n> @itemsep the number of the element to return (zero origin) + + @i<list> @itemsep the list + + returns @itemsep the nth element or @xlcode(nil) if the list isn't that long + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{nthcdr(@i(n), @i(list))} @c{[sal]} + + @xlcode{(nthcdr@pragma(defn)@index(nthcdr) @t(@i(n)) @t(@i(list)))} @c{[lisp]} @itemsep return the nth cdr of a list +@end(fgroup) +@begin(pdescription) + @i<n> @itemsep the number of the element to return (zero origin) + + @i<list> @itemsep the list + + returns @itemsep the nth cdr or @xlcode(nil) if the list isn't that long + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{mapc(@i(fcn), @i(list1), @i(list)@r(...))} @c{[sal]} + + @xlcode{(mapc@pragma(defn)@index(mapc) @t(@i(fcn)) @t(@i(list1)) @t(@i(list))@r(...))} @c{[lisp]} @itemsep apply function to successive cars +@end(fgroup) +@begin(pdescription) + @i<fcn> @itemsep the function or function name + + @i<listn> @itemsep a list for each argument of the function + + returns @itemsep the first list of arguments + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{mapcar(@i(fcn), @i(list1), @i(list)@r(...))} @c{[sal]} + + @xlcode{(mapcar@pragma(defn)@index(mapcar) @t(@i(fcn)) @t(@i(list1)) @t(@i(list))@r(...))} @c{[lisp]} @itemsep apply function to successive cars +@end(fgroup) +@begin(pdescription) + @i<fcn> @itemsep the function or function name + + @i<listn> @itemsep a list for each argument of the function + + returns @itemsep a list of the values returned + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{mapl(@i(fcn), @i(list1), @i(list)@r(...))} @c{[sal]} + + @xlcode{(mapl@pragma(defn)@index(mapl) @t(@i(fcn)) @t(@i(list1)) @t(@i(list))@r(...))} @c{[lisp]} @itemsep apply function to successive cdrs +@end(fgroup) +@begin(pdescription) + @i<fcn> @itemsep the function or function name + + @i<listn> @itemsep a list for each argument of the function + + returns @itemsep the first list of arguments + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{maplist(@i(fcn), @i(list1), @i(list)@r(...))} @c{[sal]} + + @xlcode{(maplist@pragma(defn)@index(maplist) @t(@i(fcn)) @t(@i(list1)) @t(@i(list))@r(...))} @c{[lisp]} @itemsep apply function to successive cdrs +@end(fgroup) +@begin(pdescription) + @i<fcn> @itemsep the function or function name + + @i<listn> @itemsep a list for each argument of the function + + returns @itemsep a list of the values returned + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{subst(@i(to), @i(from), @i(expr), test: @i(test), test-not: @i(test-not))} @c{[sal]} + + @xlcode{(subst@pragma(defn)@index(subst) @t(@i(to)) @t(@i(from)) @t(@i(expr)) @t(&key )@t(:test) @t(:test-not))} @c{[lisp]} @itemsep substitute expressions +@end(fgroup) +@begin(pdescription) + @i<to> @itemsep the new expression + + @i<from> @itemsep the old expression + + @i<expr> @itemsep the expression in which to do the substitutions + + :test @itemsep the test function (defaults to eql) + + :test-not @itemsep the test function (sense inverted) + + returns @itemsep the expression with substitutions + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{sublis(@i(alist), @i(expr), test: @i(test), test-not: @i(test-not))} @c{[sal]} + + @xlcode{(sublis@pragma(defn)@index(sublis) @t(@i(alist)) @t(@i(expr)) @t(&key )@t(:test) @t(:test-not))} @c{[lisp]} @itemsep substitute with an a-list +@end(fgroup) +@begin(pdescription) + @i<alist> @itemsep the association list + + @i<expr> @itemsep the expression in which to do the substitutions + + :test @itemsep the test function (defaults to eql) + + :test-not @itemsep the test function (sense inverted) + + returns @itemsep the expression with substitutions + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Destructive List Functions)@index(Destructive List Functions) +@begin(fdescription) + @begin(fgroup)@xlcode{rplaca(@i(list), @i(expr))} @c{[sal]} + + @xlcode{(rplaca@pragma(defn)@index(rplaca) @t(@i(list)) @t(@i(expr)))} @c{[lisp]} @itemsep replace the car of a list node +@end(fgroup) +@begin(pdescription) + @i<list> @itemsep the list node + + @i<expr> @itemsep the new value for the car of the list node + + returns @itemsep the list node after updating the car + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{rplacd(@i(list), @i(expr))} @c{[sal]} + + @xlcode{(rplacd@pragma(defn)@index(rplacd) @t(@i(list)) @t(@i(expr)))} @c{[lisp]} @itemsep replace the cdr of a list node +@end(fgroup) +@begin(pdescription) + @i<list> @itemsep the list node + + @i<expr> @itemsep the new value for the cdr of the list node + + returns @itemsep the list node after updating the cdr + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{nconc(@i(list)@r(...))} @c{[sal]} + + @xlcode{(nconc@pragma(defn)@index(nconc) @t(@i(list))@r(...))} @c{[lisp]} @itemsep destructively concatenate lists +@end(fgroup) +@begin(pdescription) + @i<list> @itemsep lists to concatenate + + returns @itemsep the result of concatenating the lists + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{delete(@i(expr), test: @i(test), test-not: @i(test-not))} @c{[sal]} + + @xlcode{(delete@pragma(defn)@index(delete) @t(@i(expr)) @t(&key )@t(:test) @t(:test-not))} @c{[lisp]} @itemsep delete elements from a list +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the element to delete + + @i<list> @itemsep the list + + :test @itemsep the test function (defaults to eql) + + :test-not @itemsep the test function (sense inverted) + + returns @itemsep the list with the matching expressions deleted + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{delete-if(@i(test), @i(list))} @c{[sal]} + + @xlcode{(delete-if@pragma(defn)@index(delete-if) @t(@i(test)) @t(@i(list)))} @c{[lisp]} @itemsep delete elements that pass test +@end(fgroup) +@begin(pdescription) + @i<test> @itemsep the test predicate + + @i<list> @itemsep the list + + returns @itemsep the list with matching elements deleted + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{delete-if-not(@i(test), @i(list))} @c{[sal]} + + @xlcode{(delete-if-not@pragma(defn)@index(delete-if-not) @t(@i(test)) @t(@i(list)))} @c{[lisp]} @itemsep delete elements that fail test +@end(fgroup) +@begin(pdescription) + @i<test> @itemsep the test predicate + + @i<list> @itemsep the list + + returns @itemsep the list with non-matching elements deleted + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{sort(@i(list), @i(test))} @c{[sal]} + + @xlcode{(sort@pragma(defn)@index(sort) @t(@i(list)) @t(@i(test)))} @c{[lisp]} @itemsep sort a list +@end(fgroup) +@begin(pdescription) + @i<list> @itemsep the list to sort + + @i<test> @itemsep the comparison function + + returns @itemsep the sorted list + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Predicate Functions)@index(Predicate Functions) +@begin(fdescription) + @begin(fgroup)@xlcode{atom(@i(expr))} @c{[sal]} + + @xlcode{(atom@pragma(defn)@index(atom) @t(@i(expr)))} @c{[lisp]} @itemsep is this an atom? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is an atom, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{symbolp(@i(expr))} @c{[sal]} + + @xlcode{(symbolp@pragma(defn)@index(symbolp) @t(@i(expr)))} @c{[lisp]} @itemsep is this a symbol? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the expression is a symbol, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{numberp(@i(expr))} @c{[sal]} + + @xlcode{(numberp@pragma(defn)@index(numberp) @t(@i(expr)))} @c{[lisp]} @itemsep is this a number? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the expression is a number, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{null(@i(expr))} @c{[sal]} + + @xlcode{(null@pragma(defn)@index(null) @t(@i(expr)))} @c{[lisp]} @itemsep is this an empty list? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the list to check + + returns @itemsep @xlcode(t) if the list is empty, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{not(@i(expr))} @c{[sal]} + + @xlcode{(not@pragma(defn)@index(not) @t(@i(expr)))} @c{[lisp]} @itemsep is this false? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to check + + return @itemsep @xlcode(t) if the value is @xlcode(nil), @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{listp(@i(expr))} @c{[sal]} + + @xlcode{(listp@pragma(defn)@index(listp) @t(@i(expr)))} @c{[lisp]} @itemsep is this a list? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is a cons or @xlcode(nil), @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{endp(@i(list))} @c{[sal]} + + @xlcode{(endp@pragma(defn)@index(endp) @t(@i(list)))} @c{[lisp]} @itemsep is this the end of a list +@end(fgroup) +@begin(pdescription) + @i<list> @itemsep the list + + returns @itemsep @xlcode(t) if the value is @xlcode(nil), @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{consp(@i(expr))} @c{[sal]} + + @xlcode{(consp@pragma(defn)@index(consp) @t(@i(expr)))} @c{[lisp]} @itemsep is this a non-empty list? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is a cons, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{integerp(@i(expr))} @c{[sal]} + + @xlcode{(integerp@pragma(defn)@index(integerp) @t(@i(expr)))} @c{[lisp]} @itemsep is this an integer? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is an integer, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{floatp(@i(expr))} @c{[sal]} + + @xlcode{(floatp@pragma(defn)@index(floatp) @t(@i(expr)))} @c{[lisp]} @itemsep is this a float? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is a float, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{stringp(@i(expr))} @c{[sal]} + + @xlcode{(stringp@pragma(defn)@index(stringp) @t(@i(expr)))} @c{[lisp]} @itemsep is this a string? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is a string, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{characterp(@i(expr))} @c{[sal]} + + @xlcode{(characterp@pragma(defn)@index(characterp) @t(@i(expr)))} @c{[lisp]} @itemsep is this a character? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is a character, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{arrayp(@i(expr))} @c{[sal]} + + @xlcode{(arrayp@pragma(defn)@index(arrayp) @t(@i(expr)))} @c{[lisp]} @itemsep is this an array? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is an array, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{streamp(@i(expr))} @c{[sal]} + + @xlcode{(streamp@pragma(defn)@index(streamp) @t(@i(expr)))} @c{[lisp]} @itemsep is this a stream? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is a stream, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{objectp(@i(expr))} @c{[sal]} + + @xlcode{(objectp@pragma(defn)@index(objectp) @t(@i(expr)))} @c{[lisp]} @itemsep is this an object? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is an object, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{filep(@i(expr))} @c{[sal]} + + @xlcode{(filep@pragma(defn)@index(filep) @t(@i(expr)))} @c{[lisp]}@foot(This is not part of standard XLISP nor is it built-in. Nyquist defines it though.) @itemsep is this a file? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to check + + returns @itemsep @xlcode(t) if the value is an object, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{boundp(@i(sym))} @c{[sal]} + + @xlcode{(boundp@pragma(defn)@index(boundp) @t(@i(sym)))} @c{[lisp]} @itemsep is a value bound to this symbol? +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the symbol + + returns @itemsep @xlcode(t) if a value is bound to the symbol, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{fboundp(@i(sym))} @c{[sal]} + + @xlcode{(fboundp@pragma(defn)@index(fboundp) @t(@i(sym)))} @c{[lisp]} @itemsep is a functional value bound to this symbol? +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the symbol + + returns @itemsep @xlcode(t) if a functional value is bound to the symbol, + + @xlcode(nil) otherwise +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{minusp(@i(expr))} @c{[sal]} + + @xlcode{(minusp@pragma(defn)@index(minusp) @t(@i(expr)))} @c{[lisp]} @itemsep is this number negative? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the number to test + + returns @itemsep @xlcode(t) if the number is negative, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{zerop(@i(expr))} @c{[sal]} + + @xlcode{(zerop@pragma(defn)@index(zerop) @t(@i(expr)))} @c{[lisp]} @itemsep is this number zero? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the number to test + + returns @itemsep @xlcode(t) if the number is zero, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{plusp(@i(expr))} @c{[sal]} + + @xlcode{(plusp@pragma(defn)@index(plusp) @t(@i(expr)))} @c{[lisp]} @itemsep is this number positive? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the number to test + + returns @itemsep @xlcode(t) if the number is positive, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{evenp(@i(expr))} @c{[sal]} + + @xlcode{(evenp@pragma(defn)@index(evenp) @t(@i(expr)))} @c{[lisp]} @itemsep is this integer even? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the integer to test + + returns @itemsep @xlcode(t) if the integer is even, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{oddp(@i(expr))} @c{[sal]} + + @xlcode{(oddp@pragma(defn)@index(oddp) @t(@i(expr)))} @c{[lisp]} @itemsep is this integer odd? +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the integer to test + + returns @itemsep @xlcode(t) if the integer is odd, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{eq(@i(expr1), @i(expr2))} @c{[sal]} + + @xlcode{(eq@pragma(defn)@index(eq) @t(@i(expr1)) @t(@i(expr2)))} @c{[lisp]} @itemsep are the expressions identical? +@end(fgroup) +@begin(pdescription) + @i<expr1> @itemsep the first expression + + @i<expr2> @itemsep the second expression + + returns @itemsep @xlcode(t) if they are equal, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + +@begin(fgroup)@xlcode{eql(@i(expr1), @i(expr2))} @c{[sal]} + + @xlcode{(eql@pragma(defn)@index(eql) @t(@i(expr1)) @t(@i(expr2)))} @c{[lisp]} @itemsep are the expressions identical? (works with all numbers) +@end(fgroup) +@begin(pdescription) + @i<expr1> @itemsep the first expression + + @i<expr2> @itemsep the second expression + + returns @itemsep @xlcode(t) if they are equal, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{equal(@i(expr1), @i(expr2))} @c{[sal]} + + @xlcode{(equal@pragma(defn)@index(equal) @t(@i(expr1)) @t(@i(expr2)))} @c{[lisp]} @itemsep are the expressions equal? +@end(fgroup) +@begin(pdescription) + @i<expr1> @itemsep the first expression + + @i<expr2> @itemsep the second expression + + returns @itemsep @xlcode(t) if they are equal, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Control Constructs)@index(Control Constructs) +@begin(fdescription) + @xlcode{(cond@pragma(defn)@index(cond) @t(@i(pair))@r(...))} @c{[lisp]} @itemsep evaluate conditionally +@begin(pdescription) + @i<pair> @itemsep pair consisting of: + +@begin(pdescription) + (@i<pred> @i<expr>...) +@end(pdescription)@pragma(stopcodef) + where: +@begin(pdescription) + @i<pred> @itemsep is a predicate expression + + @i<expr> @itemsep evaluated if the predicate + is not @xlcode(nil) +@end(pdescription)@pragma(stopcodef) +returns @itemsep the value of the first expression whose predicate is not +@xlcode(nil) +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{and(@i(expr)@r(...))} @c{[sal]} + + @xlcode{(and@pragma(defn)@index(and) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep the logical and of a list of expressions +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expressions to be anded + + returns @itemsep @xlcode(nil) if any expression evaluates to @xlcode(nil), + otherwise the value of the last expression + (evaluation of expressions stops after the first + expression that evaluates to @xlcode(nil)) +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{or(@i(expr)@r(...))} @c{[sal]} + + @xlcode{(or@pragma(defn)@index(or) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep the logical or of a list of expressions +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expressions to be ored + + returns @itemsep @xlcode(nil) if all expressions evaluate to @xlcode(nil), + otherwise the value of the first non-@xlcode(nil) expression + (evaluation of expressions stops after the first + expression that does not evaluate to @xlcode(nil)) +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{if(@i(texpr), @i(expr1)[, @i(expr2)])} @c{[sal]} + + @xlcode{(if@pragma(defn)@index(if) @t(@i(texpr)) @t(@i(expr1)) [@t(@i(expr2))])} @c{[lisp]} @itemsep evaluate expressions conditionally +@end(fgroup) +@begin(pdescription) + @i<texpr> @itemsep the test expression + + @i<expr1> @itemsep the expression to be evaluated if texpr is non-@xlcode(nil) + + @i<expr2> @itemsep the expression to be evaluated if texpr is @xlcode(nil) + + returns @itemsep the value of the selected expression + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{when(@i(texpr), @i(expr)@r(...))} @c{[sal]} + + @xlcode{(when@pragma(defn)@index(when) @t(@i(texpr)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep evaluate only when a condition is true +@end(fgroup) +@begin(pdescription) + @i<texpr> @itemsep the test expression + + @i<expr> @itemsep the expression(s) to be evaluated if texpr is non-@xlcode(nil) + + returns @itemsep the value of the last expression or @xlcode(nil) +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{unless(@i(texpr), @i(expr)@r(...))} @c{[sal]} + + @xlcode{(unless@pragma(defn)@index(unless) @t(@i(texpr)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep evaluate only when a condition is false +@end(fgroup) +@begin(pdescription) + @i<texpr> @itemsep the test expression + + @i<expr> @itemsep the expression(s) to be evaluated if texpr is @xlcode(nil) + + returns @itemsep the value of the last expression or @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + @xlcode{(case@pragma(defn)@index(case) @t(@i(expr)) @t(@i(case))@r(...))} @c{[lisp]} @itemsep select by case +@begin(pdescription) + @i<expr> @itemsep the selection expression + + @i<case> @itemsep pair consisting of: + +@begin(pdescription) + (@i<value> @i<expr>...) +@end(pdescription)@pragma(stopcodef) + where: +@begin(pdescription) + @i<value> @itemsep is a single expression or a list of + expressions (unevaluated) + + @i<expr> @itemsep are expressions to execute if the + case matches +@end(pdescription)@pragma(stopcodef) + returns @itemsep the value of the last expression of the matching case + +@end(pdescription) +@blankspace(1) +@begin(fgroup) + @xlcode{(let@pragma(defn)@index(let) (@t(@i(binding))@r(...)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep create local bindings + +@pragma(startcodef) + @xlcode{(let*@pragma(defn)@index(let*) (@t(@i(binding))@r(...)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep let with sequential binding +@end(fgroup) +@begin(pdescription) + @i<binding> @itemsep the variable bindings each of which is either: + +@begin(pdescription) + 1) a symbol (which is initialized to @xlcode(nil)) + + 2) a list whose car is a symbol and whose cadr + is an initialization expression +@end(pdescription)@pragma(stopcodef) + @i<expr> @itemsep the expressions to be evaluated + + returns @itemsep the value of the last expression + +@end(pdescription) +@blankspace(1) +@begin(fgroup) + @xlcode{(flet@pragma(defn)@index(flet) (@t(@i(binding))@r(...)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep create local functions + +@pragma(startcodef) + @xlcode{(labels@pragma(defn)@index(labels) (@t(@i(binding))@r(...)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep flet with recursive functions + +@pragma(startcodef) + @xlcode{(macrolet@pragma(defn)@index(macrolet) (@t(@i(binding))@r(...)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep create local macros +@end(fgroup) +@begin(pdescription) + @i<binding> @itemsep the function bindings each of which is: + +@begin(pdescription) + (@i<sym> @i<fargs> @i<expr>...) +@end(pdescription)@pragma(stopcodef) + where: +@begin(pdescription) + @i<sym> @itemsep the function/macro name + + @i<fargs> @itemsep formal argument list (lambda list) + + @i<expr> @itemsep expressions constituting the body of + the function/macro +@end(pdescription)@pragma(stopcodef) + @i<expr> @itemsep the expressions to be evaluated + + returns @itemsep the value of the last expression +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{catch(@i(sym), @i(expr)@r(...))} @c{[sal]} + + @xlcode{(catch@pragma(defn)@index(catch) @t(@i(sym)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep evaluate expressions and catch throws +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the catch tag + + @i<expr> @itemsep expressions to evaluate + + returns @itemsep the value of the last expression the throw expression + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{throw(@i(sym)[, @i(expr)])} @c{[sal]} + + @xlcode{(throw@pragma(defn)@index(throw) @t(@i(sym)) [@t(@i(expr))])} @c{[lisp]} @itemsep throw to a catch +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the catch tag + + @i<expr> @itemsep the value for the catch to return (defaults to @xlcode(nil)) + + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{unwind-protect(@i(expr), @i(cexpr)@r(...))} @c{[sal]} + + @xlcode{(unwind-protect@pragma(defn)@index(unwind-protect) @t(@i(expr)) @t(@i(cexpr))@r(...))} @c{[lisp]} @itemsep protect evaluation of an expression +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to protect + + @i<cexpr> @itemsep the cleanup expressions + + returns @itemsep the value of the expression@* + + Note: unwind-protect guarantees to execute the cleanup expressions + even if a non-local exit terminates the evaluation of the + protected expression +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Looping Constructs)@index(Looping Constructs) +@begin(fdescription) + @xlcode{(loop@pragma(defn)@index(loop) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep basic looping form +@begin(pdescription) + @i<expr> @itemsep the body of the loop + + returns @itemsep never returns (must use non-local exit) + +@end(pdescription) +@blankspace(1) +@begin(fgroup) + @xlcode{(do@pragma(defn)@index(do) (@t(@i(binding))@r(...)) (@t(@i(texpr)) @t(@i(rexpr))@r(...)) @t(@i(expr))@r(...))} @c{[lisp]} +@pragma(endcodef) + @xlcode{(do*@pragma(defn)@index(do*) (@t(@i(binding))@r(...)) (@t(@i(texpr)) @t(@i(rexpr))@r(...)) @t(@i(expr))@r(...))} @c{[lisp]} +@end(fgroup) +@begin(pdescription) + @i<binding> @itemsep the variable bindings each of which is either: + +@begin(pdescription) + 1) a symbol (which is initialized to @xlcode(nil)) + + 2) a list of the form: (@i<sym> @i<init> [@i<step>]) + where: +@begin(pdescription) + @i<sym> @itemsep is the symbol to bind + + @i<init> @itemsep is the initial value of the symbol + + @i<step> @itemsep is a step expression + +@end(pdescription) +@end(pdescription)@pragma(stopcodef) + @i<texpr> @itemsep the termination test expression + + @i<rexpr> @itemsep result expressions (the default is @xlcode(nil)) + + @i<expr> @itemsep the body of the loop (treated like an implicit prog) + + returns @itemsep the value of the last result expression + +@end(pdescription) +@blankspace(1) + + @xlcode{(dolist@pragma(defn)@index(dolist) (@t(@i(sym)) @t(@i(expr)) [@t(@i(rexpr))]) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep loop through a list +@begin(pdescription) + @i<sym> @itemsep the symbol to bind to each list element + + @i<expr> @itemsep the list expression + + @i<rexpr> @itemsep the result expression (the default is @xlcode(nil)) + + @i<expr> @itemsep the body of the loop (treated like an implicit prog) + +@end(pdescription) +@blankspace(1) + + @xlcode{(dotimes@pragma(defn)@index(dotimes) (@t(@i(sym)) @t(@i(expr)) [@t(@i(rexpr))]) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep loop from zero to n-1 +@begin(pdescription) + @i<sym> @itemsep the symbol to bind to each value from 0 to n-1 + + @i<expr> @itemsep the number of times to loop + + @i<rexpr> @itemsep the result expression (the default is @xlcode(nil)) + + @i<expr> @itemsep the body of the loop (treated like an implicit prog) + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(The Program Feature)@index(The Program Feature) +@begin(fdescription) +@begin(fgroup) +@xlcode{(prog@pragma(defn)@index(prog) (@t(@i(binding))@r(...)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep the program feature + +@pragma(startcodef) +@xlcode{(prog*@pragma(defn)@index(prog*) (@t(@i(binding))@r(...)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep prog with sequential binding +@end(fgroup) +@begin(pdescription) + @i<binding> @itemsep the variable bindings each of which is either: + +@begin(pdescription) + 1) a symbol (which is initialized to @xlcode(nil)) + + 2) a list whose car is a symbol and whose cadr + is an initialization expression +@end(pdescription)@pragma(stopcodef) + @i<expr> @itemsep expressions to evaluate or tags (symbols) + + returns @itemsep @xlcode(nil) or the argument passed to the return function + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{block(@i(name), @i(expr)@r(...))} @c{[sal]} + + @xlcode{(block@pragma(defn)@index(block) @t(@i(name)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep named block +@end(fgroup) +@begin(pdescription) + @i<name> @itemsep the block name (symbol) + + @i<expr> @itemsep the block body + + returns @itemsep the value of the last expression + +@end(pdescription) +@blankspace(1) + + @xlcode{(return@pragma(defn)@index(return) [@t(@i(expr))])} @c{[lisp]} @itemsep cause a prog construct to return a value +@begin(pdescription) + @i<expr> @itemsep the value (defaults to @xlcode(nil)) + + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{return-from(@i(name)[, @i(value)])} @c{[sal]} + + @xlcode{(return-from@pragma(defn)@index(return-from) @t(@i(name)) [@t(@i(value))])} @c{[lisp]} @itemsep return from a named block +@end(fgroup) +@begin(pdescription) + @i<name> @itemsep the block name (symbol) + + @i<value> @itemsep the value to return (defaults to @xlcode(nil)) + + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{tagbody(@i(expr)@r(...))} @c{[sal]} + + @xlcode{(tagbody@pragma(defn)@index(tagbody) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep block with labels +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep expression(s) to evaluate or tags (symbols) + + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{go(@i(sym))} @c{[sal]} + + @xlcode{(go@pragma(defn)@index(go) @t(@i(sym)))} @c{[lisp]} @itemsep go to a tag within a tagbody or prog +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the tag (quoted) + + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + @xlcode{(progv@pragma(defn)@index(progv) @t(@i(slist)) @t(@i(vlist)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep dynamically bind symbols +@begin(pdescription) + @i<slist> @itemsep list of symbols + + @i<vlist> @itemsep list of values to bind to the symbols + + @i<expr> @itemsep expression(s) to evaluate + + returns @itemsep the value of the last expression + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{prog1(@i(expr1), @i(expr)@r(...))} @c{[sal]} + + @xlcode{(prog1@pragma(defn)@index(prog1) @t(@i(expr1)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep execute expressions sequentially +@end(fgroup) +@begin(pdescription) + @i<expr1> @itemsep the first expression to evaluate + + @i<expr> @itemsep the remaining expressions to evaluate + + returns @itemsep the value of the first expression + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{prog2(@i(expr1), @i(expr2), @i(expr)@r(...))} @c{[sal]} + + @xlcode{(prog2@pragma(defn)@index(prog2) @t(@i(expr1)) @t(@i(expr2)) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep execute expressions sequentially +@end(fgroup) +@begin(pdescription) + @i<expr1> @itemsep the first expression to evaluate + + @i<expr2> @itemsep the second expression to evaluate + + @i<expr> @itemsep the remaining expressions to evaluate + + returns @itemsep the value of the second expression + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{progn(@i(expr)@r(...))} @c{[sal]} + + @xlcode{(progn@pragma(defn)@index(progn) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep execute expressions sequentially +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expressions to evaluate + + returns @itemsep the value of the last expression (or @xlcode(nil)) + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Debugging and Error Handling)@index(Debugging)@index(Error Handling) +@begin(fdescription) + @begin(fgroup)@xlcode{trace(@i(sym))} @c{[sal]} + + @xlcode{(trace@pragma(defn)@index(trace) @t(@i(sym)))} @c{[lisp]} @itemsep add a function to the trace list +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the function to add (quoted) + + returns @itemsep the trace list + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{untrace(@i(sym))} @c{[sal]} + + @xlcode{(untrace@pragma(defn)@index(untrace) @t(@i(sym)))} @c{[lisp]} @itemsep remove a function from the trace list +@end(fgroup) +@begin(pdescription) + @i<sym> @itemsep the function to remove (quoted) + + returns @itemsep the trace list + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{error(@i(emsg)[, @i(arg)])} @c{[sal]} + + @xlcode{(error@pragma(defn)@index(error) @t(@i(emsg)) [@t(@i(arg))])} @c{[lisp]} @itemsep signal a non-correctable error +@end(fgroup) +@begin(pdescription) + @i<emsg> @itemsep the error message string + + @i<arg> @itemsep the argument expression (printed after the message) + + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{cerror(@i(cmsg), @i(emsg)[, @i(arg)])} @c{[sal]} + + @xlcode{(cerror@pragma(defn)@index(cerror) @t(@i(cmsg)) @t(@i(emsg)) [@t(@i(arg))])} @c{[lisp]} @itemsep signal a correctable error +@end(fgroup) +@begin(pdescription) + @i<cmsg> @itemsep the continue message string + + @i<emsg> @itemsep the error message string + + @i<arg> @itemsep the argument expression (printed after the message) + + returns @itemsep @xlcode(nil) when continued from the break loop + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{break([@i(bmsg)[, @i(arg)]])} @c{[sal]} + + @xlcode{(break@pragma(defn)@index(break) [@t(@i(bmsg)) [@t(@i(arg))]])} @c{[lisp]} @itemsep enter a break loop +@end(fgroup) +@begin(pdescription) + @i<bmsg> @itemsep the break message string (defaults to @xlcode(**break**)) + + @i<arg> @itemsep the argument expression (printed after the message) + + returns @itemsep @xlcode(nil) when continued from the break loop + +@end(pdescription) +@blankspace(1) + + @xlcode{(clean-up@pragma(defn)@index(clean-up))} @c{[lisp]} @itemsep clean-up after an error +@begin(pdescription) + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + @xlcode{(top-level@pragma(defn)@index(top-level))} @c{[lisp]} @itemsep clean-up after an error and return to the top level +@begin(pdescription) + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + @xlcode{(continue@pragma(defn)@index(continue))} @c{[lisp]} @itemsep continue from a correctable error +@begin(pdescription) + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + @xlcode{(errset@pragma(defn)@index(errset) @t(@i(expr)) [@t(@i(pflag))])} @c{[lisp]} @itemsep trap errors +@begin(pdescription) + @i<expr> @itemsep the expression to execute + + @i<pflag> @itemsep flag to control printing of the error message + + returns @itemsep the value of the last expression consed with @xlcode(nil) + + or @xlcode(nil) on error +@end(pdescription) +@blankspace(1) + + @xlcode{(baktrace@pragma(defn)@index(baktrace)@index(debugging)@index(stack trace) [@t(@i(n))])} @c{[lisp]} @itemsep print n levels of trace back information +@begin(pdescription) + @i<n> @itemsep the number of levels (defaults to all levels) + + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + @xlcode{(evalhook@pragma(defn)@index(evalhook) @t(@i(expr)) @t(@i(ehook)) @t(@i(ahook)) [@t(@i(env))])} @c{[lisp]} @itemsep evaluate with hooks +@begin(pdescription) + @i<expr> @itemsep the expression to evaluate + + @i<ehook> @itemsep the value for @xlcode(*evalhook*) + + @i<ahook> @itemsep the value for @xlcode(*applyhook*) + + @i<env> @itemsep the environment (default is @xlcode(nil)) + + returns @itemsep the result of evaluating the expression + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{profile(@i(flag))} @c{[sal]} + + @xlcode{(profile@pragma(defn)@index(profile) @t(@i(flag)))} @c{[lisp]}@foot(This is not a standard XLISP 2.0 function.) @itemsep turn profiling on or off. +@end(fgroup) +@begin(pdescription) + @i<flag> @itemsep @xlcode(nil) turns profiling off, otherwise on + + returns @itemsep the previous state of profiling. + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Arithmetic Functions)@index(Arithmetic Functions) +@begin(fdescription) + @begin(fgroup)@xlcode{truncate(@i(expr))} @c{[sal]} + + @xlcode{(truncate@pragma(defn)@index(truncate) @t(@i(expr)))} @c{[lisp]} @itemsep truncates a floating point number to an integer +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the number + + returns @itemsep the result of truncating the number + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{float(@i(expr))} @c{[sal]} + + @xlcode{(float@pragma(defn)@index(float) @t(@i(expr)))} @c{[lisp]} @itemsep converts an integer to a floating point number +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the number + + returns @itemsep the result of floating the integer + +@end(pdescription) +@blankspace(1) + + @xlcode{(+@pragma(defn)@index(+) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep add a list of numbers +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the addition + +@end(pdescription) +@blankspace(1) + + @xlcode{(-@pragma(defn)@index(-) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep subtract a list of numbers or negate a single number +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the subtraction + +@end(pdescription) +@blankspace(1) + + @xlcode{(*@pragma(defn)@index(*) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep multiply a list of numbers +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the multiplication + +@end(pdescription) +@blankspace(1) + + @xlcode{(/@pragma(defn)@index(/) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep divide a list of numbers +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the division + +@end(pdescription) +@blankspace(1) + + @xlcode{(1+@pragma(defn)@index(1+) @t(@i(expr)))} @c{[lisp]} @itemsep add one to a number +@begin(pdescription) + @i<expr> @itemsep the number + + returns @itemsep the number plus one + +@end(pdescription) +@blankspace(1) + + @xlcode{(1-@pragma(defn)@index(1-) @t(@i(expr)))} @c{[lisp]} @itemsep subtract one from a number +@begin(pdescription) + @i<expr> @itemsep the number + + returns @itemsep the number minus one + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{rem(@i(expr)@r(...))} @c{[sal]} + + @xlcode{(rem@pragma(defn)@index(rem)@index(remainder)@index(modulo (rem) function) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep remainder of a list of numbers +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the remainder operation + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{min(@i(expr)@r(...))} @c{[sal]} + + @xlcode{(min@pragma(defn)@index(min)@index(minimum) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep the smallest of a list of numbers +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expressions to be checked + + returns @itemsep the smallest number in the list + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{max(@i(expr)@r(...))} @c{[sal]} + + @xlcode{(max@pragma(defn)@index(max)@index(maximum) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep the largest of a list of numbers +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expressions to be checked + + returns @itemsep the largest number in the list + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{abs(@i(expr))} @c{[sal]} + + @xlcode{(abs@pragma(defn)@index(abs) @t(@i(expr)))} @c{[lisp]} @itemsep the absolute value of a number +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the number + + returns @itemsep the absolute value of the number + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{gcd(@i(n1), @i(n2)@r(...))} @c{[sal]} + + @xlcode{(gcd@pragma(defn)@index(gcd) @t(@i(n1)) @t(@i(n2))@r(...))} @c{[lisp]} @itemsep compute the greatest common divisor +@end(fgroup) +@begin(pdescription) + @i<n1> @itemsep the first number (integer) + + @i<n2> @itemsep the second number(s) (integer) + + returns @itemsep the greatest common divisor + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{random(@i(n))} @c{[sal]} + + @xlcode{(random@pragma(defn)@index(random) @t(@i(n)))} @c{[lisp]} @itemsep compute a random number between 0 and n-1 inclusive +@end(fgroup) +@begin(pdescription) + @i<n> @itemsep the upper bound (integer) + + returns @itemsep a random number + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{rrandom()} @c{[sal]} + + @xlcode{(rrandom@pragma(defn)@index(rrandom)@index(uniform random))} @c{[lisp]} @itemsep compute a random real number between 0 and 1 inclusive +@end(fgroup) +@begin(pdescription) + returns @itemsep a random floating point number + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{sin(@i(expr))} @c{[sal]} + + @xlcode{(sin@pragma(defn)@index(sin) @t(@i(expr)))} @c{[lisp]} @itemsep compute the sine of a number +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the floating point number + + returns @itemsep the sine of the number + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{cos(@i(expr))} @c{[sal]} + + @xlcode{(cos@pragma(defn)@index(cos) @t(@i(expr)))} @c{[lisp]} @itemsep compute the cosine of a number +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the floating point number + + returns @itemsep the cosine of the number + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{tan(@i(expr))} @c{[sal]} + + @xlcode{(tan@pragma(defn)@index(tan) @t(@i(expr)))} @c{[lisp]} @itemsep compute the tangent of a number +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the floating point number + + returns @itemsep the tangent of the number + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{atan(@i(expr)[, @i(expr2)])} @c{[sal]} + + @xlcode{(atan@pragma(defn)@index(atan) @t(@i(expr)) [@t(@i(expr2))])} @c{[lisp]}@foot(This is not a standard XLISP 2.0 function.) @itemsep compute the arctangent +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the value of @i(x) + + @i<expr2> @itemsep the value of @i(y) (default value is 1.0) + + returns @itemsep the arctangent of @i(x)/@i(y) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{expt(@i(x-expr), @i(y-expr))} @c{[sal]} + + @xlcode{(expt@pragma(defn)@index(expt) @t(@i(x-expr)) @t(@i(y-expr)))} @c{[lisp]} @itemsep compute x to the y power +@end(fgroup) +@begin(pdescription) + @i<x-expr> @itemsep the floating point number + + @i<y-expr> @itemsep the floating point exponent + + returns @itemsep x to the y power + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{exp(@i(x-expr))} @c{[sal]} + + @xlcode{(exp@pragma(defn)@index(exp) @t(@i(x-expr)))} @c{[lisp]} @itemsep compute e to the x power +@end(fgroup) +@begin(pdescription) + @i<x-expr> @itemsep the floating point number + + returns @itemsep e to the x power + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{sqrt(@i(expr))} @c{[sal]} + + @xlcode{(sqrt@pragma(defn)@index(sqrt) @t(@i(expr)))} @c{[lisp]} @itemsep compute the square root of a number +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the floating point number + + returns @itemsep the square root of the number + +@end(pdescription) +@blankspace(1) +@begin(fgroup) +@xlcode{(<@pragma(defn)@index(<) @t(@i(n1)) @t(@i(n2))@r(...))} @c{[lisp]} @itemsep test for less than + +@xlcode{(<=@pragma(defn)@index(<=) @t(@i(n1)) @t(@i(n2))@r(...))} @c{[lisp]} @itemsep test for less than or equal to + +@xlcode{(=@pragma(defn)@index(=) @t(@i(n1)) @t(@i(n2))@r(...))} @c{[lisp]} @itemsep test for equal to + +@xlcode{(/=@pragma(defn)@index(/=) @t(@i(n1)) @t(@i(n2))@r(...))} @c{[lisp]} @itemsep test for not equal to + +@xlcode{(>=@pragma(defn)@index(>=) @t(@i(n1)) @t(@i(n2))@r(...))} @c{[lisp]} @itemsep test for greater than or equal to + +@xlcode{(>@pragma(defn)@index(>) @t(@i(n1)) @t(@i(n2))@r(...))} @c{[lisp]} @itemsep test for greater than +@end(fgroup) +@begin(pdescription) + @i<n1> @itemsep the first number to compare + + @i<n2> @itemsep the second number to compare + +returns @itemsep @xlcode(t) if the results of comparing @i<n1> with @i<n2>, +@i<n2> with @i<n3>, etc., are all true. + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Bitwise Logical Functions)@index(Bitwise Logical Functions) +@begin(fdescription) + @begin(fgroup)@xlcode{logand(@i(expr)@r(...))} @c{[sal]} + + @xlcode{(logand@pragma(defn)@index(logand) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep the bitwise and of a list of numbers +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the and operation + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{logior(@i(expr)@r(...))} @c{[sal]} + + @xlcode{(logior@pragma(defn)@index(logior) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep the bitwise inclusive or of a list of numbers +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the inclusive or operation + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{logxor(@i(expr)@r(...))} @c{[sal]} + + @xlcode{(logxor@pragma(defn)@index(logxor) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep the bitwise exclusive or of a list of numbers +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the numbers + + returns @itemsep the result of the exclusive or operation + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{lognot(@i(expr))} @c{[sal]} + + @xlcode{(lognot@pragma(defn)@index(lognot) @t(@i(expr)))} @c{[lisp]} @itemsep the bitwise not of a number +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the number + + returns @itemsep the bitwise inversion of number + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(String Functions)@index(String Functions) +@begin(fdescription) + @begin(fgroup)@xlcode{string(@i(expr))} @c{[sal]} + + @xlcode{(string@pragma(defn)@index(string) @t(@i(expr)))} @c{[lisp]} @itemsep make a string from a value +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep an integer (which is first converted into its ASCII character value), string, character, or symbol + + returns @itemsep the string representation of the argument + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{string-search(@i(pat), @i(str), start: @i(start), end: @i(end))} @c{[sal]} + + @xlcode{(string-search@pragma(defn)@index(string-search)@index(find string) @t(@i(pat)) @t(@i(str)) @t(&key )@t(:start) @t(:end))} @c{[lisp]}@foot(This is not a standard XLISP 2.0 function.) @itemsep search for pattern in string +@end(fgroup) +@begin(pdescription) + @i<pat> @itemsep a string to search for + + @i<str> @itemsep the string to be searched + + :start @itemsep the starting offset in str + + :end @itemsep the ending offset + 1 + + returns @itemsep index of pat in str or NIL if not found + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{string-trim(@i(bag), @i(str))} @c{[sal]} + + @xlcode{(string-trim@pragma(defn)@index(string-trim) @t(@i(bag)) @t(@i(str)))} @c{[lisp]} @itemsep trim both ends of a string +@end(fgroup) +@begin(pdescription) + @i<bag> @itemsep a string containing characters to trim + + @i<str> @itemsep the string to trim + + returns @itemsep a trimed copy of the string + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{string-left-trim(@i(bag), @i(str))} @c{[sal]} + + @xlcode{(string-left-trim@pragma(defn)@index(string-left-trim) @t(@i(bag)) @t(@i(str)))} @c{[lisp]} @itemsep trim the left end of a string +@end(fgroup) +@begin(pdescription) + @i<bag> @itemsep a string containing characters to trim + + @i<str> @itemsep the string to trim + + returns @itemsep a trimed copy of the string + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{string-right-trim(@i(bag), @i(str))} @c{[sal]} + + @xlcode{(string-right-trim@pragma(defn)@index(string-right-trim) @t(@i(bag)) @t(@i(str)))} @c{[lisp]} @itemsep trim the right end of a string +@end(fgroup) +@begin(pdescription) + @i<bag> @itemsep a string containing characters to trim + + @i<str> @itemsep the string to trim + + returns @itemsep a trimed copy of the string + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{string-upcase(@i(str), start: @i(start), end: @i(end))} @c{[sal]} + + @xlcode{(string-upcase@pragma(defn)@index(string-upcase) @t(@i(str)) @t(&key )@t(:start) @t(:end))} @c{[lisp]} @itemsep convert to uppercase +@end(fgroup) +@begin(pdescription) + @i<str> @itemsep the string + + :start @itemsep the starting offset + + :end @itemsep the ending offset + 1 + + returns @itemsep a converted copy of the string + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{string-downcase(@i(str), start: @i(start), end: @i(end))} @c{[sal]} + + @xlcode{(string-downcase@pragma(defn)@index(string-downcase) @t(@i(str)) @t(&key )@t(:start) @t(:end))} @c{[lisp]} @itemsep convert to lowercase +@end(fgroup) +@begin(pdescription) + @i<str> @itemsep the string + + :start @itemsep the starting offset + + :end @itemsep the ending offset + 1 + + returns @itemsep a converted copy of the string + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{nstring-upcase(@i(str), start: @i(start), end: @i(end))} @c{[sal]} + + @xlcode{(nstring-upcase@pragma(defn)@index(nstring-upcase) @t(@i(str)) @t(&key )@t(:start) @t(:end))} @c{[lisp]} @itemsep convert to uppercase +@end(fgroup) +@begin(pdescription) + @i<str> @itemsep the string + + :start @itemsep the starting offset + + :end @itemsep the ending offset + 1 + + returns @itemsep the converted string (not a copy) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{nstring-downcase(@i(str), start: @i(start), end: @i(end))} @c{[sal]} + + @xlcode{(nstring-downcase@pragma(defn)@index(nstring-downcase) @t(@i(str)) @t(&key )@t(:start) @t(:end))} @c{[lisp]} @itemsep convert to lowercase +@end(fgroup) +@begin(pdescription) + @i<str> @itemsep the string + + :start @itemsep the starting offset + + :end @itemsep the ending offset + 1 + + returns @itemsep the converted string (not a copy) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{strcat(@i(expr)@r(...))} @c{[sal]} + + @xlcode{(strcat@pragma(defn)@index(strcat)@index(concatenate strings) @t(@i(expr))@r(...))} @c{[lisp]} @itemsep concatenate strings +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the strings to concatenate + + returns @itemsep the result of concatenating the strings + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{subseq(@i(string), @i(start)[, @i(end)])} @c{[sal]} + + @xlcode{(subseq@pragma(defn)@index(subseq) @t(@i(string)) @t(@i(start)) [@t(@i(end))])} @c{[lisp]} @itemsep extract a substring +@end(fgroup) +@begin(pdescription) + @i<string> @itemsep the string + + @i<start> @itemsep the starting position (zero origin) + + @i<end> @itemsep the ending position + 1 (defaults to end) + + returns @itemsep substring between @i<start> and @i<end> + +@end(pdescription) +@blankspace(1) +@begin(fgroup) + @begin(fgroup)@xlcode{string<(@i(str1), @i(str2), start1: @i(start1), end1: @i(end1), start2: @i(start2), end2: @i(end2))} @c{[sal]} + + @xlcode{(string<@pragma(defn)@index(string<) @t(@i(str1)) @t(@i(str2)) @t(&key )@t(:start1) @t(:end1) @t(:start2) @t(:end2))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + @begin(fgroup)@xlcode{string<=(@i(str1), @i(str2), start1: @i(start1), end1: @i(end1), start2: @i(start2), end2: @i(end2))} @c{[sal]} + + @xlcode{(string<=@pragma(defn)@index(string<=) @t(@i(str1)) @t(@i(str2)) @t(&key )@t(:start1) @t(:end1) @t(:start2) @t(:end2))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + + @begin(fgroup)@xlcode{string=(@i(str1), @i(str2), start1: @i(start1), end1: @i(end1), start2: @i(start2), end2: @i(end2))} @c{[sal]} + + @xlcode{(string=@pragma(defn)@index(string=) @t(@i(str1)) @t(@i(str2)) @t(&key )@t(:start1) @t(:end1) @t(:start2) @t(:end2))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + + @begin(fgroup)@xlcode{string/=(@i(str1), @i(str2), start1: @i(start1), end1: @i(end1), start2: @i(start2), end2: @i(end2))} @c{[sal]} + + @xlcode{(string/=@pragma(defn)@index(string/=) @t(@i(str1)) @t(@i(str2)) @t(&key )@t(:start1) @t(:end1) @t(:start2) @t(:end2))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + + @begin(fgroup)@xlcode{string>=(@i(str1), @i(str2), start1: @i(start1), end1: @i(end1), start2: @i(start2), end2: @i(end2))} @c{[sal]} + + @xlcode{(string>=@pragma(defn)@index(string>=) @t(@i(str1)) @t(@i(str2)) @t(&key )@t(:start1) @t(:end1) @t(:start2) @t(:end2))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + + @begin(fgroup)@xlcode{string>(@i(str1), @i(str2), start1: @i(start1), end1: @i(end1), start2: @i(start2), end2: @i(end2))} @c{[sal]} + + @xlcode{(string>@pragma(defn)@index(string>) @t(@i(str1)) @t(@i(str2)) @t(&key )@t(:start1) @t(:end1) @t(:start2) @t(:end2))} @c{[lisp]} +@end(fgroup) +@end(fgroup) +@begin(pdescription) + @i<str1> @itemsep the first string to compare + + @i<str2> @itemsep the second string to compare + + :start1 @itemsep first substring starting offset + + :end1 @itemsep first substring ending offset + 1 + + :start2 @itemsep second substring starting offset + + :end2 @itemsep second substring ending offset + 1 + + returns @itemsep @xlcode(t) if predicate is true, @xlcode(nil) otherwise + + Note: case is significant with these comparison functions. +@end(pdescription) +@blankspace(1) +@begin(fgroup) +@begin(fgroup)@xlcode{string-lessp(@i(str1), @i(str2), start1: @i(start1), end1: @i(end1), start2: @i(start2), end2: @i(end2))} @c{[sal]} + + @xlcode{(string-lessp@pragma(defn)@index(string-lessp) @t(@i(str1)) @t(@i(str2)) @t(&key )@t(:start1) @t(:end1) @t(:start2) @t(:end2))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + +@begin(fgroup)@xlcode{string-not-greaterp(@i(str1), @i(str2), start1: @i(start1), end1: @i(end1), start2: @i(start2), end2: @i(end2))} @c{[sal]} + + @xlcode{(string-not-greaterp@pragma(defn)@index(string-not-greaterp) @t(@i(str1)) @t(@i(str2)) @t(&key )@t(:start1) @t(:end1) @t(:start2) @t(:end2))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + +@begin(fgroup)@xlcode{string-equalp(@i(str1), @i(str2), start1: @i(start1), end1: @i(end1), start2: @i(start2), end2: @i(end2))} @c{[sal]} + + @xlcode{(string-equalp@pragma(defn)@index(string-equalp) @t(@i(str1)) @t(@i(str2)) @t(&key )@t(:start1) @t(:end1) @t(:start2) @t(:end2))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + +@begin(fgroup)@xlcode{string-not-equalp(@i(str1), @i(str2), start1: @i(start1), end1: @i(end1), start2: @i(start2), end2: @i(end2))} @c{[sal]} + + @xlcode{(string-not-equalp@pragma(defn)@index(string-not-equalp) @t(@i(str1)) @t(@i(str2)) @t(&key )@t(:start1) @t(:end1) @t(:start2) @t(:end2))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + +@begin(fgroup)@xlcode{string-not-lessp(@i(str1), @i(str2), start1: @i(start1), end1: @i(end1), start2: @i(start2), end2: @i(end2))} @c{[sal]} + + @xlcode{(string-not-lessp@pragma(defn)@index(string-not-lessp) @t(@i(str1)) @t(@i(str2)) @t(&key )@t(:start1) @t(:end1) @t(:start2) @t(:end2))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + +@begin(fgroup)@xlcode{string-greaterp(@i(str1), @i(str2), start1: @i(start1), end1: @i(end1), start2: @i(start2), end2: @i(end2))} @c{[sal]} + + @xlcode{(string-greaterp@pragma(defn)@index(string-greaterp) @t(@i(str1)) @t(@i(str2)) @t(&key )@t(:start1) @t(:end1) @t(:start2) @t(:end2))} @c{[lisp]} +@end(fgroup) +@end(fgroup) +@begin(pdescription) + @i<str1> @itemsep the first string to compare + + @i<str2> @itemsep the second string to compare + + :start1 @itemsep first substring starting offset + + :end1 @itemsep first substring ending offset + 1 + + :start2 @itemsep second substring starting offset + + :end2 @itemsep second substring ending offset + 1 + + returns @itemsep @xlcode(t) if predicate is true, @xlcode(nil) otherwise + + Note: case is not significant with these comparison functions. +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Character Functions)@index(Character Functions) +@begin(fdescription) + @begin(fgroup)@xlcode{char(@i(string), @i(index))} @c{[sal]} + + @xlcode{(char@pragma(defn)@index(char) @t(@i(string)) @t(@i(index)))} @c{[lisp]} @itemsep extract a character from a string +@end(fgroup) +@begin(pdescription) + @i<string> @itemsep the string + + @i<index> @itemsep the string index (zero relative) + + returns @itemsep the ascii code of the character + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{upper-case-p(@i(chr))} @c{[sal]} + + @xlcode{(upper-case-p@pragma(defn)@index(upper-case-p) @t(@i(chr)))} @c{[lisp]} @itemsep is this an upper case character? +@end(fgroup) +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep @xlcode(t) if the character is upper case, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{lower-case-p(@i(chr))} @c{[sal]} + + @xlcode{(lower-case-p@pragma(defn)@index(lower-case-p) @t(@i(chr)))} @c{[lisp]} @itemsep is this a lower case character? +@end(fgroup) +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep @xlcode(t) if the character is lower case, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{both-case-p(@i(chr))} @c{[sal]} + + @xlcode{(both-case-p@pragma(defn)@index(both-case-p) @t(@i(chr)))} @c{[lisp]} @itemsep is this an alphabetic (either case) character? +@end(fgroup) +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep @xlcode(t) if the character is alphabetic, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{digit-char-p(@i(chr))} @c{[sal]} + + @xlcode{(digit-char-p@pragma(defn)@index(digit-char-p) @t(@i(chr)))} @c{[lisp]} @itemsep is this a digit character? +@end(fgroup) +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep the digit weight if character is a digit, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{char-code(@i(chr))} @c{[sal]} + + @xlcode{(char-code@pragma(defn)@index(char-code) @t(@i(chr)))} @c{[lisp]} @itemsep get the ascii code of a character +@end(fgroup) +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep the ascii character code (integer) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{code-char(@i(code))} @c{[sal]} + + @xlcode{(code-char@pragma(defn)@index(code-char) @t(@i(code)))} @c{[lisp]} @itemsep get the character with a specified ascii code +@end(fgroup) +@begin(pdescription) + @i<code> @itemsep the ascii code (integer) + + returns @itemsep the character with that code or @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{char-upcase(@i(chr))} @c{[sal]} + + @xlcode{(char-upcase@pragma(defn)@index(char-upcase) @t(@i(chr)))} @c{[lisp]} @itemsep convert a character to upper case +@end(fgroup) +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep the upper case character + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{char-downcase(@i(chr))} @c{[sal]} + + @xlcode{(char-downcase@pragma(defn)@index(char-downcase) @t(@i(chr)))} @c{[lisp]} @itemsep convert a character to lower case +@end(fgroup) +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep the lower case character + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{digit-char(@i(n))} @c{[sal]} + + @xlcode{(digit-char@pragma(defn)@index(digit-char) @t(@i(n)))} @c{[lisp]} @itemsep convert a digit weight to a digit +@end(fgroup) +@begin(pdescription) + @i<n> @itemsep the digit weight (integer) + + returns @itemsep the digit character or @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{char-int(@i(chr))} @c{[sal]} + + @xlcode{(char-int@pragma(defn)@index(char-int) @t(@i(chr)))} @c{[lisp]} @itemsep convert a character to an integer +@end(fgroup) +@begin(pdescription) + @i<chr> @itemsep the character + + returns @itemsep the ascii character code + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{int-char(@i(int))} @c{[sal]} + + @xlcode{(int-char@pragma(defn)@index(int-char) @t(@i(int)))} @c{[lisp]} @itemsep convert an integer to a character +@end(fgroup) +@begin(pdescription) + @i<int> @itemsep the ascii character code + + returns @itemsep the character with that code + +@end(pdescription) +@blankspace(1) +@begin(fgroup) + @begin(fgroup)@xlcode{char<(@i(chr1), @i(chr2)@r(...))} @c{[sal]} + + @xlcode{(char<@pragma(defn)@index(char<) @t(@i(chr1)) @t(@i(chr2))@r(...))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + + @begin(fgroup)@xlcode{char<=(@i(chr1), @i(chr2)@r(...))} @c{[sal]} + + @xlcode{(char<=@pragma(defn)@index(char<=) @t(@i(chr1)) @t(@i(chr2))@r(...))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + + @begin(fgroup)@xlcode{char=(@i(chr1), @i(chr2)@r(...))} @c{[sal]} + + @xlcode{(char=@pragma(defn)@index(char=) @t(@i(chr1)) @t(@i(chr2))@r(...))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + + @begin(fgroup)@xlcode{char/=(@i(chr1), @i(chr2)@r(...))} @c{[sal]} + + @xlcode{(char/=@pragma(defn)@index(char/=) @t(@i(chr1)) @t(@i(chr2))@r(...))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + + @begin(fgroup)@xlcode{char>=(@i(chr1), @i(chr2)@r(...))} @c{[sal]} + + @xlcode{(char>=@pragma(defn)@index(char>=) @t(@i(chr1)) @t(@i(chr2))@r(...))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + + @begin(fgroup)@xlcode{char>(@i(chr1), @i(chr2)@r(...))} @c{[sal]} + + @xlcode{(char>@pragma(defn)@index(char>) @t(@i(chr1)) @t(@i(chr2))@r(...))} @c{[lisp]} +@end(fgroup) +@end(fgroup) +@begin(pdescription) + @i<chr1> @itemsep the first character to compare + + @i<chr2> @itemsep the second character(s) to compare + + returns @itemsep @xlcode(t) if predicate is true, @xlcode(nil) otherwise + + Note: case is significant with these comparison functions. +@end(pdescription) +@blankspace(1) +@begin(fgroup) +@begin(fgroup)@xlcode{char-lessp(@i(chr1), @i(chr2)@r(...))} @c{[sal]} + + @xlcode{(char-lessp@pragma(defn)@index(char-lessp) @t(@i(chr1)) @t(@i(chr2))@r(...))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + +@begin(fgroup)@xlcode{char-not-greaterp(@i(chr1), @i(chr2)@r(...))} @c{[sal]} + + @xlcode{(char-not-greaterp@pragma(defn)@index(char-not-greaterp) @t(@i(chr1)) @t(@i(chr2))@r(...))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + +@begin(fgroup)@xlcode{char-equalp(@i(chr1), @i(chr2)@r(...))} @c{[sal]} + + @xlcode{(char-equalp@pragma(defn)@index(char-equalp) @t(@i(chr1)) @t(@i(chr2))@r(...))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + +@begin(fgroup)@xlcode{char-not-equalp(@i(chr1), @i(chr2)@r(...))} @c{[sal]} + + @xlcode{(char-not-equalp@pragma(defn)@index(char-not-equalp) @t(@i(chr1)) @t(@i(chr2))@r(...))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + +@begin(fgroup)@xlcode{char-not-lessp(@i(chr1), @i(chr2)@r(...))} @c{[sal]} + + @xlcode{(char-not-lessp@pragma(defn)@index(char-not-lessp) @t(@i(chr1)) @t(@i(chr2))@r(...))} @c{[lisp]} +@end(fgroup) +@pragma(endcodef) + +@begin(fgroup)@xlcode{char-greaterp(@i(chr1), @i(chr2)@r(...))} @c{[sal]} + + @xlcode{(char-greaterp@pragma(defn)@index(char-greaterp) @t(@i(chr1)) @t(@i(chr2))@r(...))} @c{[lisp]} +@end(fgroup) +@end(fgroup) +@begin(pdescription) +@i<chr1> @itemsep the first string to compare + +@i<chr2> @itemsep the second string(s) to compare + +returns @itemsep @xlcode(t) if predicate is true, @xlcode(nil) otherwise + + Note: case is not significant with these comparison functions. +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(Input/Output Functions)@index(Input/Output Functions) +@begin(fdescription) + @begin(fgroup)@xlcode{read([@i(stream)[, @i(eof)[, @i(rflag)]]])} @c{[sal]} + + @xlcode{(read@pragma(defn)@index(read) [@t(@i(stream)) [@t(@i(eof)) [@t(@i(rflag))]]])} @c{[lisp]} @itemsep read an expression +@end(fgroup) +@begin(pdescription) + @i<stream> @itemsep the input stream (default is standard input) + + @i<eof> @itemsep the value to return on end of file (default is @xlcode(nil)) + + @i<rflag> @itemsep recursive read flag (default is @xlcode(nil)) + + returns @itemsep the expression read + +@end(pdescription) +@blankspace(1) + + @xlcode{(print@pragma(defn)@index(print) @t(@i(expr)) [@t(@i(stream))])} @c{[lisp]} @itemsep print an expression on a new line +@begin(pdescription) + @i<expr> @itemsep the expression to be printed + + @i<stream> @itemsep the output stream (default is standard output) + + returns @itemsep the expression + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{prin1(@i(expr)[, @i(stream)])} @c{[sal]} + + @xlcode{(prin1@pragma(defn)@index(prin1) @t(@i(expr)) [@t(@i(stream))])} @c{[lisp]} @itemsep print an expression +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to be printed + + @i<stream> @itemsep the output stream (default is standard output) + + returns @itemsep the expression + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{princ(@i(expr)[, @i(stream)])} @c{[sal]} + + @xlcode{(princ@pragma(defn)@index(princ) @t(@i(expr)) [@t(@i(stream))])} @c{[lisp]} @itemsep print an expression without quoting +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expressions to be printed + + @i<stream> @itemsep the output stream (default is standard output) + + returns @itemsep the expression + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{pprint(@i(expr)[, @i(stream)])} @c{[sal]} + + @xlcode{(pprint@pragma(defn)@index(pprint) @t(@i(expr)) [@t(@i(stream))])} @c{[lisp]} @itemsep pretty print an expression +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expressions to be printed + + @i<stream> @itemsep the output stream (default is standard output) + + returns @itemsep the expression + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{terpri([@i(stream)])} @c{[sal]} + + @xlcode{(terpri@pragma(defn)@index(terpri) [@t(@i(stream))])} @c{[lisp]} @itemsep terminate the current print line +@end(fgroup) +@begin(pdescription) + @i<stream> @itemsep the output stream (default is standard output) + + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{flatsize(@i(expr))} @c{[sal]} + + @xlcode{(flatsize@pragma(defn)@index(flatsize) @t(@i(expr)))} @c{[lisp]} @itemsep length of printed representation using prin1 +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression + + returns @itemsep the length + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{flatc(@i(expr))} @c{[sal]} + + @xlcode{(flatc@pragma(defn)@index(flatc) @t(@i(expr)))} @c{[lisp]} @itemsep length of printed representation using princ +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression + + returns @itemsep the length +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(The Format Function)@index(The Format Function) +@begin(fdescription) +@begin(fgroup)@xlcode{format(@i(stream), @i(fmt), @i(arg)@r(...))} @c{[sal]} + + @xlcode{(format@pragma(defn)@index(format) @t(@i(stream)) @t(@i(fmt)) @t(@i(arg))@r(...))} @c{[lisp]} @itemsep do formated +@end(fgroup) +output +@begin(pdescription) + @i<stream> @itemsep the output stream + + @i<fmt> @itemsep the format string + + @i<arg> @itemsep the format arguments + + returns @itemsep output string if @i<stream> is @xlcode(nil), @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) +@end(fdescription) + The format string can contain characters that should be copied + directly to the output and formatting directives. The + formatting directives are: +@begin(display) +@xlcode(~A) @itemsep print next argument using princ +@xlcode(~S) @itemsep print next argument using prin1 +@xlcode(~%) @itemsep start a new line +@xlcode(~~) @itemsep print a tilde character +@xlcode(~)<newline> @itemsep ignore this one newline and white space on the +next line up to the first non-white-space character or newline. This +allows strings to continue across multiple lines +@end(display) + +@section(File I/O Functions)@index(File I/O Functions) +Note that files are ordinarily opened as text. Binary files (such as standard midi files) must be opened with @xlcode(open-binary) on non-unix systems. +@begin(fdescription) + @begin(fgroup)@xlcode{open(@i(fname), direction: @i(direction))} @c{[sal]} + + @xlcode{(open@pragma(defn)@index(open) @t(@i(fname)) @t(&key )@t(:direction))} @c{[lisp]} @itemsep open a file stream +@end(fgroup) +@begin(pdescription) + @i<fname> @itemsep the file name string or symbol + + :direction @itemsep :input or :output (default is :input) + + returns @itemsep a stream + +@end(pdescription) +@blankspace(1) + @begin(fgroup)@xlcode{open-binary(@i(fname), direction: @i(direction))} @c{[sal]} + + @xlcode{(open-binary@pragma(defn)@index(open-binary)@index(open)@index(binary files) @t(@i(fname)) @t(&key )@t(:direction))} @c{[lisp]} @itemsep open a binary file stream +@end(fgroup) +@begin(pdescription) + @i<fname> @itemsep the file name string or symbol + + :direction @itemsep :input or :output (default is :input) + + returns @itemsep a stream + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{close(@i(stream))} @c{[sal]} + + @xlcode{(close@pragma(defn)@index(close) @t(@i(stream)))} @c{[lisp]} @itemsep close a file stream +@end(fgroup) +@begin(pdescription) + @i<stream> @itemsep the stream + + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{setdir(@i(path)[, @i(verbose)])} @c{[sal]} + + @xlcode{(setdir@pragma(defn)@index(setdir)@index(change directory) @t(@i(path)) [@t(@i(verbose))])} @c{[lisp]}@foot(This is not a standard XLISP 2.0 function.) @itemsep set current directory +@end(fgroup) +@begin(pdescription) + @i<path> @itemsep the path of the new directory + + @i<verbose> @itemsep print error message if current directory cannot be changed to @i(path) + + returns @itemsep the resulting full path, e.g. (setdir ".") gets the current working directory, or @xlcode(nil) if an error occurs + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{listdir(@i(path))} @c{[sal]} + + @xlcode{(listdir@pragma(defn)@index(listdir)@index(directory listing)@index(scan directory)@index(read directory)@index(list directory) @t(@i(path)))} @c{[lisp]}@foot(This is not a standard XLISP 2.0 function.) @itemsep get a directory listing +@end(fgroup) +@begin(pdescription) + @i<path> @itemsep the path of the directory to be listed + + returns @itemsep list of filenames in the directory + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{get-temp-path()} @c{[sal]} + + @xlcode{(get-temp-path@pragma(defn)@index(get-temp-path)@index(temporary files)@index(temp file))} @c{[lisp]}@foot(This is not a standard XLISP 2.0 function.) @itemsep get a path where a temporary file can be created. Under Windows, this is based on environment variables. If XLISP is running as a sub-process to Java, the environment may not exist, in which case the default result is the unfortunate choice @xlcode(c:\windows\). +@end(fgroup) +@begin(pdescription) + returns @itemsep the resulting full path as a string + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{get-user()} @c{[sal]} + + @xlcode{(get-user@pragma(defn)@index(get-user)@index(user name)@index(temp file))} @c{[lisp]}@foot(This is not a standard XLISP 2.0 function.) @itemsep get the user ID. In Unix systems (including OS X and Linux), this is the value of the USER environment variable. In Windows, this is currently just ``nyquist'', which is also returned if the environment variable cannot be accessed. This function is used to avoid the case of two users creating files of the same name in the same temp directory. +@end(fgroup) +@begin(pdescription) + returns @itemsep the string naming the user + +@end(pdescription) +@blankspace(1) + @begin(fgroup)@xlcode{find-in-xlisp-path(@i(filename))} @c{[sal]} + + @xlcode{(find-in-xlisp-path@pragma(defn)@index(find-in-xlisp-path) @t(@i(filename)))} @c{[lisp]}@foot(This is not a standard XLISP 2.0 function.) @itemsep search the XLISP search path (e.g. @xlcode(XLISPPATH) from the environment) for @i(filename). If @i(filename) is not found as is, and there is no file extension, append "@code(.lsp)" to @i(filename) and search again. The current directory is not searched. +@end(fgroup) +@begin(pdescription) + @i<filename> @itemsep the name of the file to search for + + returns @itemsep a full path name to the first occurrence found + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{read-char([@i(stream)])} @c{[sal]} + + @xlcode{(read-char@pragma(defn)@index(read-char)@index(get char) [@t(@i(stream))])} @c{[lisp]} @itemsep read a character from a stream +@end(fgroup) +@begin(pdescription) + @i<stream> @itemsep the input stream (default is standard input) + + returns @itemsep the character + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{peek-char([@i(flag)[, @i(stream)]])} @c{[sal]} + + @xlcode{(peek-char@pragma(defn)@index(peek-char) [@t(@i(flag)) [@t(@i(stream))]])} @c{[lisp]} @itemsep peek at the next character +@end(fgroup) +@begin(pdescription) + @i<flag> @itemsep flag for skipping white space (default is @xlcode(nil)) + + @i<stream> @itemsep the input stream (default is standard input) + + returns @itemsep the character (integer) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{write-char(@i(ch)[, @i(stream)])} @c{[sal]} + + @xlcode{(write-char@pragma(defn)@index(write-char) @t(@i(ch)) [@t(@i(stream))])} @c{[lisp]} @itemsep write a character to a stream +@end(fgroup) +@begin(pdescription) + @i<ch> @itemsep the character to write + + @i<stream> @itemsep the output stream (default is standard output) + + returns @itemsep the character + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{read-int([@i(stream)[, @i(length)]])} @c{[sal]} + + @xlcode{(read-int@pragma(defn)@index(read-int) [@t(@i(stream)) [@t(@i(length))]])} @c{[lisp]} @itemsep read a binary integer from a stream +@end(fgroup) +@begin(pdescription) + @i<stream> @itemsep the input stream (default is standard input) + + @i<length> @itemsep the length of the integer in bytes (default is 4) + + returns @itemsep the integer + +Note: Integers are assumed to be big-endian (high-order byte first) and +signed, regardless of the platform. To read little-endian format, use a +negative number for the length, e.g. -4 indicates a 4-bytes, low-order +byte first. The file should be opened in binary mode. + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{write-int(@i(ch)[, @i(stream)[, @i(length)]])} @c{[sal]} + + @xlcode{(write-int@pragma(defn)@index(write-int) @t(@i(ch)) [@t(@i(stream)) [@t(@i(length))]])} @c{[lisp]} @itemsep write a binary integer to a stream +@end(fgroup) +@begin(pdescription) + @i<ch> @itemsep the character to write + + @i<stream> @itemsep the output stream (default is standard output) + + @i<length> @itemsep the length of the integer in bytes (default is 4) + + returns @itemsep the integer + +Note: Integers are assumed to be big-endian (high-order byte first) and +signed, regardless of the platform. To write in little-endian format, use a +negative number for the length, e.g. -4 indicates a 4-bytes, low-order +byte first. The file should be opened in binary mode. + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{read-float([@i(stream)[, @i(length)]])} @c{[sal]} + + @xlcode{(read-float@pragma(defn)@index(read-float) [@t(@i(stream)) [@t(@i(length))]])} @c{[lisp]} @itemsep read a binary floating-point number from a stream +@end(fgroup) +@begin(pdescription) + @i<stream> @itemsep the input stream (default is standard input) + + @i<length> @itemsep the length of the float in bytes (default is 4, legal values are -4, -8, 4, and 8) + + returns @itemsep the integer + +Note: Floats are assumed to be big-endian (high-order byte first) and +signed, regardless of the platform. To read little-endian format, use a +negative number for the length, e.g. -4 indicates a 4-bytes, low-order +byte first. The file should be opened in binary mode. + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{write-float(@i(ch)[, @i(stream)[, @i(length)]])} @c{[sal]} + + @xlcode{(write-float@pragma(defn)@index(write-float) @t(@i(ch)) [@t(@i(stream)) [@t(@i(length))]])} @c{[lisp]} @itemsep write a binary floating-point number to a stream +@end(fgroup) +@begin(pdescription) + @i<ch> @itemsep the character to write + + @i<stream> @itemsep the output stream (default is standard output) + + @i<length> @itemsep the length of the float in bytes (default is 4, legal values are -4, -8, 4, and 8) + + returns @itemsep the integer + +Note: Floats are assumed to be big-endian (high-order byte first) and +signed, regardless of the platform. To write in little-endian format, use a +negative number for the length, e.g. -4 indicates a 4-bytes, low-order +byte first. The file should be opened in binary mode. + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{read-line([@i(stream)])} @c{[sal]} + + @xlcode{(read-line@pragma(defn)@index(read-line) [@t(@i(stream))])} @c{[lisp]} @itemsep read a line from a stream +@end(fgroup) +@begin(pdescription) + @i<stream> @itemsep the input stream (default is standard input) + + returns @itemsep the string + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{read-byte([@i(stream)])} @c{[sal]} + + @xlcode{(read-byte@pragma(defn)@index(read-byte) [@t(@i(stream))])} @c{[lisp]} @itemsep read a byte from a stream +@end(fgroup) +@begin(pdescription) + @i<stream> @itemsep the input stream (default is standard input) + + returns @itemsep the byte (integer) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{write-byte(@i(byte)[, @i(stream)])} @c{[sal]} + + @xlcode{(write-byte@pragma(defn)@index(write-byte) @t(@i(byte)) [@t(@i(stream))])} @c{[lisp]} @itemsep write a byte to a stream +@end(fgroup) +@begin(pdescription) + @i<byte> @itemsep the byte to write (integer) + + @i<stream> @itemsep the output stream (default is standard output) + + returns @itemsep the byte (integer) + +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(String Stream Functions)@index(String Stream Functions) + These functions operate on unnamed streams. An unnamed output + stream collects characters sent to it when it is used as the + destination of any output function. The functions +@xlcode(get-output-stream-string) and @xlcode(get-output-stream-list) return a string or a list of characters. + +An unnamed input stream is setup with the + @xlcode(make-string-input-stream) function and returns each character of the string when + it is used as the source of any input function. + +@begin(fdescription) +@blankspace(1) + @begin(fgroup)@xlcode{make-string-input-stream(@i(str)[, @i(start)[, @i(end)]])} @c{[sal]} + + @xlcode{(make-string-input-stream@pragma(defn)@index(make-string-input-stream) @t(@i(str)) [@t(@i(start)) [@t(@i(end))]])} @c{[lisp]} +@end(fgroup) +@begin(pdescription) + @i<str> @itemsep the string + + @i<start> @itemsep the starting offset + + @i<end> @itemsep the ending offset + 1 + + returns @itemsep an unnamed stream that reads from the string + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{make-string-output-stream)()} @c{[sal]} + + @xlcode{(make-string-output-stream)} @c{[lisp]}@pragma(defn)@index(make-string-output-stream) +@end(fgroup) +@begin(pdescription) + returns @itemsep an unnamed output stream + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{get-output-stream-string(@i(stream))} @c{[sal]} + + @xlcode{(get-output-stream-string@pragma(defn)@index(get-output-stream-string) @t(@i(stream)))} @c{[lisp]} +@end(fgroup) +@begin(pdescription) + @i<stream> @itemsep the output stream + + returns @itemsep the output so far as a string + + Note: the output stream is emptied by this function +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{get-output-stream-list(@i(stream))} @c{[sal]} + + @xlcode{(get-output-stream-list@pragma(defn)@index(get-output-stream-list) @t(@i(stream)))} @c{[lisp]} +@end(fgroup) +@begin(pdescription) + @i<stream> @itemsep the output stream + + returns @itemsep the output so far as a list + + Note: the output stream is emptied by this function +@end(pdescription) +@blankspace(1) +@end(fdescription) + +@section(System Functions)@index(System Functions) +Note: the @xlcode(load) function first tries to load a file from the current directory. A @code(.lsp) extension is added if there is not already an alphanumeric extension following a period. If that fails, XLISP searches the path, which is obtained from the XLISPPATH environment variable in Unix and HKEY_LOCAL_MACHINE\SOFTWARE\CMU\Nyquist\XLISPPATH under Win32. (The Macintosh version has no search path.) + +@begin(fdescription) + @begin(fgroup)@xlcode{get-env(@i(name))} @c{[sal]} + + @xlcode{(get-env@pragma(defn)@index(get-env)@index(getenv)@index(environment variables) @t(@i(name)))} @c{[lisp]} @itemsep get from an environment variable +@end(fgroup) +@begin(pdescription) + @i<name> @itemsep the name of the environment variable + + returns @itemsep string value of the environment variable, @xlcode(nil) if variable does not exist + +@end(pdescription) +@blankspace(1) + + @xlcode{(load@pragma(defn)@index(load) @t(@i(fname)) @t(&key )@t(:verbose) @t(:print))} @c{[lisp]} @itemsep load a source file +@begin(pdescription) + @i<fname> @itemsep the filename string or symbol + + :verbose @itemsep the verbose flag (default is t) + + :print @itemsep the print flag (default is @xlcode(nil)) + + returns @itemsep the filename + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{save(@i(fname))} @c{[sal]} + + @xlcode{(save@pragma(defn)@index(save) @t(@i(fname)))} @c{[lisp]} @itemsep save workspace to a file +@end(fgroup) +@begin(pdescription) + @i<fname> @itemsep the filename string or symbol + + returns @itemsep @xlcode(t) if workspace was written, @xlcode(nil) otherwise + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{restore(@i(fname))} @c{[sal]} + + @xlcode{(restore@pragma(defn)@index(restore) @t(@i(fname)))} @c{[lisp]} @itemsep restore workspace from a file +@end(fgroup) +@begin(pdescription) + @i<fname> @itemsep the filename string or symbol + + returns @itemsep @xlcode(nil) on failure, otherwise never returns + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{dribble([@i(fname)])} @c{[sal]} + + @xlcode{(dribble@pragma(defn)@index(dribble) [@t(@i(fname))])} @c{[lisp]} @itemsep create a file with a transcript of a session +@end(fgroup) +@begin(pdescription) + @i<fname> @itemsep file name string or symbol + (if missing, close current transcript) + + returns @itemsep @xlcode(t) if the transcript is opened, @xlcode(nil) if it is closed + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{gc()} @c{[sal]} + + @xlcode{(gc@pragma(defn)@index(gc))} @c{[lisp]} @itemsep force garbage collection +@end(fgroup) +@begin(pdescription) + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{expand(@i(num))} @c{[sal]} + + @xlcode{(expand@pragma(defn)@index(expand) @t(@i(num)))} @c{[lisp]} @itemsep expand memory by adding segments +@end(fgroup) +@begin(pdescription) + @i<num> @itemsep the number of segments to add + + returns @itemsep the number of segments added + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{alloc(@i(num))} @c{[sal]} + + @xlcode{(alloc@pragma(defn)@index(alloc) @t(@i(num)))} @c{[lisp]} @itemsep change number of nodes to allocate in each segment +@end(fgroup) +@begin(pdescription) + @i<num> @itemsep the number of nodes to allocate + + returns @itemsep the old number of nodes to allocate + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{info()} @c{[sal]} + + @xlcode{(info@pragma(defn)@index(info))} @c{[lisp]} @itemsep show information about memory usage. +@end(fgroup) +@begin(pdescription) + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{room()} @c{[sal]} + + @xlcode{(room@pragma(defn)@index(room))} @c{[lisp]} @itemsep show memory allocation statistics +@end(fgroup) +@begin(pdescription) + returns @itemsep @xlcode(nil) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{type-of(@i(expr))} @c{[sal]} + + @xlcode{(type-of@pragma(defn)@index(type-of) @t(@i(expr)))} @c{[lisp]} @itemsep returns the type of the expression +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the expression to return the type of + + returns @itemsep @xlcode(nil) if the value is @xlcode(nil) otherwise one of the symbols: + +@begin(pdescription) + SYMBOL @itemsep for symbols + + OBJECT @itemsep for objects + + CONS @itemsep for conses + + SUBR @itemsep for built-in functions + + FSUBR @itemsep for special forms + + CLOSURE @itemsep for defined functions + + STRING @itemsep for strings + + FIXNUM @itemsep for integers + + FLONUM @itemsep for floating point numbers + + CHARACTER @itemsep for characters + + FILE-STREAM @itemsep for file pointers + + UNNAMED-STREAM @itemsep for unnamed streams + + ARRAY @itemsep for arrays + +@end(pdescription) +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{peek(@i(addrs))} @c{[sal]} + + @xlcode{(peek@pragma(defn)@index(peek) @t(@i(addrs)))} @c{[lisp]} @itemsep peek at a location in memory +@end(fgroup) +@begin(pdescription) + @i<addrs> @itemsep the address to peek at (integer) + + returns @itemsep the value at the specified address (integer) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{poke(@i(addrs), @i(value))} @c{[sal]} + + @xlcode{(poke@pragma(defn)@index(poke) @t(@i(addrs)) @t(@i(value)))} @c{[lisp]} @itemsep poke a value into memory +@end(fgroup) +@begin(pdescription) + @i<addrs> @itemsep the address to poke (integer) + + @i<value> @itemsep the value to poke into the address (integer) + + returns @itemsep the value + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{bigendianp()} @c{[sal]} + + @xlcode{(bigendianp@pragma(defn)@index(bigendianp)@index(endian)@index(big endian)@index(little endian))} @c{[lisp]} @itemsep is this a big-endian machine? +@end(fgroup) +@begin(pdescription) + returns @itemsep T if this a big-endian architecture, storing the high-order byte of an integer at the lowest byte address of the integer; otherwise, NIL. +@foot(This is not a standard XLISP 2.0 function.) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{address-of(@i(expr))} @c{[sal]} + + @xlcode{(address-of@pragma(defn)@index(address-of) @t(@i(expr)))} @c{[lisp]} @itemsep get the address of an xlisp node +@end(fgroup) +@begin(pdescription) + @i<expr> @itemsep the node + + returns @itemsep the address of the node (integer) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{exit()} @c{[sal]} + + @xlcode{(exit@pragma(defn)@index(exit))} @c{[lisp]} @itemsep exit xlisp +@end(fgroup) +@begin(pdescription) + returns @itemsep never returns + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{setup-console()} @c{[sal]} + + @xlcode{(setup-console@pragma(defn)@index(setup-console)@index(window initialization))} @c{[lisp]} @itemsep set default console attributes +@end(fgroup) +@begin(pdescription) + returns @itemsep NIL + +Note: Under Windows, Nyquist normally starts up in a medium-sized console window with black text and a white background, with a window title of ``Nyquist.'' This is normally accomplished by calling @xlcode(setup-console) in @code(system.lsp). In Nyquist, you can avoid this behavior by setting @xlcode(*setup-console*) to NIL in your @code(init.lsp) file. If @xlcode(setup-console) is not called, Nyquist uses standard input and output as is. This is what you want if you are running Nyquist inside of emacs, for example.@index(emacs, using Nyquist with) + +@end(pdescription) +@blankspace(1) + + @begin(fgroup)@xlcode{echoenabled(@i(flag))} @c{[sal]} + + @xlcode{(echoenabled@pragma(defn)@index(echoenabled)@index(console, XLISP) @t(@i(flag)))} @c{[lisp]} @itemsep turn console input echoing on or off +@end(fgroup) +@begin(pdescription) + @i<flag> @itemsep T to enable echo, NIL to disable + + returns @itemsep NIL + +Note: This function is only implemented under Linux and Mac OS X. If Nyquist I/O is redirected through pipes, +the Windows version does not echo the input, but the Linux and Mac versions do. You can turn off echoing with +this function. Under windows it is defined to do nothing. + +@end(pdescription) +@end(fdescription) + +@section(File I/O Functions)@index(File I/O Functions) + +@subsection(Input from a File)@index(Input from a File) + +To open a file for input, use the @xlcode(open) function with the keyword +argument @xlcode(:direction) set to @xlcode(:input). To open a file for output, +use the @xlcode(open) function with the keyword argument @xlcode(:direction) set +to @xlcode(:output). The @xlcode(open) function takes a single required argument which +is the name of the file to be opened. This name can be in the form of a +string or a symbol. The @xlcode(open) function returns an object of type +@xlcode(FILE-STREAM) if it succeeds in opening the specified file. It returns the +value @xlcode(nil) if it fails. In order to manipulate the file, it is +necessary to save the value returned by the @xlcode(open) function. This is +usually done by assigning it to a variable with the @xlcode(setq) special form or by +binding it using @xlcode(let) or @xlcode(let*). Here is an example: +@begin(example) +(setq fp (open "init.lsp" :direction :input)) +@end(example) + Evaluating this expression will result in the file @code(init.lsp) + being opened. The file object that will be returned by the @xlcode(open) + function will be assigned to the variable @xlcode(fp). + + It is now possible to use the file for input. To read an + expression from the file, just supply the value of the @xlcode(fp) + variable as the optional @i(stream) argument to @xlcode(read). +@begin(example) +(read fp) +@end(example) + Evaluating this expression will result in reading the first + expression from the file @code(init.lsp). The expression will be + returned as the result of the @xlcode(read) function. More expressions + can be read from the file using further calls to the @xlcode(read) + function. When there are no more expressions to read, the @xlcode(read) + function will return @xlcode(nil) (or whatever value was supplied as the + second argument to @xlcode(read)). + + Once you are done reading from the file, you should close it. + To close the file, use the following expression: +@begin(example) +(close fp) +@end(example) + Evaluating this expression will cause the file to be closed. + +@subsection(Output to a File)@index(Output to a File) + + Writing to a file is pretty much the same as reading from one. + You need to open the file first. This time you should use the + @xlcode(open) function to indicate that you will do output to the file. + For example: +@begin(example) +(setq fp (open "test.dat" :direction :output)) +@end(example) + Evaluating this expression will open the file @code(test.dat) for + output. If the file already exists, its current contents will + be discarded. If it doesn't already exist, it will be created. + In any case, a @xlcode(FILE-STREAM) object will be returned by the @xlcode(OPEN) + function. This file object will be assigned to the @xlcode(fp) + variable. + + It is now possible to write to this file by supplying the value + of the @xlcode(fp) variable as the optional @i(stream) parameter in the @xlcode(print) function. +@begin(example) +(print "Hello there" fp) +@end(example) + Evaluating this expression will result in the string ``Hello + there'' being written to the file @code(test.dat). More data can be + written to the file using the same technique. + + Once you are done writing to the file, you should close it. + Closing an output file is just like closing an input file. +@begin(example) +(close fp) +@end(example) + Evaluating this expression will close the output file and make + it permanent. + +@subsection(A Slightly More Complicated File Example) + + This example shows how to open a file, read each Lisp expression + from the file and print it. It demonstrates the use of files + and the use of the optional @i(stream) argument to the @xlcode(read) + function. +@begin(programexample) +(do* ((fp (open "test.dat" :direction :input)) + (ex (read fp) (read fp))) + ((null ex) nil) + (print ex)) +@end(programexample) + |
