diff options
| author | Steve M. Robbins <smr@debian.org> | 2011-10-22 04:54:51 +0200 |
|---|---|---|
| committer | Steve M. Robbins <smr@debian.org> | 2011-10-22 04:54:51 +0200 |
| commit | dd657ad3f1428b026486db3ec36691df17ddf515 (patch) | |
| tree | 6ffb465595479fb5a76c1a6ea3ec992abaa8c1c1 /docsrc/xlisp/xlisp-doc/tutorials | |
Import nyquist_3.05.orig.tar.gz
[dgit import orig nyquist_3.05.orig.tar.gz]
Diffstat (limited to 'docsrc/xlisp/xlisp-doc/tutorials')
| -rw-r--r-- | docsrc/xlisp/xlisp-doc/tutorials/binary-io.htm | 79 | ||||
| -rw-r--r-- | docsrc/xlisp/xlisp-doc/tutorials/environment.htm | 530 | ||||
| -rw-r--r-- | docsrc/xlisp/xlisp-doc/tutorials/file-io.htm | 349 | ||||
| -rw-r--r-- | docsrc/xlisp/xlisp-doc/tutorials/lisp-faq.htm | 199 | ||||
| -rw-r--r-- | docsrc/xlisp/xlisp-doc/tutorials/lisp-hints.htm | 2055 | ||||
| -rw-r--r-- | docsrc/xlisp/xlisp-doc/tutorials/nyquist.htm | 383 | ||||
| -rw-r--r-- | docsrc/xlisp/xlisp-doc/tutorials/shell-utilities.htm | 539 | ||||
| -rw-r--r-- | docsrc/xlisp/xlisp-doc/tutorials/tutorials.htm | 28 | ||||
| -rw-r--r-- | docsrc/xlisp/xlisp-doc/tutorials/xlisp-objects.htm | 839 | ||||
| -rw-r--r-- | docsrc/xlisp/xlisp-doc/tutorials/xobj-1.png | bin | 0 -> 1551 bytes |
10 files changed, 5001 insertions, 0 deletions
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 |
