diff options
Diffstat (limited to 'docsrc/xlisp/xlisp-doc/examples')
48 files changed, 11729 insertions, 0 deletions
diff --git a/docsrc/xlisp/xlisp-doc/examples/apropos.htm b/docsrc/xlisp/xlisp-doc/examples/apropos.htm new file mode 100644 index 0000000..f0657b2 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/apropos.htm @@ -0,0 +1,268 @@ +<html><head>
+
+<title>apropos</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>apropos</h1>
+
+<hr>
+
+
+
+<p><div class="box">
+
+<dl>
+
+<dt><p><nobr>(<b>apropos</b> &optional <i>pattern type</i>)</nobr></p></dt>
+
+<dd><p>The 'apropos' function searches the Nyquist/XLISP *obarray* for
+matching symbol names containing 'pattern' and being of 'type'. <nobr>It
+prints</nobr> a list of the results in alphabetical order.</p>
+
+<p>'pattern and 'type' can be given as symbols or strings. <nobr>If
+no</nobr> 'pattern' is given, all symbol names are considered as matching.
+<nobr>If no</nobr> 'type' is given, all symbol types are considered as
+matching. With 'type', only the first letter is important. <nobr>A
+type</nobr> of 'f' searches for symbols with a valid function value, while a
+type of 'v' searches for symbols with a valid variable value.</p></dd>
+
+</dd>
+
+</dl>
+
+</div></p>
+
+<p>Examples:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(apropos)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%"><nobr>all symbols known by Nyquist</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(apropos nil 'f)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%"><nobr>all bound functions known by Nyquist</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(apropos nil 'v)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%"><nobr>all bound variables known by Nyquist</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td valign="top">
+ <table cellpadding="0" cellspacing="0" width="100%"><tbody>
+ <tr valign="top">
+ <td class="button"><nobr><code>(apropos 'snd 'f)</code></nobr></td>
+ </tr>
+ </tbody></table>
+ </td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%"><nobr>all function names containing 'snd'</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>A method to introspect classes and objects:</p>
+
+<pre class="example">
+(setq instance-var '*wrong-variable*) ; value outside the object
+
+(setq my-class (send class :new '(instance-var))) ; class with instance variable
+(send my-class :answer :isnew '() '((setq instance-var '*OK*))) ; value inside an object
+(send my-class :answer :eval '(list) '((eval list))) ; evaluation method
+
+(setq my-object (send my-class :new)) ; instance of my-class
+(send my-object :eval 'instance-var) => <font color="#008844">*OK*</font>
+(send my-object :eval '(apropos 'instance-var 'v t)) => <font color="#AA0000">*WRONG-VARIABLE*</font>
+</pre>
+
+<p>The first version works because the call to 'eval' happens inside the
+object:</p>
+
+<pre class="example">
+(send my-class :answer :eval '(list) '((eval list))) => <font color="#008844">*OK*</font>
+</pre>
+
+<p>The second version doesn't work because the call to 'eval' happens
+outside the object:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">external-function</font> (list)
+ (eval list))
+
+(send my-class :answer :eval '(list) '((external-function list))) => <font color="#AA0000">*WRONG-VARIABLE*</font>
+</pre>
+
+<p>The call to 'apropos' doesn't work because 'apropos' is executed outside
+the object:</p>
+
+<pre class="example">
+(send my-object :eval '(apropos)) => <font color="#AA0000">*WRONG-VARIABLE*</font>
+</pre>
+
+<p>The trick is to pass the Lisp code of 'apropos' as a list into the inside
+of the object and 'apply' it there to the arguments:</p>
+
+<pre class="example">
+(send my-class :answer :apropos '(args)
+ '((apply (get-lambda-expression #'apropos) args)))
+
+(send my-object :apropos '(instance-var v t)) => <font color="#008844">*OK*</font>
+</pre>
+
+<p>But this only works if all function that need access to internal instance
+or class variables are executed inside the object. For example, if 'apropos'
+calls a function that needs access to an internal instance variable, I
+would get a 'unbound variable' error.</p>
+
+<p>Here is the code of the 'apropos' function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">apropos</font> (&optional pattern type)
+ (let (result-list (<font color="#AA5500">*gc-flag*</font> nil))
+ <font color="#008844">;; make sure 'pattern' is a string, either empty or upper-case</font>
+ (if pattern
+ (setf pattern (string-upcase (string pattern)))
+ (setf pattern <font color="#880000">""</font>))
+ <font color="#008844">;; take only the first letter of 'type' and make it an upper-case string</font>
+ (if type (setf type (string-upcase (subseq (string type) 0 1))))
+ <font color="#008844">;; go through all entries in the *obarray* symbol hash table</font>
+ (dotimes (i (length <font color="#AA5500">*obarray*</font>))
+ (let ((entry (aref <font color="#AA5500">*obarray*</font> i))) <font color="#008844">; *obarray* is an array of lists</font>
+ <font color="#008844">;; if the *obarray* entry is not an empty list</font>
+ (if entry
+ <font color="#008844">;; go through all elements of the *obarray* entry list</font>
+ <font color="#008844">;; do not use 'dolist' because *obarray* contains *unbound*</font>
+ (dotimes (j (length entry))
+ <font color="#008844">;; convert the symbol to a string to enable pattern matching</font>
+ (let ((string (string (nth j entry))))
+ <font color="#008844">;; if the symbol string matches the search pattern</font>
+ (if (string-search pattern string)
+ <font color="#008844">;; if a special symbol type to search for was given</font>
+ (if type
+ <font color="#008844">;; if a 'type' search was initiated and the current</font>
+ <font color="#008844">;; symbol has no 'type' value bound to it, do nothing</font>
+ <font color="#008844">;; and return from 'cond' without adding the symbol</font>
+ <font color="#008844">;; string to the result list</font>
+ (cond ((and (string= type <font color="#880000">"F"</font>) <font color="#008844">; bound functions only</font>
+ (not (fboundp (nth j entry))))
+ nil)
+ ((and (string= type <font color="#880000">"V"</font>) <font color="#008844">; bound variables only</font>
+ (not (boundp (nth j entry))))
+ nil)
+ <font color="#008844">;; if the symbol has passed all tests,</font>
+ <font color="#008844">;; add the symbol string to the result list</font>
+ (t (setf result-list (cons string result-list))))
+ <font color="#008844">;; if no special symbol type to search for had been given,</font>
+ <font color="#008844">;; but the symbol string had matched the search pattern,</font>
+ <font color="#008844">;; add the symbol string to the result list</font>
+ (setf result-list (cons string result-list)))))))))
+ <font color="#008844">;; if the result list contains more than one element</font>
+ <font color="#008844">;; make it become an alphabetically sorted list</font>
+ (if (> (length result-list) 1)
+ (setf result-list (sort result-list 'string<)))
+ <font color="#008844">;; print a message according to the search type and pattern</font>
+ (cond ((and type (string= type <font color="#880000">"F"</font>)) (setf type <font color="#880000">"function"</font>))
+ ((and type (string= type <font color="#880000">"V"</font>)) (setf type <font color="#880000">"variable"</font>))
+ (t (setf type <font color="#880000">"symbol"</font>)))
+ (if (string= pattern <font color="#880000">""</font>)
+ (format t <font color="#880000">"All ~a names known by Nyquist:~%"</font> type)
+ (format t <font color="#880000">"All ~a names containing pattern ~a:~%"</font> type pattern))
+ <font color="#008844">;; print the search results</font>
+ (cond (result-list
+ (let ((list-length (length result-list)))
+ (format t <font color="#880000">";; number of symbols: ~a~%"</font> list-length)
+ (dolist (i result-list) (format t <font color="#880000">"~a~%"</font> i))
+ (if (> list-length 20)
+ (format t <font color="#880000">";; number of symbols: ~a~%"</font> list-length))))
+ (t (format t <font color="#880000">"No matches found."</font>)))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/arrays.htm b/docsrc/xlisp/xlisp-doc/examples/arrays.htm new file mode 100644 index 0000000..6e258ff --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/arrays.htm @@ -0,0 +1,430 @@ +<html><head>
+
+<title>Arrays</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Arrays</h1>
+
+<hr>
+
+<p>Arrays are also <a href="sequences.htm">Sequences</a>.</p>
+
+<ul>
+<li><nobr><a href="#make-array-star">make-array*</a> - create multi-dimensional arrays</nobr></li>
+<li><nobr><a href="#aref-star">aref*</a> - access multi-dimensional-arrays</nobr></li>
+<li><nobr><a href="#vector-star">vector*</a> - make a one-dimensional array out of arbitrary Lisp expressions</nobr></li>
+<li><nobr><a href="#vector-star">array*</a> - make a multi-dimensional array out of arbitrary Lisp expressions</nobr></li>
+</ul>
+
+<a name="make-array-star"></a>
+
+<hr>
+
+<h2>make-array*</h2>
+
+<hr>
+
+<p>XLISP already has the
+<nobr><a href="../reference/make-array.htm">make-array</a></nobr>
+function to create <nobr>one-dimensional</nobr> arrays:</p>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<a href="../reference/make-array.htm">make-array</a> <i>size</i>)</nobr></dt>
+<dd><i>size</i> - the size [integer] of the array to be created<br>
+returns - the new array</dd>
+</dl>
+
+</div></p>
+
+<p>Here is a function to create <nobr>multi-dimensional</nobr> arrays:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>make-array*</b> <i>size-1</i> [<i>size-2</i> ...])</dt>
+<dd><i>sizeN</i> - the size [integer] of the <i>N</i>-th dimension in the array to be created<br>
+returns - the new array</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">make-array*</font> (&rest dimensions-list)
+ (cond ((null dimensions-list)
+ (error <font color="#880000">"too few arguments"</font>))
+ ((and (null (rest dimensions-list))
+ (eql 0 (first dimensions-list)))
+ (make-array 0))
+ (t (labels ((multi-vector (dimensions-list)
+ (let ((count (first dimensions-list)))
+ (if (not (and (integerp count) (plusp count)))
+ (error <font color="#880000">"not a positive integer"</font> count)
+ (let ((rest (rest dimensions-list))
+ (elements-list nil))
+ (dotimes (i count)
+ (push (when rest
+ (multi-vector rest))
+ elements-list))
+ (apply #'vector (reverse elements-list)))))))
+ (multi-vector dimensions-list)))))
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+(make-array* 2 3) => #(#(NIL NIL NIL) #(NIL NIL NIL)))
+(make-array* 2 2 1) => #(#(#(NIL) #(NIL)) #(#(NIL) #(NIL)))
+</pre>
+
+<p>Like <nobr><a href="../reference/make-array.htm">make-array</a></nobr> it
+is possible to create <nobr>one-dimensional</nobr> arrays with zero
+elements:</p>
+
+<pre class="example">
+(make-array* 0) => #()
+(make-array 0) => #()
+</pre>
+
+<p>But it is not allowed to create <nobr>multi-dimensional</nobr> arrays
+with <nobr>zero-size</nobr> dimensions:</p>
+
+<pre class="example">
+(make-array* 1 0 1) => <font color="#AA0000">error: not a positive integer - 0</font>
+</pre>
+
+<p><b>Rationale:</b> Multi-dimensional arrays are implemented as nested
+vectors and a <nobr>zero-element</nobr> vector cannot hold the vector for
+the subsequent dimension. <nobr>We would</nobr> need some additional
+administration overhead to keep the subsequent dimensions accessible, but
+this would break the compatibility to the <nobr>build-in</nobr> XLISP
+<a href="../reference/aref.htm">aref</a> function.</p>
+
+<p>More practical examples see 'aref*' below.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="aref-star"></a>
+
+<hr>
+
+<h2>aref*</h2>
+
+<hr>
+
+<p>XLISP already has the <a href="../reference/aref.htm">aref</a> function
+to access elements in one-dimensional arrays:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<a href="../reference/aref.htm">aref</a> <i>array dimension-1</i>)</dt>
+<dd><i>array</i> - one-dimensional array<br>
+<i>dimension-1</i> - element number in the first dimension<br>
+returns - the value of the array element</dd>
+</dl>
+
+</div></p>
+
+<p>Here is a macro for accessing elements in <nobr>multi-dimensional</nobr>
+arrays:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>aref*</b> <i>array dimension-1</i> [<i>dimension-2</i> ...])</dt>
+<dd><i>array</i> - any-dimensional array<br>
+<i>dimensionN</i> - element number in the <i>N</i>-th dimension<br>
+returns - the value of the array element</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">aref*</font> (array &rest index-list)
+ (labels ((multi-aref (array-name index-list)
+ (let ((index (first index-list)))
+ (if (not (integerp index))
+ (error <font color="#880000">"not an integer"</font> index)
+ (let ((rest (rest index-list))
+ (expansion-list (list 'aref)))
+ (push (if rest
+ (multi-aref array-name rest)
+ array-name)
+ expansion-list)
+ (push index expansion-list)
+ (reverse expansion-list))))))
+ (multi-aref `,array (reverse `,index-list))))
+</pre>
+
+<p>The symbols inside the <a href="../reference/labels.htm">labels</a> form
+do not leak into the expansion, so 'aref*' also works with array names like
+'array', '<nobr>array-name</nobr>' 'index', '<nobr>index-list</nobr>' or
+'<nobr>expansion-list</nobr>'. Also the values of local or global variables
+with these names are not changed.</p>
+
+<pre class="example">
+(macroexpand-1 '(aref* a 1 2 3)) => (aref (aref (aref a 1) 2) 3)
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+> (setq a (make-array* 2 3))
+#(#(NIL NIL NIL) #(NIL NIL NIL)))
+
+> (setf (aref* a 0 1) "hello")
+"hello"
+
+> a
+#(#(NIL "hello" NIL) #(NIL NIL NIL))
+
+> (aref* a 0 1)
+"hello"
+</pre>
+
+<p>'aref*' with only one 'dimension' argument behaves
+<nobr>like <a href="../reference/aref.htm">aref</a>:</nobr></p>
+
+<pre class="example">
+(aref* a 0) => #(NIL "hello" NIL)
+(aref a 0) => #(NIL "hello" NIL)
+
+(aref* (aref* a 0) 1) => "hello"
+(aref (aref a 0) 1) => "hello"
+
+(aref* a 0 1) => "hello"
+(aref a 0 1) => <font color="#AA0000">error: too many arguments</font>
+</pre>
+
+<p>'aref*' like <a href="../reference/aref.htm">aref</a> also works
+<nobr>with <a href="../reference/setf.htm">setf</a></nobr> to store
+values in <nobr>multi-dimensional</nobr> arrays:</p>
+
+<pre class="example">
+(setf (aref* (aref* a 0) 1) "1") => "1" <font color="#008844">; a => #(#(NIL "1" NIL) #(NIL NIL NIL)))</font>
+(setf (aref (aref a 0) 1) "2") => "2" <font color="#008844">; a => #(#(NIL "2" NIL) #(NIL NIL NIL)))</font>
+
+(setf (aref* 0 1) "3") => "3" <font color="#008844">; a => #(#(NIL "3" NIL) #(NIL NIL NIL)))</font>
+(setf (aref 0 1) "4") => <font color="#AA0000">error: too many arguments</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="vector-star"></a>
+
+<hr>
+
+<h2>vector*</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">vector*</font> (&rest items)
+ (if (null items)
+ (make-array 0)
+ (let* ((end (length items))
+ (result (make-array end)))
+ (if (> end 1)
+ (dotimes (index end) <font color="#008844">; more than one item</font>
+ (setf (aref result index)
+ (if (eq (nth index items) '*unbound*)
+ '*unbound*
+ (nth index items))))
+ (if (eq (first items) '*unbound*) <font color="#008844">; one item only</font>
+ (setf (aref result 0) '*unbound*)
+ (let ((item (first items)))
+ (case (type-of item)
+ (cons (let ((end (length item)))
+ (setq result (make-array end))
+ (dotimes (index end)
+ (setf (aref result index)
+ (if (eq (nth index item) '*unbound*)
+ '*unbound*
+ (nth index item))))))
+ (array (let ((end (length item)))
+ (setq result (make-array end))
+ (dotimes (index end)
+ (setf (aref result index)
+ (if (eq (aref item index) '*unbound*)
+ '*unbound*
+ (aref item index))))))
+ (string (let ((end (length item)))
+ (setq result (make-array end))
+ (dotimes (index end)
+ (setf (aref result index)
+ (char item index)))))
+ (t (setf (aref result 0) item))))))
+ result)))
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">list*</font> (&rest items)
+ (if (null items)
+ nil
+ (let* ((end (length items))
+ (result nil))
+ (labels ((push-element (element)
+ (if (member (type-of element) '(array cons string))
+ (setq result (append (reverse (list* element)) result))
+ (push element result))))
+ (dotimes (index end)
+ (if (eq (nth index items) '*unbound*)
+ (push '*unbound* result)
+ (let ((item (nth index items)))
+ (case (type-of item)
+ (nil (push item result))
+ (cons (let ((end (length item)))
+ (when (not (consp (last item))) (incf end))
+ (dotimes (index end)
+ (if (eq (nth index item) '*unbound*)
+ (push '*unbound* result)
+ (push-element (nth index item))))))
+ (array (let ((end (length item)))
+ (dotimes (index end)
+ (if (eq (aref item index) '*unbound*)
+ (push '*unbound* result)
+ (push-element (aref item index))))))
+ (string (let ((end (length item)))
+ (dotimes (index end)
+ (push (char item index) result))))
+ (t (push item result))))))
+ (reverse result)))))
+</pre>
+
+
+<pre class="example">
+(defun <font color="#0000CC">tree*</font> (&rest items)
+ (if (null items)
+ nil
+ (let* ((end (length items))
+ (result nil))
+ (labels ((push-element (element)
+ (if (member (type-of element) '(array cons string))
+ (push (reverse (list* element)) result)
+ (push element result))))
+ (dotimes (index end)
+ (if (eq (nth index items) '*unbound*)
+ (push '*unbound* result)
+ (let ((item (nth index items)))
+ (case (type-of item)
+ (nil (push item result))
+ (cons (let ((end (length item)))
+ (when (not (consp (last item))) (incf end))
+ (dotimes (index end)
+ (if (eq (nth index item) '*unbound*)
+ (push '*unbound* result)
+ (push-element (nth index item))))))
+ (array (let ((end (length item)))
+ (dotimes (index end)
+ (if (eq (aref item index) '*unbound*)
+ (push '*unbound* result)
+ (push-element (aref item index))))))
+ (string (let ((end (length item)))
+ (dotimes (index end)
+ (push (char item index) result))))
+ (t (push item result))))))
+ (reverse result)))))
+</pre>
+
+
+
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="array-star"></a>
+
+<hr>
+
+<h2>array*</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">array*</font> (&rest items)
+ (if (null items)
+ (make-array 0)
+ (let* ((end (length items))
+ (result (make-array end)))
+ (labels ((vector-element (element index)
+ (setf (aref result index)
+ (if (member (type-of element) '(cons string array))
+ (array* element)
+ element))))
+ (dotimes (index end)
+ (if (eq (nth index items) '*unbound*)
+ (setf (aref result index) '*unbound*)
+ (let ((item (nth index items)))
+ (case (type-of item)
+ (cons (let ((end (length item)))
+ (dotimes (index end)
+ (if (eq (nth index item) '*unbound*)
+ (strcat-element <font color="#880000">"*UNBOUND*"</font>)
+ (strcat-element (nth index item))))))
+ (array (let ((end (length item)))
+ (dotimes (index end)
+ (if (eq (aref item index) '*unbound*)
+ (strcat-element <font color="#880000">"*UNBOUND*"</font>)
+ (strcat-element (aref item index))))))
+ (t (strcat-element item))))))
+ result))))
+</pre>
+
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/binary.htm b/docsrc/xlisp/xlisp-doc/examples/binary.htm new file mode 100644 index 0000000..3ae5d56 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/binary.htm @@ -0,0 +1,160 @@ +<html><head>
+
+<title>Binary Integer Numbers</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Binary Integer Numbers</h1>
+
+<hr>
+
+<p>XLISP provides the <a href="../manual/xlisp.htm#binary">#b</a>
+<nobr>read-macro</nobr> for binary numbers:</p>
+
+<pre class="example">
+#b0 => 0 #b1000 => 8 #b100000 => 16
+#b1 => 1 #b1001 => 9 #b100001 => 17
+#b10 => 2 #b1010 => 10 #b100010 => 18
+#b11 => 3 #b1011 => 11 #b100011 => 19
+#b100 => 4 #b1100 => 12 #b100100 => 20
+#b101 => 5 #b1101 => 13 #b100101 => 21
+#b110 => 6 #b1110 => 14 #b100110 => 22
+#b111 => 7 #b1111 => 15 #b100111 => 23
+</pre>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>bin-string</b> <i>integer</i> [<i>all</i>])</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>all</i> - a boolean expression<br>
+returns - the <i>integer</i> in binary form as string</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">bin-string</font> (integer &optional all)
+ (if (integerp integer)
+ (let ((digits (or (dolist (bits '(16 32 64 128) nil)
+ (let ((fixnum (round (expt 2.0 (1- bits)))))
+ (and (plusp (1- fixnum))
+ (minusp fixnum)
+ (return bits))))
+ (error <font color="#880000">"integer limit not found"</font>)))
+ (string <font color="#880000">""</font>))
+ (dotimes (x digits)
+ (let ((digit (logand (round (expt 2.0 x)) integer)))
+ (setq string (strcat (if (zerop digit) <font color="#880000">"0" "1"</font>) string))))
+ (format nil <font color="#880000">"~a"</font> (if all string (string-left-trim <font color="#880000">"0"</font> string))))
+ (error <font color="#880000">"not an integer"</font> integer)))
+</pre>
+
+<p>The '<nobr>bin-string</nobr>' function converts the 'integer' argument
+into binary form and returns is as a string. <nobr>If the</nobr>
+optional 'all' argument is not given or
+<a href="../reference/nil.htm">NIL</a>, leading zeros are not included in
+the string. <nobr>If the</nobr> optional 'all' argument is
+<nobr>non-<a href="../reference/nil.htm">NIL</a></nobr>, all digits of the
+internal representation of the 'integer' argument, including leading zeros,
+are contained in the string. This is useful for debugging integer overflow
+and <nobr>bit-wise</nobr> functions.</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>bin</b> <i>integer</i> [<i>all</i>])</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>all</i> - a boolean expression<br>
+prints - the <i>integer</i> in binary form<br>
+returns - the <i>integer</i> argument</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">bin</font> (integer &optional all)
+ (if (integerp integer)
+ (format t <font color="#880000">"#b~a~%"</font> (bin-string integer all))
+ (format t <font color="#880000">";; not an integer~%"</font>))
+ integer)
+</pre>
+
+<p>The 'bin' function prints the 'integer' argument in binary form on
+the screen. Together with the
+<a href="../manual/xlisp.htm#binary">#b</a> <nobr>read-macro</nobr>
+this can be used for interactive binary computations.</p>
+
+<pre class="example">
+> (bin 12345678)
+#b101111000110000101001110
+12345678
+
+> (bin 12345678 :all)
+#b00000000101111000110000101001110
+12345678
+
+> (bin 1.2345678)
+;; not an integer
+1.2345678
+
+> (bin (logand #b1011 #b1101))
+#b1001
+9
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/circular-lists.htm b/docsrc/xlisp/xlisp-doc/examples/circular-lists.htm new file mode 100644 index 0000000..48d7cdf --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/circular-lists.htm @@ -0,0 +1,133 @@ +<html><head>
+
+<title>Circular Lists</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Circular Lists</h1>
+
+<hr>
+
+
+<hr>
+
+<h2>Known XLISP Problems with Circular Lists</h2>
+
+<hr>
+
+<p><b>Warning:</b> do <b>not</b> try this with XLISP:</p>
+
+<pre class="example">
+> (setq my-list (cons 'item nil)) <font color="#008844">; create a 1-item list</font>
+(ITEM)
+
+> (setf (cdr my-list) my-list)) <font color="#008844">; create the circle</font>
+ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM
+ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM
+ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM
+ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ITEM ...
+</pre>
+
+<p>If you're lucky you can <a href="../reference/break.htm">break</a> the
+loop. <nobr>If not</nobr>, then XLISP will print the ITEM forever.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="circular-nth"></a>
+
+<hr>
+
+<h2>c-nth</h2>
+
+<hr>
+
+<p>The '<nobr>c-nth</nobr>' macro accesses a linear list as if it were
+circular:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">c-nth</font> (index list)
+ `(nth ,(rem index (length list)) ,list))
+</pre>
+
+<p>Note that with every call to '<nobr>c-nth</nobr>', the length of the list
+will be computed again.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(c-nth 0 '(1 2 3)) => 1
+(c-nth 1 '(1 2 3)) => 2
+(c-nth 2 '(1 2 3)) => 3
+(c-nth 3 '(1 2 3)) => 1
+(c-nth 4 '(1 2 3)) => 2
+(c-nth 5 '(1 2 3)) => 3
+(c-nth 6 '(1 2 3)) => 1
+(c-nth 7 '(1 2 3)) => 2
+</pre>
+
+Because '<nobr>c-nth</nobr>' is a macro expanding into a regular
+<a href="../reference/nth.htm">nth</a> form, '<nobr>c-nth</nobr>' can be
+used <nobr>with <a href="../reference/setf.htm">setf</a></nobr>:
+
+<pre class="example">
+(setq lst '(1 2 3)) => (1 2 3)
+lst => (1 2 3)
+(setf (c-nth 4 lst) 'x) => X
+lst => (1 X 3)
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp.htm new file mode 100644 index 0000000..add5cc7 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp.htm @@ -0,0 +1,161 @@ +<html><head>
+
+<title>Common Lisp</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Where is the Nyquist Common Lisp Library?</h1>
+
+<hr>
+
+<p>Short answer - nowhere.</p>
+
+<p>Rationale:</p>
+
+<ol>
+
+<li><p>XLISP is a very simple Lisp. Many of the XLISP functions are just simple
+wrappers around the underlying <nobr>C functions</nobr>. This makes XLISP,
+as an interpreted language, run with reasonable speed. <nobr>The main</nobr>
+advantage of XLISP over <nobr>Common Lisp</nobr> is that XLISP is much
+smaller and therefore much easier to learn.</p></li>
+
+<li><p>The main trick of Nyquist is to use XLISP only in the initial setup
+phase, where the Lisp code is parsed, to <nobr>set-up</nobr> the
+<nobr>low-level</nobr> sound sample functions, written <nobr>in C</nobr>,
+not in Lisp.</p>
+
+<p><nobr>The Nyquist</nobr> <nobr>low-level</nobr> '<nobr>snd-...</nobr>'
+functions only look like Lisp functions, but they are direct wrappers around
+<nobr>C functions</nobr> and behave like that. They do not provide type
+contagion, instead they expect a correct number of arguments, given in
+correct order with correct data types, and if not given exactly as expected,
+chances are good that Nyquist will crash.</p>
+
+<p><nobr>In Nyquist</nobr>, <nobr>XLISP [slow]</nobr> is used to make sure
+that the <nobr>low-level</nobr> functions will be given the correct
+arguments, while the <nobr>low-level</nobr> sound sample functions after the
+initial setup phase will run in <nobr>high-speed C</nobr>, and not in Lisp
+anymore.</nobr></p></li>
+
+</ol>
+
+<p>Because the Nyquist <nobr>Common Lisp</nobr> functions are running in
+interpreted XLISP, they run slower than the <nobr>built-in</nobr> XLISP
+functions. Because many <nobr>Common Lisp</nobr> functions do extensive
+parsing and/or type checking on their arguments, they run many times
+slower than XLISP. That's why overloading Nyquist with an extensive
+<nobr>Common Lisp</nobr> layer makes not much sense.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<h2>But why did you write so many Common Lisp functions?</h2>
+
+<hr>
+
+<p>I usually work with <nobr>Common Lisp</nobr> for prototyping, so if I'm
+porting code from <nobr>Common Lisp</nobr> to Nyquist:</p>
+
+<ol>
+
+<li><p>I first copy the <nobr>Common Lisp</nobr> code together with the
+respective Nyquist <nobr>Common Lisp</nobr> functions from screen into a
+Nyquist lisp file to see if the <nobr>Common Lisp</nobr> code works with
+Nyquist <nobr>at all</nobr>. Many of the Nyquist <nobr>Common Lisp</nobr>
+functions have argument tests to help with error tracking.</p></li>
+
+<li><p>When the <nobr>Common Lisp</nobr> code works with Nyquist I start to
+strip out everything I don't need for the particular problem at hand, making
+the Nyquist code run faster. Because this second step is highly depending on
+the particular problem at hand, there probably never will be a general
+solution for this.</p></li>
+
+</ol>
+
+<p><div class="box">
+
+<p>I have tried to keep the functions as <nobr>self-contained</nobr> as
+possible, any dependencies to <nobr>non-Nyquist</nobr> functions are noted
+directly below the code.</p>
+
+</div></p>
+
+<p>There are many XLISP functions that behave exactly like their
+<nobr>Common Lisp</nobr> counterparts, so I haven't written extra functions
+for them.</p>
+
+<ul>
+
+<li><p>If you already know <nobr>Common Lisp</nobr> then the Nyquist
+<nobr>Common Lisp</nobr> functions may help to understand how XLISP
+works.</p></li>
+
+<li><p>If you still don't know <nobr>Common Lisp</nobr> and maybe one day
+you decide to learn more <nobr>about it</nobr>, then the Nyquist
+<nobr>Common Lisp</nobr> functions may save you from learning everything
+double.</p></li>
+
+</ul>
+
+<p>In either case you can use the Nyquist <nobr>Common Lisp</nobr> functions
+as a <nobr>grab-bag</nobr> for your own functions.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/ceiling.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/ceiling.htm new file mode 100644 index 0000000..a39f495 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/ceiling.htm @@ -0,0 +1,137 @@ +<html><head>
+
+<title>cl:ceiling</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:ceiling</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>ceiling</b></nobr> function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward positive infinity:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>ceiling</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of truncating the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the truncate operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:ceiling</font> (number &optional (divisor
+ (if (integerp number) 1 1.0)
+ divisor-p))
+ (let ((quotient
+ (cond ((and (not divisor-p) (integerp number)) number)
+ ((= number divisor) 1)
+ (t (let ((i-quotient (/ (truncate number) (truncate divisor)))
+ (f-quotient (/ (float number) divisor)))
+ (if (or (= i-quotient f-quotient) <font color="#008844">; integer result</font>
+ (not (plusp f-quotient)))
+ (truncate f-quotient)
+ (1+ (truncate f-quotient))))))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The <nobr>cl:<b>ceiling</b></nobr> function computes a quotient that has
+been truncated toward positive infinity. <nobr>That is</nobr>, the quotient
+represents the smallest mathematical integer that is not smaller than the
+mathematical result.</p>
+
+<p>The quotient is directly returned by the function, while a list:</p>
+
+<pre class="example">
+(quotient remainder)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a> is set to
+<a href="../../reference/t.htm"> T </a> to signal that
+<a href="multiple-values.htm">Multiple Values</a> are returned.</p>
+
+<nobr>See
+<a href="rounding-and-truncation.htm">Rounding and Truncation</a></nobr>
+for more details.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:ceiling 3.5) => 4 <font color="#008844">; *rslt* => ( 4 -0.5)</font>
+(cl:ceiling -3.5) => -3 <font color="#008844">; *rslt* => (-3 -0.5)</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/debug-mv.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/debug-mv.htm new file mode 100644 index 0000000..c61cb23 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/debug-mv.htm @@ -0,0 +1,110 @@ +<html><head>
+
+<title>cl:debug:mv</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:debug:mv</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>debug:mv</b></b></nobr> function can be used to debug
+multiple value expressions:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>debug:mv</b> <i>expr</i></dt>
+<dd><i>expr</i> - a Lisp expression, returning an arbitrary number of values<br>
+returns - the normal Lisp return value from evaluating <i>expr</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:debug:mv</font> (expr)
+ (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+ (let ((result (eval expr)))
+ (format t <font color="#880000">";; cl:*multiple-values* => ~a~%"</font> <font color="#AA5500">cl:*multiple-values*</font>)
+ (format t <font color="#880000">";; *rslt* => ~a~a~%"</font> <font color="#AA5500">*rslt*</font>
+ (if <font color="#AA5500">cl:*multiple-values*</font> <font color="#880000">"" " [invalid]"</font>))
+ result))
+</pre>
+
+<p>The <nobr>cl:<b>debug:mv</b></nobr> function first sets the
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>, then it
+evaluates the expression. After evaluation it prints the values of the
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+and <a href="../../reference/global-rslt.htm">*rslt*</a> variables and
+returns the normal Lisp return value from the evaluation.</p>
+
+<p>Example:</p>
+
+<pre class="example">
+> (cl:debug:mv '(cl:values 1 2 3))
+;; cl:*multiple-values* => T
+;; *rslt* => (1 2 3)
+1
+
+> (cl:debug:mv 1)
+;; cl:*multiple-values* => NIL
+;; *rslt* => (1 2 3) [invalid]
+1
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/equalp.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/equalp.htm new file mode 100644 index 0000000..14835c5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/equalp.htm @@ -0,0 +1,162 @@ +<html><head>
+
+<title>cl:equalp</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:equalp</h1>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>equalp</b> <i>expr1 expr2</i>)</dt>
+<dd><i>exprN</i> - arbitrary Lisp expressions<br>
+returns - <a href="t.htm"> T </a> if the expressions
+are structurally equal, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<p>Two expressions are 'equalp':</p>
+
+<ul>
+
+<li><p>If the expressions
+<nobr>are <a href="../../reference/equal.htm">equal</a></nobr>.</p></li>
+
+<li><p>If two numbers of arbitrary type <nobr>are
+<a href="../../reference/number-equal.htm"> = </a></nobr>.</p></li>
+
+<li><p>If two characters are
+<nobr><a href="../../reference/char-equal-i.htm">char-equal</a></nobr>.</p></li>
+
+<li><p>If two strings are <nobr><a
+href="../../reference/string-equal-i.htm">string-equal</a></nobr>.</p></li>
+
+<li><p>If the two <a href="../../reference/car.htm">car</a>s in conses are
+'equalp' and the two <a href="../../reference/cdr.htm">cdr</a>s in conses
+are 'equalp'.</p></li>
+
+<li><p>If two arrays have the same number of elements and dimensions, and
+the corresponding elements in all dimensions are 'equalp'.</p></li>
+
+</ul>
+
+<p>Note that only 'equalp' can compare arrays.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:equalp</font> (expr-1 expr-2)
+ (or (equal expr-1 expr-2)
+ (and (numberp expr-1) (numberp expr-2) (= expr-1 expr-2))
+ (let ((type (type-of expr-1)))
+ (when (eq type (type-of expr-2))
+ (case type
+ (character (char-equal expr-1 expr-2))
+ (string (string-equal expr-1 expr-2))
+ (cons (do ((x (first expr-1)
+ (if (consp expr-1) (first expr-1) expr-1))
+ (y (first expr-2)
+ (if (consp expr-2) (first expr-2) expr-2)))
+ ((or (null expr-1)
+ (null expr-2)
+ (not (equalp x y)))
+ (and (null expr-1)
+ (null expr-2)))
+ (setq expr-1 (and (consp expr-1) (rest expr-1))
+ expr-2 (and (consp expr-2) (rest expr-2)))))
+ (array (let ((end (length expr-1)))
+ (when (eql end (length expr-2))
+ (dotimes (index end t)
+ (and (not (equalp (aref expr-1 index)
+ (aref expr-2 index)))
+ (return nil)))))))))))
+</pre>
+
+<p><b>cons:</b> <a href="../../reference/do.htm">do</a> is used instead of
+recursion because XLISP has only two kilobytes stack size. <nobr>The
+(<a href="../../reference/consp.htm">consp</a> <i>expr</i>)</nobr> tests are
+necessary because in a dotted list the last
+<a href="../../reference/rest.htm">rest</a> element is not a cons.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:equalp 1 1.0) => T
+(cl:equalp #\a #\A) => T
+(cl:equalp "Abc" "aBc") => T
+(cl:equalp '(1 #\a "Abc") '(1.0 #\A "aBc")) => T
+(cl:equalp #(1 #\a "Abc") #(1.0 #\A "aBc")) => T
+</pre>
+
+<p>Nested expressions only match if the nesting matches:</p>
+
+<pre class="example">
+(cl:equalp '(1 <font color="#AA0000">(</font>2 3<font color="#AA0000">)</font>) '(1.0 <font color="#AA0000">(</font>2.0 3.0<font color="#AA0000">)</font>) => T
+(cl:equalp '(1 <font color="#AA0000">(</font>2 3<font color="#AA0000">)</font>) '(<font color="#AA0000">(</font>1.0 2.0<font color="#AA0000">)</font> 3.0) => NIL
+(cl:equalp '(<font color="#AA0000">(</font>1 2<font color="#AA0000">)</font> 3) '(<font color="#AA0000">(</font>1.0 2.0<font color="#AA0000">)</font> 3.0) => T
+(cl:equalp '(<font color="#AA0000">(</font>1 2<font color="#AA0000">)</font> 3) '(1.0 <font color="#AA0000">(</font>2.0 3.0<font color="#AA0000">)</font>) => NIL
+</pre>
+
+<p>A character does not match a string with the same character:</p>
+
+<pre class="example">
+(cl:equalp #\a "a") => NIL
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/exp.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/exp.htm new file mode 100644 index 0000000..707e28e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/exp.htm @@ -0,0 +1,92 @@ +<html><head>
+
+<title>cl:exp</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:exp</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>exp</b></nobr> function does the same as the
+Nyquist/XLISP <a href="../../reference/exp.htm">exp</a> function, but
+also accepts integer numbers as argument:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>exp</b> <i>power</i>)</dt>
+<dd><i>power</i> - an integer or floating-point number<br>
+returns - the result of <nobr>'e' [2.7128]</nobr> to the power of <i>power</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:exp</font> (x)
+ (exp (float x)))
+</pre>
+
+<p>See <a href="../../reference/defun.htm">defun</a>,
+<a href="../../reference/exp.htm">exp</a>,
+<a href="../../reference/float.htm">float</a>.</p>
+
+<p>The <nobr>cl:<b>exp</b></nobr> function computes <nobr>'e'
+[2.7128]</nobr> raised to the specified 'power' and returns the result as a
+<nobr>floating-point</nobr> number.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/expt.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/expt.htm new file mode 100644 index 0000000..05e95ea --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/expt.htm @@ -0,0 +1,105 @@ +<html><head>
+
+<title>cl:expt</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:expt</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>expt</b></nobr> function computes the result of 'x' to
+the power <nobr>of 'y'</nobr>:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>expt</b> <i>base power</i>)</dt>
+<dd><i>base</i> - the base<br>
+<i>power</i> - the exponent<br>
+returns - the result of <i>base</i> to the power of <i>power</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:expt</font> (x y)
+ (let ((power (expt (float x) y)))
+ (if (and (integerp x) (integerp y))
+ (round power)
+ power)))
+</pre>
+
+<p>See <a href="../reference/and.htm">and</a>,
+<a href="../reference/defun.htm">defun</a>,
+<a href="../reference/expt.htm">expt</a>,
+<a href="../reference/float.htm">float</a>,
+<nobr><a href="../reference/if.htm"> if </a></nobr>,
+<a href="../reference/integerp.htm">integerp</a>,
+<a href="../reference/let.htm">let</a>,
+<a href="../reference/power.htm">power</a>,
+<a href="../reference/round.htm">round</a>.</p>
+
+<p>The <nobr>cl:<b>expt</b></nobr> function accepts integer and floating
+point numbers as arguments. <nobr>If both</nobr> arguments are integer
+numbers, the result will be an integer number, <nobr>if one</nobr> or both
+arguments are <nobr>floating-point</nobr> numbers, the result will be a
+<nobr>floating-point</nobr> number. <nobr>In contrast</nobr> to the
+Nyquist/XLISP <a href="../../reference/expt.htm">expt</a> function, the
+'<nobr>cl:expt</nobr>' function accepts exactly two arguments.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/floor.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/floor.htm new file mode 100644 index 0000000..79e046c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/floor.htm @@ -0,0 +1,150 @@ +<html><head>
+
+<title>cl:floor</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:floor</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>floor</b></nobr> function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward negative infinity:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>floor</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of truncating the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the truncate operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:floor</font> (number &optional (divisor
+ (if (integerp number) 1 1.0)
+ divisor-p))
+ (let ((quotient
+ (cond ((and (not divisor-p) (integerp number)) number)
+ ((= number divisor) 1)
+ (t (let ((i-quotient (/ (truncate number) (truncate divisor)))
+ (f-quotient (/ (float number) divisor)))
+ (if (or (= i-quotient f-quotient) <font color="#008844">; integer result</font>
+ (not (minusp f-quotient)))
+ (truncate f-quotient)
+ (1- (truncate f-quotient))))))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The <nobr>cl:<b>floor</b></nobr> function computes a quotient that has
+been truncated toward negative infinity. <nobr>That is</nobr>, the quotient
+represents the largest mathematical integer that is not larger than the
+mathematical quotient.</p>
+
+<p>The quotient is directly returned by the function, while a list:</p>
+
+<pre class="example">
+(quotient remainder)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a> is set to
+<a href="../../reference/t.htm"> T </a> to signal that
+<a href="multiple-values.htm">Multiple Values</a> are returned.</p>
+
+<nobr>See
+<a href="rounding-and-truncation.htm">Rounding and Truncation</a></nobr>
+for more details.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:floor 3.5) => 3 <font color="#008844">; *rslt* => ( 3 0.5)</font>
+(cl:floor -3.5) => -4 <font color="#008844">; *rslt* => (-4 0.5)</font>
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr><a href="../../reference/rem.htm">rem</a> - remainder of an integer division</nobr></li>
+<li><nobr><a href="../../reference/round.htm">round</a> - round arbitrary numbers to integers</nobr></li>
+<li><nobr><a href="../../reference/truncate.htm">truncate</a> - truncate arbitrary numbers toward zero</nobr></li>
+<li><nobr><a href="mod.htm">cl:mod</a></nobr></li>
+<li><nobr><a href="rem.htm">cl:rem</a></nobr></li>
+<li><nobr><a href="round.htm">cl:round</a></nobr></li>
+<li><nobr><a href="truncate.htm">cl:truncate</a></nobr></li>
+<li><nobr><a href="ceiling.htm">cl:ceiling</a></nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/global-multiple-values.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/global-multiple-values.htm new file mode 100644 index 0000000..5ca1757 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/global-multiple-values.htm @@ -0,0 +1,142 @@ +<html><head>
+
+<title>cl:*multiple-values*</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:*multiple-values*</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>*multiple-values*</b></nobr> variable is used to signal
+if a function has returned multiple values:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>cl:<b>*multiple-values*</b></dt>
+<dd>returns - <a href="../../reference/t.htm"> T </a> if a
+function returned multiple values</dd>
+</dl>
+
+</div></p>
+
+<p>Test if a function has returned multiple values:</p>
+
+<pre class="example">
+(setf cl:*multiple-values* nil)
+(let ((result (function ...)))
+ (if cl:*multiple-values*
+ (do-something-with *rslt* ...)
+ (do-something-with result ...))
+ ... )
+</pre>
+
+<p>Do not use <nobr>cl:<b>*multiple-values*</b></nobr> with
+<a href="../../reference/let.htm">let</a> like this:</p>
+
+<pre class="example">
+(let ((cl:*multiple-values* nil)
+ (result (function ...)))
+ (if cl:*multiple-values*
+ (do-something-with *rslt* ...)
+ (do-something-with result ...))
+ ... )
+</pre>
+
+<p>This doesn't work because 'function' is evaluated in the global XLISP
+environment, where the lexical <a href="../../reference/let.htm">let</a>
+binding of the <nobr>cl:<b>*multiple-values*</b></nobr> variable does not
+exist, while the <a href="../../reference/if.htm"> if </a> form
+inside the <a href="../../reference/let.htm">let</a> form cannot see a
+global change of the <nobr>cl:<b>*multiple-values*</b></nobr> variable,
+because the global value is shadowed by the lexical
+<a href="../../reference/let.htm">let</a> binding.
+<nobr>See <a href="../environment.htm">Environment</a></nobr> for more
+details about variables.</p>
+
+<p>The XLISP <a href="../../reference/progv.htm">progv</a> special form can
+be used to encapsulate a multiple value call while automatically restoring
+the old values at the end like this:</p>
+
+<pre class="example">
+(values 1 2 3) => 1
+
+cl:*multiple-values* => T
+*rslt* => (1 2 3)
+
+(progv '(cl:*multiple-values* *rslt*) '(nil nil)
+ (let ((result (function ...)))
+ (if cl:*multiple-values*
+ (do-something-with *rslt* ...)
+ (do-something-with result ...))))
+
+cl:*multiple-values* => T
+*rslt* => (1 2 3)
+</pre>
+
+<p><div class="box">
+
+<p><b>Note:</b> All functions returning multiple values set
+<nobr>cl:<b>*multiple-values*</b></nobr> to
+<a href="../../reference/t.htm"> T </a>, but it's up to the
+Lisp programmer to reset the variable
+<nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>.</p>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/log.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/log.htm new file mode 100644 index 0000000..c7e5c5f --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/log.htm @@ -0,0 +1,95 @@ +<html><head>
+
+<title>cl:log</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:log</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>log</b></nobr> function does the same as the
+Nyquist/XLISP <a href="../../reference/log.htm">log</a> function, but also
+accepts integer numbers and has an optional 'base' argument:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>log</b> <i>number</i> [<i>base</i>])</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+<i>base</i> - an integer or floating-point number<br>
+returns - the the logarithm of <i>number</i> in base <i>base</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:log</font> (number &optional base)
+ (if base
+ (if (zerop base)
+ 0.0
+ (/ (log (float number)) (log (float base))))
+ (log (float number))))
+</pre>
+
+<p>The '<nobr>cl:log</nobr>' function returns the logarithm of 'number' in
+base 'base'. <nobr>If 'base'</nobr> is not supplied its value <nobr>is
+'e'</nobr>, the base of the natural logarithms. <nobr>If the</nobr> 'base'
+argument is zero, then 'cl:log' returns zero. <nobr>The result</nobr> is
+always a <nobr>floating-point</nobr> number.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/mod.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/mod.htm new file mode 100644 index 0000000..9454d4e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/mod.htm @@ -0,0 +1,97 @@ +<html><head>
+
+<title>cl:mod</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:mod</h1>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>mod</b> <i>number divisor</i>)</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+<i>divisor</i> - an integer or floating-point number<br>
+returns - the remainder of a <a href="#cl-floor">cl:floor</a> operation</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:mod</font> (number divisor)
+ (if (= (abs number) (abs divisor))
+ (if (and (integerp number) (integerp divisor)) 0 0.0)
+ (let* ((i-quotient (/ (truncate number) (truncate divisor)))
+ (f-quotient (/ (float number) divisor))
+ (quotient (if (or (= i-quotient f-quotient) <font color="#008844">; integer result</font>
+ (not (minusp f-quotient)))
+ (truncate f-quotient)
+ (1- (truncate f-quotient)))))
+ (- number (* quotient divisor)))))
+</pre>
+
+<p>The <nobr>cl:<b>mod</b></nobr> function performs the
+<a href="floor.htm">cl:floor</a> operation on its arguments and returns the
+remainder of the <a href="floor.htm">cl:floor</a> operation. <nobr>The
+result</nobr> is either zero or an integer or <nobr>floating-point</nobr>
+number with the same sign as the 'divisor' argument. <nobr>If both</nobr>
+arguments are integer numbers, the <nobr>cl:<b>mod</b></nobr> function is
+equal to the mathematical modulus function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-bind.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-bind.htm new file mode 100644 index 0000000..32fdadf --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-bind.htm @@ -0,0 +1,193 @@ +<html><head>
+
+<title>cl:multiple-value-bind</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:multiple-value-bind</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>multiple-value-bind</b></nobr> macro creates new bindings
+for a list of symbols and evaluates expressions that use these bindings:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>multiple-value-bind</b> <i>symbols values</i> [<i>expr1</i> ...])</dt>
+<dd><i>symbols</i> - a list of symbols<br>
+<i>values</i> - a Lisp expression returning one or more values<br>
+<i>exprN</i> - arbitrary Lisp expressions<br>
+returns - the value[s] returned by the last expression</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:multiple-value-bind</font> (symbols expr &rest body)
+ (and (or (not (consp symbols))
+ (eq 'quote (first symbols))
+ (dolist (symbol symbols)
+ (or (symbolp symbol) (return t))))
+ (error <font color="#880000">"not a list of symbols"</font> symbols))
+ (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+ (let* ((result (eval expr))
+ (values (if <font color="#AA5500">cl:*multiple-values*</font>
+ <font color="#AA5500">*rslt*</font>
+ (list result)))
+ (number-of-symbols (length symbols))
+ (number-of-values (length values))
+ (bindings nil))
+ (dotimes (index number-of-symbols)
+ (push (if (< index number-of-values)
+ (list (nth index symbols)
+ (list 'quote (nth index values)))
+ (nth index symbols))
+ bindings))
+ (setq bindings (reverse bindings))
+ `(let ,bindings ,@body)))
+</pre>
+
+<p>The 'values' expression is evaluated, and each of the symbols is bound to
+the respective value returned by the evaluation. <nobr>If there</nobr> are
+more symbols than values returned, extra values of
+<a href="../../reference/nilo.htm">NIL</a> are bound to the remaining
+symbols. <nobr>If there</nobr> are more values than symbols, the extra
+values are ignored. The symbols are bound to the values <nobr>by
+<a href="../../reference/let.htm">let</a></nobr>, behaving like an
+<nobr>implicit <a href="../../reference/progn.htm">progn</a></nobr>.</p>
+
+<p><nobr>Before evaluating 'expr1', the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable <nobr>is <a href="../../reference/t.htm"> T </a></nobr>
+if evaluating the 'values' expression returned multiple values and
+<a href="../../reference/nil.htm">NIL</a> with a normal return value.</p>
+
+<p>The <nobr>cl:<b>multiple-value-bind</b></nobr> macro binds multiple
+values to local <a href="../../reference/let.htm">let</a> variables::</p>
+
+<pre class="example">
+> (macroexpand-1 '(cl:multiple-value-bind (a b c)
+ (cl:values 1 2 3)
+ (list a b c)))
+(LET ((A (QUOTE 1))
+ (B (QUOTE 2))
+ (C (QUOTE 3)))
+ (LIST A B C))
+</pre>
+
+<p>The <a href="../../reference/quote.htm">quote</a>s are necessary to
+prevent 'unbound variable' and 'unbound function' errors with symbols and
+lists.</p>
+
+<p>Examples:</p>
+
+<p><b>1.</b> The <nobr>cl:<b>multiple-value-bind</b></nobr> macro binds
+values returned by the <a href="values.htm">cl:values</a> function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">multiple-value-function</font> ()
+ (cl:values 1 2 3)) <font color="#008844">; multiple return values</font>
+
+> (cl:multiple-value-bind (a b c)
+ (multiple-value-function)
+ (list a b c))
+(1 2 3)
+</pre>
+
+<p><b>2.</b> If there are no values returned in the Nyquist
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable, the normal
+function return value is bound to the first symbol and all remaining symbols
+are bound <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">normal-lisp-function</font> ()
+ (+ 1 1)) <font color="#008844">; normal return value</font>
+
+> (cl:multiple-value-bind (a b c)
+ (normal-lisp-function)
+ (list a b c))
+(2 NIL NIL)
+</pre>
+
+<p><b>3.</b> If there are less values than symbols, the extra symbols are
+bound <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">not-enough-values-function</font> ()
+ (cl:values 1 2)) <font color="#008844">; multiple return values</font>
+
+> (cl:multiple-value-bind (a b c)
+ (not-enough-values-function)
+ (list a b c))
+(1 2 NIL)
+</pre>
+
+<p><b>4.</b> If there are more values than symbols, the extra values are
+ignored:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">too-many-values-function</font> ()
+ (cl:values 1 2 3 4 5)) <font color="#008844">; multiple return values</font>
+
+> (cl:multiple-value-bind (a b c)
+ (too-many-values-function)
+ (list a b c))
+(1 2 3)
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-call.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-call.htm new file mode 100644 index 0000000..dba7c45 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-call.htm @@ -0,0 +1,119 @@ +<html><head>
+
+<title>cl:multiple-value-call</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:multiple-value-call</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>multiple-value-call</b></nobr> macro applies a function
+to a list of return values:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>multiple-value-call</b> <i>function</i> [<i>expr1</i> ...])</dt>
+<dd><i>function</i> - a Lisp expression evaluating to a function call<br>
+<i>exprN</i> - arbitrary Lisp expressions<br>
+returns - the values returned by the function</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:multiple-value-call</font> (function &rest exprs)
+ (let (args)
+ (dolist (expr exprs)
+ (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+ (let* ((result (eval expr)))
+ (if <font color="#AA5500">cl:*multiple-values*</font>
+ (dolist (rslt <font color="#AA5500">*rslt*</font>) (push rslt args))
+ (push result args))))
+ (setq args (reverse args))
+ `(progn
+ (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+ (apply ,function ',args)))
+</pre>
+
+<p>The <nobr>cl:<b>multiple-value-call</b></nobr> macro first evaluates the
+expressions and collects all return values in a single list, then the
+'function' form is evaluated and the resulting function call is applied to
+the list of values.</p>
+
+<p>Before applying the function to the list of values the
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable is set to <a href="../../reference/nil.htm">NIL</a>, the final value of
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+depends on the 'function' argument.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+> (funcall #'+
+ (cl:values 1 2)
+ (cl:values 3 4))
+4 <font color="#008844">; (apply #'+ (1 3))</font>
+
+> (cl:multiple-value-call #'+
+ (cl:values 1 2)
+ (cl:values 3 4))
+10 <font color="#008844">; (apply #'+ (1 2 3 4))</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-list.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-list.htm new file mode 100644 index 0000000..6e3a374 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-list.htm @@ -0,0 +1,112 @@ +<html><head>
+
+<title>cl:multiple-value-list</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:multiple-value-list</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>multiple-value-list</b></nobr> macro evaluates a Lisp
+expression and returns all values in a list:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>multiple-value-list</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - an arbitrary Lisp expression<br>
+returns - all values in a list</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:multiple-value-list</font> (expr)
+ (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+ (let ((result (eval expr)))
+ (if <font color="#AA5500">cl:*multiple-values*</font>
+ '<font color="#AA5500">*rslt*</font>
+ `(list ,result))))
+</pre>
+
+<p>The <nobr>cl:<b>multiple-value-list</b></nobr> macro first evaluates the
+expression. <nobr>If the</nobr> evaluation returned multiple values, the
+value of the <a href="../../reference/global-rslt.htm">*rslt*</a> variable
+is returned, otherwise the normal Lisp return value is returned in a list of
+one element.</p>
+
+<p><nobr>The
+<a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable <nobr>is <a href="../../reference/t.htm"> T </a></nobr>
+if evaluating the expression returns multiple values and
+<a href="../../reference/nil.htm">NIL</a> with a normal return value.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:multiple-value-list 1) => (1) <font color="#008844">; cl:*multiple-values* => NIL</font>
+ <font color="#008844">; *rslt* => [invalid]</font>
+(cl:multiple-value-list
+ (+ 1 1)) => (2) <font color="#008844">; cl:*multiple-values* => NIL</font>
+ <font color="#008844">; *rslt* => [invalid]</font>
+(cl:multiple-value-list
+ (cl:values 1 2 3)) => (1 2 3) <font color="#008844">; cl:*multiple-values* => T</font>
+ <font color="#008844">; *rslt* => (1 2 3)</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-prog1.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-prog1.htm new file mode 100644 index 0000000..d5f5fc6 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-prog1.htm @@ -0,0 +1,106 @@ +<html><head>
+
+<title>cl:multiple-value-prog1</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:multiple-value-prog1</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>multiple-value-prog1</b></nobr> macro is like
+<a href="../../reference/prog1.htm">prog1</a>, but it can handle multiple
+values:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>multiple-value-prog1</b> <i>expr1</i> [<i>expr2</i> ...])</dt>
+<dd><i>exprN</i> - arbitrary Lisp expressions<br>
+returns - the values returned by the first expression</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:multiple-value-prog1</font> (expr &rest body)
+ (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+ (let* ((result (eval expr)))
+ (if <font color="#AA5500">cl:*multiple-values*</font>
+ `(progn ,@body
+ (setq <font color="#AA5500">*rslt*</font> ',<font color="#AA5500">*rslt*</font>
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ ',result)
+ `(progn ,@body ',result))))
+</pre>
+
+<p>The <nobr>cl:<b>multiple-value-prog1</b></nobr> macro evaluates the first
+expression and saves all the values returned by the evaluation. <nobr>It
+then</nobr> evaluates each of the following expressions from left to right,
+discarding their values. After the evaluation is finished, the
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+and <a href="../../reference/global-rslt.htm">*rslt*</a> variables are
+restored and the primary value from evaluating the fist expression is
+returned.</p>
+
+<p><nobr>The
+<a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable <nobr>is <a href="../../reference/t.htm"> T </a></nobr>
+if evaluating the first expression returns multiple values and
+<a href="../../reference/nil.htm">NIL</a> with a normal return value.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-setq.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-setq.htm new file mode 100644 index 0000000..3a8b701 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-setq.htm @@ -0,0 +1,239 @@ +<html><head>
+
+<title>cl:multiple-value-setq</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:multiple-value-setq</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>multiple-value-setq</b></nobr> macro assigns multiple
+values to multiple variables:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>multiple-value-setq</b> <i>symbols expr</i>)</dt>
+<dd><i>symbols</i> - a list of symbols<br>
+<i>expr</i> - a Lisp expression returning one or more values<br>
+returns - the primary value returned by evaluating the expression</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:multiple-value-setq</font> (symbols expr)
+ (and (or (not (consp symbols))
+ (eq 'quote (first symbols))
+ (dolist (symbol symbols)
+ (or (symbolp symbol) (return t))))
+ (error <font color="#880000">"not a list of symbols"</font> symbols))
+ (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+ (let* ((result (eval expr))
+ (values (if <font color="#AA5500">cl:*multiple-values*</font>
+ <font color="#AA5500">*rslt*</font>
+ (list result)))
+ (number-of-symbols (length symbols))
+ (number-of-values (length values))
+ (assignments (list 'setq)))
+ (dotimes (index number-of-symbols)
+ (push (nth index symbols) assignments)
+ (push (when (< index number-of-values)
+ (list 'quote (nth index values)))
+ assignments))
+ (setq assignments (reverse assignments))
+ `(progn ,assignments ',result)))
+</pre>
+
+<p>The expression is evaluated, and each symbol is assigned to the
+corresponding value returned by the evaluation. <nobr>If there</nobr> are
+more symbols than values returned,
+<a href="../../reference/nil.htm">NIL</a> is assigned to the extra symbols.
+<nobr>If there</nobr> are more values than symbols, the extra values are
+discarded.</p>
+
+<p><nobr>The
+<a href="#cl-global-multiple-values">cl:*multiple-values*</a></nobr>
+variable <nobr>is <a href="../../reference/t.htm"> T </a></nobr>
+if evaluating the expression returns multiple values and
+<a href="../../reference/nil.htm">NIL</a> with a normal return value.</p>
+
+<p>The <nobr>cl:<b>multiple-value-setq</b></nobr> macro assigns multiple
+values to multiple variables
+<nobr>using <a href="../../reference/setq.htm">setq</a>:</nobr></p>
+
+<pre class="example">
+> (macroexpand-1 '(cl:multiple-value-setq (a b c)
+ (cl:values 1 2 3)))
+(PROGN (SETQ A (QUOTE 1)
+ B (QUOTE 2)
+ C (QUOTE 3))
+ (QUOTE 1))
+</pre>
+
+<p>The <a href="../../reference/quote.htm">quote</a>s are necessary to
+prevent 'unbound variable' and 'unbound function' errors with symbols and
+lists.</p>
+
+<p>Examples:</p>
+
+<p><b>1.</b> The <nobr>cl:<b>multiple-value-setq</b></nobr> macro assigns
+values returned by the <a href="values.htm">cl:values</a> function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">multiple-value-function</font> ()
+ (cl:values 1 2 3)) <font color="#008844">; multiple return values</font>
+
+> (let ((a 'A) (b 'B) (c 'C))
+ (cl:multiple-value-setq (a b c)
+ (multiple-value-function))
+ (list a b c))
+(1 2 3)
+</pre>
+
+<p><b>2.</b> If there are no values returned in the Nyquist
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable, the normal
+function return value is assigned to the first symbol and all remaining
+symbols are assigned
+<nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">normal-lisp-function</font> ()
+ (+ 1 1)) <font color="#008844">; normal return value</font>
+
+> (let ((a 'A) (b 'B) (c 'C))
+ (cl:multiple-value-setq (a b c)
+ (normal-lisp-function))
+ (list a b c))
+(2 NIL NIL)
+</pre>
+
+<p><b>3.</b> If there are less values than symbols, the extra symbols are
+assigned <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">not-enough-values-function</font> ()
+ (cl:values 1 2)) <font color="#008844">; multiple return values</font>
+
+> (let ((a 'A) (b 'B) (c 'C))
+ (cl:multiple-value-setq (a b c)
+ (not-enough-values-function))
+ (list a b c))
+(1 2 NIL)
+</pre>
+
+<p><b>4.</b> If there are more values than symbols, the extra values are
+ignored:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">too-many-values-function</font> ()
+ (cl:values 1 2 3 4 5)) <font color="#008844">; multiple return values</font>
+
+> (let ((a 'A) (b 'B) (c 'C))
+ (cl:multiple-value-setq (a b c)
+ (too-many-values-function))
+ (list a b c))
+(1 2 3)
+</pre>
+
+<p><b>5.</b> Symbols not contained in the
+<nobr>cl:<b>multiple-value-setq</b></nobr> <nobr>symbol-list</nobr> are not
+changed:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">multiple-value-function</font> ()
+ (cl:values 1 2 3)) <font color="#008844">; multiple return values</font>
+
+> (let ((a 'A) (b 'B) (c 'C) (d 'D) (e 'E))
+ (cl:multiple-value-setq (a b c)
+ (multiple-value-function))
+ (list a b c d e))
+(1 2 3 D E)
+</pre>
+
+<p><b>5.</b> If no bindings exist, new variables will be created:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">multiple-value-function</font> ()
+ (cl:values 1 2 3)) <font color="#008844">; multiple return values</font>
+
+> (let ((c 'C) (d 'D) (e 'E))
+ (cl:multiple-value-setq (a b c)
+ (multiple-value-function))
+ (list a b c d e))
+(1 2 3 D E)
+</pre>
+
+<p><b>Caution:</b> In the last example, two global variables 'a' and 'b'
+were created, while the lexical <a href="../../reference/let.htm">let</a>
+variable 'c' was assigned to the <nobr>value 3</nobr>:</p>
+
+<pre class="example">
+> (list a b)
+(1 2)
+
+> (list a b c)
+<font color="#AA0000">error: unbound variable - C</font>
+</pre>
+
+<p>The lexical <a href="../../reference/let.htm">let</a> binding of 'c' does
+not exist in the global <nobr>top-level</nobr>.
+<nobr>See <a href="../environment.htm">Environment</a></nobr> for more
+details about variables.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-values.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-values.htm new file mode 100644 index 0000000..d05df73 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-values.htm @@ -0,0 +1,181 @@ +<html><head>
+
+<title>Multiple Values</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Multiple Values</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#multiple-values">Multiple Values</a></nobr></li>
+<ul>
+<li><nobr>Nyquist/XLISP helpers</nobr></li>
+<ul>
+<li><nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a> - [Variable] - signals if a function has returned multiple values</nobr></li>
+<li><nobr><a href="debug-mv.htm">cl:debug:mv</a> - [Function] - debug multiple values</nobr></li>
+</ul>
+<li><nobr>Returning Multiple Values</nobr></li>
+<ul>
+<li><nobr><a href="values.htm">cl:values</a> - [Function] - return multiple values</nobr></li>
+<li><nobr><a href="values-list.htm">cl:values-list</a> - [Function] - return multiple values from a list</nobr></li>
+</ul>
+<li><nobr>Working with Multiple Values</nobr></li>
+<ul>
+<li><nobr><a href="multiple-value-list.htm">cl:multiple-value-list</a> - [Macro] - evaluate an expression and return all values in a list</nobr></li>
+<li><nobr><a href="multiple-value-bind.htm">cl:multiple-value-bind</a> - [Macro] - bind multiple values to multiple <a href="../reference/let.htm">let</a> variables</nobr></li>
+<li><nobr><a href="multiple-value-setq.htm">cl:multiple-value-setq</a> - [Macro] - assign multiple values to multiple variables using <a href="../reference/setq.htm">setq</a></nobr></li>
+<li><nobr><a href="multiple-value-prog1.htm">cl:multiple-value-prog1</a> - [Macro] - eveluate multiple expressions, return the values of the first expression</nobr></li>
+<li><nobr><a href="multiple-value-call.htm">cl:multiple-value-call</a> - [Macro] - apply a function to multiple values collected in a list</nobr></li>
+</ul>
+</ul>
+</ol>
+
+<a name="multiple-values"></a>
+
+<hr>
+
+<h2>Multiple Values</h2>
+
+<hr>
+
+<p>This is a port of the Common List framework for passing multiple values
+from one place to another. <nobr>It is</nobr> most often used to return
+multiple values from a function with
+<a href="values.htm">cl:values</a> or to bind multiple values to multiple
+variables with
+<nobr><a href="multiple-value-bind.htm">cl:multiple-value-bind</a></nobr> or
+<nobr><a href="multiple-value-setq.htm">cl:multiple-value-setq</a></nobr>.</p>
+
+<p>The multiple value functions and macros use the
+<nobr>Nyquist/XLISP</nobr>
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable to store the
+values as a list, while the
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable is used as a flag to indicate if a function has returned multiple
+values.</p>
+
+<p><b>What happens if a normal Lisp function are given multiple
+values?</b></p>
+
+<p>A normal Lisp function only sees the 'primary' return value, as returned
+by every Lisp function. <nobr>The additional</nobr> return values
+[including the primary return value] are stored in the
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and are only read
+by the multiple value functions. This also means that with multiple values,
+the most important value should always be returned as the first value,
+because only the first value can be seen by a normal Lisp function.
+<nobr>See <a href="values.htm">cl:values</a></nobr> for examples.</p>
+
+<p><b>What happens if a function expecting multiple values is given a normal
+Lisp return value?</b></p>
+
+<p>The first symbol will be set to the function's return value, while all
+other symbol will be set to <a href="../../reference/nil.htm">NIL</a>.
+<nobr>No symbol</nobr> will be left unset. <nobr>All functions</nobr>
+expecting multiple values are protected against a wrong number of values.
+<nobr>If there</nobr> are more symbols than values, then the extra symbols
+are set to <a href="../../reference/nil.htm">NIL</a>, if there are more
+values than symbols, the extra values will be ignored.</p>
+
+<p><div class="box">
+
+<p><b>Known Limitations</b></p>
+
+<p><b>1.</b> In Nyquist/XLISP, <a href="values.htm">cl:values</a> cannot be
+used as argument to <a href="../../reference/setf.htm">setf</a>. <nobr>But
+this</nobr> is not a real problem, because the values are stored as a
+simple list in the <a href="../../reference/global-rslt.htm">*rslt*</a>
+variable, where they can be manipulated with any arbitrary Lisp
+functions, not only <nobr>with
+<a href="../../reference/setf.htm">setf</a></nobr>.</p>
+
+<p><b>2.</b> In <nobr>Common Lisp</nobr> there exists the option to return
+<nobr>'no value</nobr>' by calling the 'values' function with no arguments.
+<nobr>In Nyquist/XLISP</nobr> there is no <nobr>built-in</nobr> way to
+return '<nobr>no value</nobr>' from a function. <nobr>The symbol</nobr>
+<a href="../../reference/global-unbound.htm">*unbound*</a> cannot be used for
+this because in <nobr>Common Lisp</nobr>, if '<nobr>no value</nobr>' is
+assigned to a symbol as variable value, the new value will be
+<a href="../../reference/nil.htm">NIL</a> and not
+<a href="../../reference/global-unbound.htm">*unbound*</a>.</p>
+
+<p>In Nyquist/XLISP, the <a href="values.htm">cl:values</a> function, if
+called with no arguments, always returns
+<a href="../../reference/nil.htm">NIL</a>, and the
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable will be
+set <nobr>to <a href="../../reference/nil.htm">NIL</a>, too:</nobr></p>
+
+<pre class="example">
+(cl:values) => NIL <font color="#008844">; *rslt* = NIL</font>
+(cl:values nil) => NIL <font color="#008844">; *rslt* = (NIL)</font>
+</pre>
+
+<p>Maybe this observation helps to write a '<nobr>no values</nobr>' test if
+anybody really <nobr>needs it</nobr>.</p>
+
+<p><b>3.</b> Neither in <nobr>Common Lisp</nobr> nor in Nyquist/XLISP is it
+possibe to return nested multiple values:</p>
+
+<pre class="example">
+(cl:values (1 (cl:values 2 3) 4) => 1 <font color="#008844">; *rslt* = (1 2 4)</font>
+</pre>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/numbers.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/numbers.htm new file mode 100644 index 0000000..d1b684c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/numbers.htm @@ -0,0 +1,104 @@ +<html><head>
+
+<title>Numbers</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Numbers</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#number-types">Number Types</a></nobr></li>
+<li><nobr><a href="#integer-limits">Integer Limits</a></nobr></li>
+</ol>
+
+<a name="number-types"></a>
+
+<hr>
+
+<h2>Number Types</h2>
+
+<hr>
+
+<p>In Nyquist/XLISP only two types of numers exist:</p>
+
+<ul>
+<li><nobr><b>fixnum</b> - integer numbers</nobr></li>
+<li><nobr><b>flonum</b> - floating-point numbers</nobr></li>
+</ul>
+
+<p>In Nyquist/XLISP, there are no ratios or complex numbers. Even if the
+math functions in this section are modelled after <nobr>Common Lisp</nobr>,
+no attempt is made to emulate these numbers.</p>
+
+<a name="integer-limits"></a>
+
+<hr>
+
+<h2>Integer Limits</h2>
+
+<hr>
+
+<pre class="example">
+(setq <font color="#AA5500">*most-positive-fixnum*</font> 2147483647)
+(setq <font color="#AA5500">*most-negative-fixnum*</font> -2147483648)
+</pre>
+
+<p><b>Note:</b> these are the limits for <nobr>32-bit</nobr> machines.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/rem.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/rem.htm new file mode 100644 index 0000000..aba20c5 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/rem.htm @@ -0,0 +1,93 @@ +<html><head>
+
+<title>cl:rem</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:rem</h1>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>rem</b> <i>number divisor</i>)</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+<i>divisor</i> - an integer or floating-point number<br>
+returns - the remainder of a <a href="cl-truncate">cl:truncate</a> operation</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:rem</font> (number divisor)
+ (if (= (abs number) (abs divisor))
+ (if (and (integerp number) (integerp divisor)) 0 0.0)
+ (let ((quotient (truncate (/ (float number) divisor))))
+ (- number (* quotient divisor)))))
+</pre>
+
+<p>The <nobr>cl:<b>rem</b></nobr> function performs the
+<a href="truncate.htm">cl:truncate</a> operation on its arguments and
+returns the remainder of the <a href="truncate.htm">cl:truncate</a>
+operation. <nobr>The result</nobr> is either zero or an integer or
+<nobr>floating-point</nobr> number with the same sign as the 'number'
+argument. <nobr>If both</nobr> arguments are integer numbers, the
+<nobr>cl:<b>rem</b></nobr> function is equal to the mathematical remainder
+function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/remainder-and-modulus.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/remainder-and-modulus.htm new file mode 100644 index 0000000..b7e89c4 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/remainder-and-modulus.htm @@ -0,0 +1,93 @@ +<html><head>
+
+<title>Remainder and Modulus</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Remainder and Modulus</h1>
+
+<hr>
+
+<p>The <a href="mod.htm">cl:mod</a> and <a href="rem.htm">cl:rem</a>
+function are generalizations of the modulus and remainder functions.</p>
+
+<ul>
+
+<li><p><nobr>The <a href="mod.htm">cl:mod</a></nobr> function performs the
+<a href="floor.htm">cl:floor</a> operation on its arguments and returns the
+remainder of the <a href="floor.htm">cl:floor</a> operation.</p></li>
+
+<li><p><nobr>The <a href="rem.htm">cl:rem</a></nobr> function performs the
+<a href="truncate.htm">cl:truncate</a> operation on its arguments and returns
+the remainder of the <a href="truncate.htm">cl:truncate</a> operation.</p></li>
+
+</ul>
+
+<p><nobr>The <a href="mod.htm">cl:mod</a></nobr> and
+<a href="rem.htm">cl:rem</a> functions are the modulus and remainder
+functions when the 'number' and 'divisor' arguments both are integers.</p>
+
+<pre class="example">
+(mod 13 4) => 1 (rem 13 4) => 1
+(mod -13 4) => 3 (rem -13 4) => -1
+(mod 13 -4) => -3 (rem 13 -4) => 1
+(mod -13 -4) => -1 (rem -13 -4) => -1
+(mod 13.4 1) => 0.4 (rem 13.4 1) => 0.4
+(mod -13.4 1) => 0.6 (rem -13.4 1) => -0.4
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/round.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/round.htm new file mode 100644 index 0000000..cf0be2c --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/round.htm @@ -0,0 +1,141 @@ +<html><head>
+
+<title>cl:round</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:round</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>round</b></nobr> function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward the next integer:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>round</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of runding the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the round operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:round</font> (number &optional (divisor
+ (if (integerp number) 1 1.0)
+ divisor-p))
+ (let* ((x (/ (float number) divisor))
+ (quotient (cond ((and (not divisor-p) (integerp number)) number)
+ ((= number divisor) 1)
+ ((plusp x) (truncate (+ x 0.5)))
+ ((= (- x 0.5) (truncate (- x 0.5)))
+ (if (minusp x)
+ (1- (truncate x))
+ (truncate x)))
+ (t (truncate (- x 0.5))))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The <nobr>cl:<b>round</b></nobr> function computes a quotient that has
+been rounded to the nearest mathematical integer. <nobr>If the</nobr>
+mathematical quotient is exactly halfway between two integers, [that is, it
+has the form <nobr>'integer+1/2']</nobr>, then the quotient has been rounded
+to the even [divisible <nobr>by two]</nobr> integer.</p>
+
+<p>The quotient is directly returned by the function, while a list:</p>
+
+<pre class="example">
+(quotient remainder)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a> is set to
+<a href="../../reference/t.htm"> T </a> to signal that
+<a href="multiple-values.htm">Multiple Values</a> are returned.</p>
+
+<nobr>See
+<a href="rounding-and-truncation.htm">Rounding and Truncation</a></nobr>
+for more details.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(round 3.5) => 4
+(round -3.5) => -3
+
+(cl:round 3.5) => 4 <font color="#008844">; *rslt* = ( 4 -0.5)</font>
+(cl:round -3.5) => -4 <font color="#008844">; *rslt* = (-4 0.5)</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/rounding-and-truncation.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/rounding-and-truncation.htm new file mode 100644 index 0000000..40eaebc --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/rounding-and-truncation.htm @@ -0,0 +1,179 @@ +<html><head>
+
+<title>Rounding and Truncation</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Rounding and Truncation</h1>
+
+<hr>
+
+<p>The <a href="round.htm">cl:round</a>,
+<a href="truncate.htm">cl:truncate</a>,
+<a href="ceiling.htm">cl:ceiling</a> and
+<a href="floor.htm">cl:floor</a> functions divide a number by a divisor,
+returning a quotient and a remainder:</p>
+
+<p><div class="box">
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="round.htm">cl:round</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="truncate.htm">cl:truncate</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="ceiling.htm">cl:ceiling</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="floor.htm">cl:floor</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+</tbody></table></p>
+
+<p><nobr>
+<i>quotient</i> * <i>divisor</i> + <i>remainder</i> = <i>number</i></nobr></p>
+
+</div></p>
+
+<p>The 'quotient' always represents a mathematical integer. <nobr>The
+'remainder'</nobr> is an integer if both 'number' and 'divisor' arguments
+are integers, and a <nobr>floating-point</nobr> number if either the
+'number' or the 'divisor' or both are <nobr>floating-point</nobr>
+numbers.</p>
+
+<p>With Nyquist/XLISP, the 'quotient' is always directly returned by the
+function, while a list:</p>
+
+<pre class="example">
+(<font color="#0000CC">quotient remainder</font>)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a> is set to
+<a href="../../reference/t.htm"> T </a> to signal that
+<a href="multiple-values.htm">Multiple Values</a> are returned.</p>
+
+Examples:
+
+<pre class="example">
+(cl:round 3.5) => 4 <font color="#008844">; *rslt* = ( 4 -0.5)</font>
+(cl:truncate 3.5) => 3 <font color="#008844">; *rslt* = ( 3 0.5)</font>
+(cl:ceiling 3.5) => 4 <font color="#008844">; *rslt* = ( 4 -0.5)</font>
+(cl:floor 3.5) => 3 <font color="#008844">; *rslt* = ( 3 0.5)</font>
+
+(cl:round -3.5) => -4 <font color="#008844">; *rslt* = (-4 0.5)</font>
+(cl:truncate -3.5) => -3 <font color="#008844">; *rslt* = (-3 -0.5)</font>
+(cl:ceiling -3.5) => -3 <font color="#008844">; *rslt* = (-3 -0.5)</font>
+(cl:floor -3.5) => -4 <font color="#008844">; *rslt* = (-4 0.5)</font>
+</pre>
+
+<p>Force an integer division:</p>
+
+<pre class="example">
+(cl:truncate 3.0 2.0) => 1 <font color="#008844">; Common Lisp</font>
+(/ (truncate 3.0) (truncate 2.0)) => 1 <font color="#008844">; Nyquist/XLISP</font>
+(/ 3 2) => 1 <font color="#008844">; integer division</font>
+</pre>
+
+<p><div class="box">
+
+<p><b>Implementation Notes</b></p>
+
+<pre class="example">
+(defun <font color="#0000CC">name</font> (number &optional (divisor (if (<font color="#AA0000">integerp</font> number) 1 1.0)))
+ ... )
+</pre>
+
+<p>The <a href="../../reference/integerp.htm">integerp</a> test in the
+parameter list signals an error if the 'number' argument is not a number,
+also the <nobr><a href="../../reference/division.htm"> / </a>
+[division]</nobr> function signals errors if the 'divisor' argument is zero
+or not a number, so we do not explicitely need to test the arguments.</p>
+
+<p>The <nobr><a href="ceiling.htm">cl:ceiling</a></nobr> and
+<nobr><a href="floor.htm">cl:floor</a></nobr> functions test if 'number' is
+an integer multiple of 'divisor' by comparing the results of an integer
+division and a <nobr>floating-point</nobr> division:</p>
+
+<pre class="example">
+(let ((<font color="#AA0000">i-quotient</font> (/ (truncate number) (truncate divisor)))
+ (<font color="#AA0000">f-quotient</font> (/ (float number) divisor)))
+ (if (= <font color="#AA0000">i-quotient f-quotient</font>)
+ ...
+</pre>
+
+<p>I'm not sure if this really catches all cases <nobr>[e.g.
+regarding</nobr> floating point precision], but have found no problems so
+far.</p>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/sqrt.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/sqrt.htm new file mode 100644 index 0000000..b430da3 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/sqrt.htm @@ -0,0 +1,92 @@ +<html><head>
+
+<title>cl:sqrt</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:sqrt</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>sqrt</b></nobr> function does the same as the
+Nyquist/XLISP <a href="../../reference/sqrt.htm">sqrt</a> function, but
+also accepts integer numbers as argument:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>sqrt</b> <i>number</i>)</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+returns - the square root of <i>number</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:sqrt</font> (x)
+ (sqrt (float x)))
+</pre>
+
+<p>See <a href="../../reference/defun.htm">defun</a>,
+<a href="../../reference/float.htm">float</a>,
+<a href="../../reference/sqrt.htm">sqrt</a>.</p>
+
+The <nobr>cl:<b>sqrt</b></nobr> function computes the square root of its
+argument and returns the result. as a <nobr>floating-point</nobr>
+number.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/truncate.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/truncate.htm new file mode 100644 index 0000000..6032dd3 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/truncate.htm @@ -0,0 +1,135 @@ +<html><head>
+
+<title>cl:truncate</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:truncate</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>truncate</b></nobr> function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward zero:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>truncate</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of truncating the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the truncate operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:truncate</font> (number &optional (divisor (if (integerp number) 1 1.0)))
+ (let ((quotient (truncate (/ (float number) divisor))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The <nobr>cl:<b>truncate</b></nobr> function computes a quotient that has
+been truncated towards zero. <nobr>That is</nobr>, the quotient represents
+the mathematical integer of the same sign as the mathematical quotient, and
+that has the greatest integral magnitude not greater than that of the
+mathematical quotient.</p>
+
+<p>The quotient is directly returned by the function, while a list:</p>
+
+<pre class="example">
+(quotient remainder)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a> is set to
+<a href="../../reference/t.htm"> T </a> to signal that
+<a href="multiple-values.htm">Multiple Values</a> are returned.</p>
+
+<nobr>See
+<a href="rounding-and-truncation.htm">Rounding and Truncation</a></nobr>
+for more details.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:truncate 3.5) => 0 <font color="#008844">; *rslt* => ( 3 0.5)</font>
+(cl:truncate -3.5) => -3 <font color="#008844">; *rslt* => (-3 -0.5)</font>
+</pre>
+
+<p>Force an integer division:</p>
+
+<pre class="example">
+(cl:truncate 3.1 2.6) => 1 <font color="#008844">; *rslt* => (1 0.5)</font>
+(/ 3 2) => 1
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/values-list.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/values-list.htm new file mode 100644 index 0000000..52fa6e6 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/values-list.htm @@ -0,0 +1,113 @@ +<html><head>
+
+<title>cl:values-list</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:values-list</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>values-list</b></nobr> function returns the elements of a
+list unevaluated as multiple values:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>values-list</b> <i>list</i>)</dt>
+<dd><i>list</i> - a list of values<br>
+returns - the elements of the list as multiple values</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:values-list</font> (list)
+ (or (listp list) (error <font color="#880000">"not a list"</font> list))
+ (or (null list) (consp (last list)) (error <font color="#880000">"not a proper list"</font> list))
+ (setq <font color="#AA5500">*rslt*</font> list
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ (first list))
+</pre>
+
+<p>The unevaluated first value from the list is returned as the primary
+return value, and the list is assigned to the Nyquist
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable. <nobr>If
+an</nobr> an empty list is given, <a href="../../reference/nil.htm">NIL</a>
+is returned and the <a href="../../reference/global-rslt.htm">*rslt*</a>
+variable is set <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>.
+<nobr>An error</nobr> is signalled if the 'list' argument is not a list or
+if the list does not end
+<nobr>with <a href="../../reference/nil.htm">NIL</a></nobr>.</p>
+
+<p><nobr>The
+<a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable is set <nobr>to
+<a href="../../reference/t.htm"> T </a></nobr> to indicate that
+multiple values are returned.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:values-list nil) => NIL <font color="#008844">; *rslt* = NIL</font>
+(cl:values-list '(1)) => 1 <font color="#008844">; *rslt* = (1)</font>
+(cl:values-list '(1 2)) => 1 <font color="#008844">; *rslt* = (1 2)</font>
+(cl:values-list '(1 2 3)) => 1 <font color="#008844">; *rslt* = (1 2 3)</font>
+(cl:values-list '(1 2 . 3)) => <font color="#AA0000">error: not a proper list - (1 2 . 3)</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/values.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/values.htm new file mode 100644 index 0000000..92a828e --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/values.htm @@ -0,0 +1,160 @@ +<html><head>
+
+<title>cl:values</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:values</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>values</b></nobr> function evaluates all given Lisp
+expressions and returns the results as multiple values:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>values</b> [<i>expr1</i> ...])</dt>
+<dd><i>exprN</i> - an arbitrary Lisp expression<br>
+returns - the results of evaluating the expressions, as multiple values</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:values</font> (&rest exprs)
+ (setq <font color="#AA5500">*rslt*</font> exprs
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ (first exprs))
+</pre>
+
+<p>The primary return value <nobr>[the result</nobr> from evaluating the
+first expression] is returned by the <nobr>cl:<b>values</b></nobr> function
+and a list with the results of evaluating all expressions is assigned to the
+Nyquist <a href="../../reference/global-rslt.htm">*rslt*</a> variable.
+<nobr>If no</nobr> expressions are given,
+<a href="..././reference/nil.htm">NIL</a> is returned and the
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable is set
+<nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>.</p>
+
+<p><nobr>The
+<a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable is set
+<nobr>to <a href="../../reference/t.htm"> T </a></nobr>
+to indicate that multiple values are returned.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:values 1 2 3) => 1 <font color="#008844">; primary value</font>
+*rslt* => (1 2 3) <font color="#008844">; all values</font>
+
+(cl:values 'a 'b) => A <font color="#008844">; primary value</font>
+*rslt* => (A B) <font color="#008844">; all values</font>
+
+> (cl:multiple-value-bind (a b c)
+ (cl:values 1 2 3)
+ (list a b c))
+(1 2 3)
+</pre>
+
+<p>See
+<nobr><a href="multiple-value-bind.htm">cl:multiple-value-bind</a></nobr>,
+<a href="../../reference/list.htm">list</a>,
+<a href="../../reference/global-rslt.htm">*rslt*</a>.</p>
+
+<p><div class="box">
+
+<p><b>Known Limitations</b></p>
+
+<p><b>1.</b> In Nyquist/XLISP, <nobr>cl:<b>values</b></nobr> cannot be
+used as argument to <a href="../../reference/setf.htm">setf</a>. <nobr>But
+this</nobr> is not a real problem, because the values are stored as a
+simple list in the <a href="../../reference/global-rslt.htm">*rslt*</a>
+variable, where they can be manipulated with any arbitrary Lisp
+functions, not only <nobr>with
+<a href="../../reference/setf.htm">setf</a></nobr>.</p>
+
+<p><b>2.</b> In <nobr>Common Lisp</nobr> there exists the option to return
+<nobr>'no value</nobr>' by calling the 'values' function with no arguments.
+<nobr>In Nyquist/XLISP</nobr> there is no <nobr>built-in</nobr> way to
+return '<nobr>no value</nobr>' from a function. <nobr>The symbol</nobr>
+<a href="../../reference/global-unbound.htm">*unbound*</a> cannot be used for
+this because in <nobr>Common Lisp</nobr>, if '<nobr>no value</nobr>' is
+assigned to a symbol as variable value, the new value will be
+<a href="../../reference/nil.htm">NIL</a> and not
+<a href="../../reference/global-unbound.htm">*unbound*</a>.</p>
+
+<p>In Nyquist/XLISP, the cl:<b>values</b> function, if called with no
+arguments, always returns <a href="../../reference/nil.htm">NIL</a>, and the
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable will be
+set <nobr>to <a href="../../reference/nil.htm">NIL</a>, too:</nobr></p>
+
+<pre class="example">
+(cl:values) => NIL <font color="#008844">; primary value</font>
+*rslt* => NIL <font color="#008844">; all values</font>
+
+(cl:values nil) => NIL <font color="#008844">; primary value</font>
+*rslt* => (NIL) <font color="#008844">; all values</font>
+</pre>
+
+<p>Maybe this observation helps to write a '<nobr>no values</nobr>' test if
+anybody really <nobr>needs it</nobr>.</p>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/environment.htm b/docsrc/xlisp/xlisp-doc/examples/environment.htm new file mode 100644 index 0000000..13a362d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/environment.htm @@ -0,0 +1,1001 @@ +<html><head>
+
+<title>Environment</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Environment</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#unbound">*unbound*</a></nobr></li>
+<li><nobr><a href="#lexical-environment">Lexical Environment</a></nobr></li>
+<ul>
+<li><nobr><a href="#getenv">getenv</a> - [Macro]</nobr></li>
+<li><nobr><a href="#eval-env">eval-env</a> - [Macro]</nobr></li>
+</ul>
+<li><nobr><a href="#lboundp">lboundp</a> - [Macro] - has this symbol a lexical variable value bound to it?</nobr></li>
+<ul>
+<li><nobr><a href="#valuep">valuep</a> - [Macro] - has this symbol a valid variable value bound to it?</nobr></li>
+</ul>
+<li><nobr><a href="#lfboundp">lfboundp</a> - [Macro] - has this symbol a lexical function value bound to it?</nobr></li>
+<li><nobr><a href="#lsymbol-value">lsymbol-value</a> - [Macro] - get the lexical variable value</nobr></li>
+<li><nobr><a href="#lsymbol-function">lsymbol-function</a> - [Macro] - get the lexical <a href="../reference/flet.htm">flet</a>, <a href="../reference/labels.htm">labels</a>, or <a href="../reference/macrolet.htm">macrolet</a> function value</nobr></li>
+<li><nobr><a href="#lmacroexpand-1">lmacroexpand-1</a> - [Macro] - expand the first level of a a <a href="../reference/macrolet.htm">macrolet</a> form</nobr></li>
+<li><nobr><a href="#known-problems">Known Problems</a></nobr></li>
+</ol>
+
+<a name="unbound"></a>
+
+<hr>
+
+<h2>*unbound*</h2>
+
+<hr>
+
+<p>A tricky problem with XLISP is that the symbol
+<a href="../reference/global-unbound.htm">*unbound*</a> can be bound as a
+value to any Lisp symbol, also to a lexical parameter variable if passed
+as a value to a Lisp function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">test</font> (x)
+ (print x))
+
+(test '*unbound*) => <font color="#880000">error: unbound variable</font>
+</pre>
+
+<p>The problem here is that the symbol
+<a href="../reference/global-unbound.htm">*unbound*</a> has been bound to
+the parameter variable 'x'</nobr>, so the expression <nobr>(print x)</nobr>
+instead of printing "*UNBOUND*" now causes an 'unbound variable'
+error. How can</nobr> I test from inside of a function if the lexical
+parameter variable 'x' is bound to the symbol
+<a href="../reference/global-unbound.htm">*unbound*</a>? Unfortunately there
+is no standard Lisp way to solve this problem.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="obarray"></a>
+
+<hr>
+
+<h2>*obarray*</h2>
+
+<hr>
+
+<p>A symbol in the *obarray* is protected from garbage collection.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lexical-environment"></a>
+
+<hr>
+
+<h2>Lexical Environment</h2>
+
+<hr>
+
+<p>Lisp parameter variables together with local variables bound with
+<a href="../reference/let.htm">let</a> and
+<a href="../reference/let-star.htm">let*</a> and functions defined by
+<a href="../reference/flet.htm">flet</a> and
+<a href="../reference/labels.htm">labels</a> are not interned in the
+<a href="../reference/global-obarray.htm">*obarray*</a>, instead they are
+stored in the local lexical environment, maintained via an internal
+association list. <nobr>The key</nobr> for reading this list is the
+<a href="../reference/global-evalhook.htm">*evalhook*</a> variable and the
+<a href="../reference/evalhook.htm">evalhook</a> function.</p>
+
+<p>Here are two Nyquist macros from 'evalenv.lsp':</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">getenv</font> () <font color="#008844">; return the current environment</font>
+ '(progv '(*evalhook*) (list #'(lambda (exp env) env))
+ (eval nil)))
+
+(defmacro <font color="#0000CC">eval-env</font> (arg) <font color="#008844">; evaluate in the current environment</font>
+ `(evalhook ,arg nil nil (getenv)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="getenv"></a>
+
+<hr>
+
+<h2>getenv</h2>
+
+<hr>
+
+<p>The 'getenv' macro returns the association list of the current lexical
+environment:</p>
+
+<pre class="example">
+(let ((<font color="#AA5500">v1</font> 1) <font color="#008844">; first variable</font>
+ (<font color="#AA5500">v2</font> 2)) <font color="#008844">; second variable</font>
+ (flet ((<font color="#0000CC">f1</font> (a) a) <font color="#008844">; first function</font>
+ (<font color="#0000CC">f2</font> (b) b)) <font color="#008844">; second function</font>
+ (getenv)))
+
+=> ((((<font color="#AA5500">V2</font> . <font color="#444444">1</font>) (<font color="#AA5500">V1</font> . <font color="#444444">2</font>))) ((<font color="#0000CC">F2</font> . <font color="#444444">#<Closure...></font>) (<font color="#0000CC">F1</font> . <font color="#444444">#<Closure...></font>)))
+</pre>
+
+<p>The asymmetric layout is produced by
+<a href="../reference/print.htm">print</a>, the real structure of the
+lexical environment is a <a href="../reference/cons.htm">cons</a> of two
+association lists:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">print-env</font> ()
+ (let ((env (gensym)))
+ `(let ((,env (getenv)))
+ (format t <font color="#880000">"(~s . ~s)~%"</font> (car ,env) (cdr ,env)))))
+</pre>
+
+<p><b>Note:</b> You could also use
+<a href="lists.htm#print-cons">print-cons</a> instead of
+<a href="../reference/format.htm">format</a> to print really all the
+details of the list, but <a href="../reference/format.htm">format</a> is
+enough for the examples here.</p>
+
+<pre class="example">
+(let ((<font color="#AA5500">v1</font> 1) <font color="#008844">; first variable</font>
+ (<font color="#AA5500">v2</font> 2)) <font color="#008844">; second variable</font>
+ (flet ((<font color="#0000CC">f1</font> (a) a) <font color="#008844">; first function</font>
+ (<font color="#0000CC">f2</font> (b) b)) <font color="#008844">; second function</font>
+ (print-env)))
+
+((((<font color="#AA5500">V2</font> . <font color="#444444">2</font>) (<font color="#AA5500">V1</font> . <font color="#444444">1</font>))) . (((<font color="#0000CC">F2</font> . <font color="#444444">#<Closure...></font>) (<font color="#0000CC">F1</font> . <font color="#444444">#<Closure...></font>))))
+</pre>
+
+<p>The basic <nobr>layout is</nobr>:</p>
+
+<pre class="example">
+((((<font color="#AA5500">V2</font> . value) (<font color="#AA5500">V1</font> . value))) . (((<font color="#0000CC">F2</font> . value) (<font color="#0000CC">F1</font> . value))))
+
+<font color="#444444">((<----- <font color="#AA5500">variable-list</font> ----->) . (<----- <font color="#0000CC">function-list</font> ----->))</font>
+
+(car (getenv)) => (<font color="#AA5500">variable-list</font>)
+(cdr (getenv)) => (<font color="#0000CC">function-list</font>)
+</pre>
+
+<p>The different levels of bindings are maintained via multiple
+sublists:</p>
+
+<pre class="example">
+(let ((<font color="#AA5500">v1</font> 1)) <font color="#008844">; first level variable</font>
+ (let ((<font color="#AA5500">v2</font> 2)) <font color="#008844">; second level variable</font>
+ (flet ((<font color="#0000CC">f1</font> (a) a)) <font color="#008844">; first level function</font>
+ (flet ((<font color="#0000CC">f2</font> (b) b)) <font color="#008844">; second level function</font>
+ (print-env)))))
+
+((((<font color="#AA5500">V2</font> . value)) ((<font color="#AA5500">V1</font> . value))) . (((<font color="#0000CC">F2</font> . value)) ((<font color="#0000CC">F1</font> . value))))
+
+<font color="#444444">(((<--<font color="#AA5500">level2</font>-->) (<--<font color="#AA5500">level1</font>-->)) . ((<--<font color="#0000CC">level2</font>-->) (<--<font color="#0000CC">level1</font>-->)))</font>
+<font color="#444444">((<------ <font color="#AA5500">variable-list</font> ------>) . (<------ <font color="#0000CC">function-list</font> ------>))</font>
+</pre>
+
+<p>Variables appear always in the variable list, functions always in the
+function list:</p>
+
+<pre class="example">
+(let ((<font color="#AA5500">v1</font> 1)) <font color="#008844">; first level variable</font>
+ (flet ((<font color="#0000CC">f1</font> (a) a)) <font color="#008844">; first level function</font>
+ (let ((<font color="#AA5500">v2</font> 2)) <font color="#008844">; second level variable</font>
+ (flet ((<font color="#0000CC">f2</font> (b) b)) <font color="#008844">; second level function</font>
+ (print-env)))))
+
+((((<font color="#AA5500">V2</font> . value)) ((<font color="#AA5500">V1</font> . value))) . (((<font color="#0000CC">F2</font> . value)) ((<font color="#0000CC">F1</font> . value))))
+
+<font color="#444444">(((<--<font color="#AA5500">level2</font>-->) (<--<font color="#AA5500">level1</font>-->)) . ((<--<font color="#0000CC">level2</font>-->) (<--<font color="#0000CC">level1</font>-->)))</font>
+<font color="#444444">((<------ <font color="#AA5500">variable-list</font> ------>) . (<------ <font color="#0000CC">function-list</font> ------>))</font>
+</pre>
+
+<p>The <nobr>inner-most</nobr> bindings always appear at the front of the
+lists:</p>
+
+<pre class="example">
+(let ((<font color="#AA5500">v1</font> 1)) <font color="#008844">; first level variable</font>
+ (let ((<font color="#AA5500">v2</font> 2)) <font color="#008844">; second level variable</font>
+ (flet ((<font color="#0000CC">f1</font> (a) a)) <font color="#008844">; first level function</font>
+ (flet ((<font color="#0000CC">f2</font> (b) b)) <font color="#008844">; second level function</font>
+ (let ((<font color="#AA5500">v3</font> 3)) <font color="#008844">; third level variable</font>
+ (print-env))))))
+
+((((<font color="#AA5500">V3</font> . value)) ((<font color="#AA5500">V2</font> . value)) ((<font color="#AA5500">V1</font> . value))) . (((<font color="#0000CC">F2</font> . value)) ((<font color="#0000CC">F1</font> . value))))
+
+<font color="#444444">(((<--<font color="#AA5500">level3</font>-->) (<--<font color="#AA5500">level2</font>-->) (<--<font color="#AA5500">level1</font>-->)) . ((<--<font color="#0000CC">level2</font>-->) (<--<font color="#0000CC">level1</font>-->)))</font>
+<font color="#444444">((<------------- <font color="#AA5500">variable-list</font> -------------->) . (<------ <font color="#0000CC">function-list</font> ------>))</font>
+</pre>
+
+<p>There may appear several variable bindings in the same sublist:</p>
+
+<pre class="example">
+(let ((<font color="#AA5500">v1</font> 1) (<font color="#AA5500">v2</font> 2)) <font color="#008844">; first level variables</font>
+ (flet ((<font color="#0000CC">f1</font> (a) a) <font color="#008844">; first level functions</font>
+ (<font color="#0000CC">f2</font> (b) b))
+ (let ((<font color="#AA5500">v3</font> 3)) <font color="#008844">; second level variable</font>
+ (print-env))))
+
+((((V3 . value)) ((V2 . value) (V1 . value))) . (((F2 . value) (F1 . value))))
+
+<font color="#444444">(((<--<font color="#AA5500">level2</font>-->) (<--------<font color="#AA5500">level1</font>--------->)) . ((<---------<font color="#0000CC">level1</font>-------->)))</font>
+<font color="#444444">((<------------ <font color="#AA5500">variable-list</font> ------------->) . (<----- <font color="#0000CC">function-list</font> ----->))</font>
+</pre>
+
+<p>The basic principle is always the same:</p>
+
+<pre class="example">
+(((<font color="#AA5500">level n</font> <font color="#008844">...</font>) <font color="#008844">...</font> (<font color="#AA5500">level 1 variables</font>)) . ((<font color="#0000CC">level n</font> <font color="#008844">...</font>) <font color="#008844">...</font> (<font color="#0000CC">level 1 functions</font>)))
+
+(car (getenv)) => ((<font color="#AA5500">level n</font> <font color="#008844">...</font>) (<font color="#AA5500">level n-1</font> <font color="#008844">...</font>) <font color="#008844">...</font> (<font color="#AA5500">level 1 variables</font>))
+(cdr (getenv)) => ((<font color="#0000CC">level n</font> <font color="#008844">...</font>) (<font color="#0000CC">level n-1</font> <font color="#008844">...</font>) <font color="#008844">...</font> (<font color="#0000CC">level 1 functions</font>))
+</pre>
+
+<p>Also the function parameter variables appear in the the lexical
+environment association list:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">test</font> (<font color="#AA0000">parameter-var</font>)
+ (let ((<font color="#AA5500">local-var</font> 'value))
+ (print-env)))
+
+((((<font color="#AA5500">LOCAL-VAR</font> . value)) ((<font color="#AA0000">PARAMETER-VAR</font> . value))) . NIL) <font color="#008844">; NIL = no functions</font>
+
+<font color="#444444">(((<-----<font color="#AA5500">level2</font>------>) (<-------<font color="#AA5500">level1</font>-------->)) . NIL)</font>
+<font color="#444444">((<--------------- <font color="#AA5500">variable-list</font> --------------->) . NIL)</font>
+</pre>
+
+<p>The variables bound by <a href="../reference/let.htm">let</a> appear
+before the function's parameter variables, that's why
+<a href="../reference/let.htm">let</a> bindings 'shadow' parameter variables
+with the same name. <nobr>The 'test'</nobr> function name does not appear in
+the environment list because the function name was
+<a href="../reference/intern.htm">intern</a>ed in the
+<a href="../reference/global-obarray.htm">*obarray*</a> by
+<a href="../reference/defun.htm">defun</a>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="eval-env"></a>
+
+<hr>
+
+<h2>eval-env</h2>
+
+<hr>
+
+<p>This still doen't work:</p>
+
+<pre class="example">
+(setq x 'global) ; define a global variable 'x'
+
+(defun print-x () ; define a function PRINT-X in the global environment
+ (print (getenv)) ; always prints ((NIL)), also with EVAL-ENV or EVALHOOK
+ (print x)) ; always prints GLOBAL, also with EVAL-ENV or EVALHOOK
+
+(let ((x 'local)) ; create a lexical variable 'x'
+ (print-x)) ; evaluate PRINT-X
+=> GLOBAL ; value from the environment, where PRINT-X was defined
+
+(let ((x 'local)) ; create a lexical variable 'x'
+ (eval-env (print-x)) ; evaluate PRINT-X in the current environment
+=> GLOBAL ;wrong ; value from the environment, where PRINT-X was called
+
+(let ((x 'local)) ; create a lexical variable 'x'
+ (eval-env (funcall 'print-x)) ; evaluate PRINT-X in the current environment
+=> GLOBAL ;wrong ; value from the environment, where PRINT-X was called
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lboundp"></a>
+
+<hr>
+
+<h2>lboundp</h2>
+
+<hr>
+
+<p>The 'lboundp' function tests if a valid variable value is bound to a
+symbol in the current lexical environment:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>lboundp</b> <i>symbol</i>)</dt>
+<dd><i>symbol</i> - a quoted lisp symbol<br>
+returns - <a href="../reference/t.htm"> T </a> if a lexical
+variable value is bound to the symbol, <a href="../reference/nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">lboundp</font> (symbol)
+ (cond ((not (or (symbolp symbol)
+ (and (consp symbol)
+ (eq 'quote (car symbol))
+ (symbolp (cadr symbol)))))
+ (error <font color="#880000">"bad argument type"</font> symbol))
+ ((and (consp symbol) (cddr symbol))
+ (error <font color="#880000">"too many arguments"</font>))
+ (t (let ((a-cons (gensym)) (level (gensym)) (binding (gensym)))
+ `(let ((,a-cons (dolist (,level (car (getenv)) nil)
+ (let ((,binding (assoc ,symbol ,level)))
+ (when ,binding (return ,binding))))))
+ (and ,a-cons (not (eq (cdr ,a-cons) '<font color="#AA5500">*unbound*</font>))))))))
+</pre>
+
+<p>The XLISP <a href="../reference/boundp.htm">boundp</a> function only
+can test global variables, interned in the
+<a href="../reference/global-obarray.htm">*obarray*</a>, so it cannot be
+used to test if a symbol has a variable value bound to it in the lexical
+environment:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">test</font> (x) <font color="#008844">; bad example</font>
+ (if (boundp 'x) <font color="#AA0000">; <- global test</font>
+ (print x)
+ (print '*unbound*)))
+
+(test 'hello!) => *UNBOUND* <font color="#AA0000">; bad result</font>
+(test 123) => *UNBOUND* <font color="#AA0000">; bad result</font>
+
+(setq x t) => T <font color="#008844">; create a global variable 'x'</font>
+
+(test 'hello!) => 'HELLO! <font color="#008844">; OK</font>
+(test 123) => 123 <font color="#008844">; OK</font>
+(test '*unbound*) => <font color="#AA0000">error: unbound variable - X ; bad result</font>
+</pre>
+
+<p>Here the same example with 'lboundp':</p>
+
+<pre class="example">
+(defun <font color="#0000CC">test</font> (x) <font color="#008844">; good example</font>
+ (if (lboundp 'x) <font color="#008844">; <- local test</font>
+ (print x)
+ (print '*unbound*)))
+
+(test 'hello!) => 'HELLO! <font color="#008844">; OK</font>
+(test 123) => 123 <font color="#008844">; OK</font>
+(test '*unbound*) => *UNBOUND* <font color="#008844">; OK</font>
+</pre>
+
+<p>The 'lboundp' function cannot test symbol values at the
+<nobr>top-level</nobr>, because there is no lexical environment:</p>
+
+<pre class="example">
+(setq x t) => T <font color="#008844">; create a global variable 'x'</font>
+(lboundp 'x) => NIL <font color="#AA0000">; lexical test fails</font>
+(boundp 'x) => T <font color="#008844">; global test succeeds</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="valuep"></a>
+
+<hr>
+
+<h2>valuep</h2>
+
+<hr>
+
+<p>The 'valuep' function tests if a valid variable value is bound to a
+symbol at any level:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">valuep</font> (symbol)
+ (cond ((not (or (symbolp symbol)
+ (and (consp symbol)
+ (eq 'quote (car symbol))
+ (symbolp (cadr symbol)))))
+ (error <font color="#880000">"bad argument type"</font> ,symbol))
+ ((and (consp symbol) (cddr symbol))
+ (error <font color="#880000">"too many arguments"</font>))
+ (t (let ((a-cons (gensym)) (level (gensym)) (binding (gensym)))
+ `(let ((,a-cons (dolist (,level (car (getenv)) nil)
+ (let ((,binding (assoc ,symbol ,level)))
+ (when ,binding (return ,binding))))))
+ (if ,a-cons
+ (not (eq (cdr ,a-cons) '<font color="#AA5500">*unbound*</font>))
+ (boundp ,symbol)))))))
+</pre>
+
+<p>It's tricky to test if a symbol has a valid variable value bound to
+it because if the symbol is bound to
+<a href="../reference/global-unbound.htm">*unbound*</a> in a lexical
+environment, it still shadows a symbol with the same name in the
+<a href="../reference/global-obarray.htm">*obarray*</a>, making a possibly
+existing global variable inaccessible, like shown in the examples
+below.</p>
+
+<p><b>Note:</b> The lexical environment must be tested first, because this
+is the way how XLISP searches for symbol bindings.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(when (valuep 'x) x) => NIL <font color="#008844">; no global binding of 'x' found</font>
+(setq x 'ok) => OK <font color="#008844">; create a global variable 'x'</font>
+(when (valuep 'x) x) => OK <font color="#008844">; global binding of 'x' found</font>
+
+(let ((x 'local)) <font color="#008844">; create a lexical variable 'x'</font>
+ (when (valuep 'x) x)) <font color="#008844">; try to access the lexical variable</font>
+=> LOCAL <font color="#008844">; lexical binding of 'x' found</font>
+</pre>
+
+<p>XLISP problems with
+<a href="../reference/global-unbound.htm">*unbound*</a>
+lexical variables:</p>
+
+<pre class="example">
+(setq x 'ok) => OK <font color="#008844">; create a global variable 'x'</font>
+(when (valuep 'x) x) => OK <font color="#008844">; global binding of 'x' found</font>
+
+(let ((x '*unbound*)) <font color="#008844">; create an unbound lexical variable 'x'</font>
+ (when (valuep 'x) x)) <font color="#008844">; try to access the global variable</font>
+=> <font color="#AA0000">NIL ; global binding of 'x' NOT found</font>
+
+(let ((x '*unbound*)) <font color="#008844">; create an unbound lexical variable 'x'</font>
+ x) <font color="#008844">; try to access the global variable</font>
+<font color="#AA0000">error: unbound variable - X</font>
+</pre>
+
+<p>The 'valuep' function recognizes if a global variable value is shadowed
+by an <a href="../reference/global-unbound.htm">*unbound*</a> lexical
+variable and returns NIL if the global variable is inaccessible..</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lfboundp"></a>
+
+<hr>
+
+<h2>lfboundp</h2>
+
+<hr>
+
+<p>The 'lfboundp' function tests if a valid function value is bound to a
+symbol in the current lexical environment:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>lfboundp</b> <i>symbol</i>)</dt>
+<dd><i>symbol</i> - a quoted lisp symbol<br>
+returns - <a href="../reference/t.htm"> T </a> if a lexical
+function value is bound to the symbol, <a href="../reference/nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">lfboundp</font> (symbol)
+ (cond ((not (or (symbolp symbol)
+ (and (consp symbol)
+ (eq 'quote (car symbol))
+ (symbolp (cadr symbol)))))
+ (error <font color="#880000">"bad argument type"</font> symbol))
+ ((and (consp symbol) (cddr symbol))
+ (error <font color="#880000">"too many arguments"</font>))
+ (t (let ((a-cons (gensym)) (level (gensym)) (binding (gensym)))
+ `(let ((,a-cons (dolist (,level (cdr (getenv)) nil)
+ (let ((,binding (assoc ,symbol ,level)))
+ (when ,binding (return ,binding))))))
+ (and ,a-cons (not (eq (cdr ,a-cons) '<font color="#AA5500">*unbound*</font>))))))))
+</pre>
+
+<p>The XLISP <a href="../reference/fboundp.htm">fboundp</a> function only
+works with symbols interned in the
+<a href="../reference/global-obarray.htm">*obarray*</a>, so it cannot be
+used to test if a symbol has a function value bound to it in the lexical
+environment:</p>
+
+<pre class="example">
+(flet ((my-function (x) 'hello))
+ (fboundp 'my-function)) <font color="#AA0000">; <- global test</font>
+=> NIL
+
+(flet ((my-function (x) 'hello))
+ (lfboundp 'my-function)) <font color="#008844">; <- local test</font>
+=> T
+</pre>
+
+<p>The 'lfboundp' function cannot test symbol function values at the
+<nobr>top-level</nobr>, because there is no lexical environment:</p>
+
+<pre class="example">
+(lfboundp 'car) => NIL <font color="#AA0000">; lexical test fails</font>
+(fboundp 'car) => T <font color="#008844">; global test succeeds</font>
+</pre>
+
+<p>Problems with <a href="../reference/global-unbound.htm">*unbound*</a>
+lexical functions are less likely then with
+<a href="../reference/global-unbound.htm">*unbound*</a> parameter
+variables, because there is no <nobr>buit-in</nobr> way to bind a lexical
+function to <a href="../reference/global-unbound.htm">*unbound*</a>.</p>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr><a href="predicates.htm#subrp">suprp</a> - is this a built-in function?</nobr></li>
+<li><nobr><a href="predicates.htm#fsubrp">fsubrp</a> - is this a built-in special form?</nobr></li>
+<li><nobr><a href="predicates.htm#closurep">closurep</a> - is this a user-defined function or macro?</nobr></li>
+<li><nobr><a href="predicates.htm#functionp">functionp</a> - is this a build-in or a user-defined function?</nobr></li>
+<li><nobr><a href="predicates.htm#macrop">macrop</a> - is this a user-defined macro?</nobr></li>
+</ul>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lsymbol-value"></a>
+
+<hr>
+
+<h2>lsymbol-value</h2>
+
+<hr>
+
+<p>The function 'lsymbol-value' returns a variable value from the lexical
+environment:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">lsymbol-value</font> (symbol)
+ (cond ((not (or (symbolp symbol)
+ (and (consp symbol)
+ (eq 'quote (car symbol))
+ (symbolp (cadr symbol)))))
+ (error <font color="#880000">"bad argument type"</font> symbol))
+ ((and (consp ,symbol) (cddr symbol))
+ (error <font color="#880000">"too many arguments"</font>))
+ (t (let ((a-cons (gensym)) (level (gensym)) (binding (gensym)))
+ `(let ((,a-cons (dolist (,level (car (getenv)) nil)
+ (let ((,binding (assoc ,symbol ,level)))
+ (when ,binding (return ,binding))))))
+ (when ,a-cons
+ (if (eq (cdr ,a-cons) '<font color="#AA5500">*unbound*</font>)
+ '*unbound*
+ (cdr ,a-cons))))))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lsymbol-function"></a>
+
+<hr>
+
+<h2>lsymbol-function</h2>
+
+<hr>
+
+<p>The function 'lsymbol-function' returns a function value from the lexical
+environment:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">lsymbol-function</font> (symbol)
+ (cond ((not (or (symbolp symbol)
+ (and (consp symbol)
+ (eq 'quote (car symbol))
+ (symbolp (cadr symbol)))))
+ (error <font color="#880000">"bad argument type"</font> symbol))
+ ((and (consp symbol) (cddr symbol))
+ (error <font color="#880000">"too many arguments"</font>))
+ (t (let ((a-cons (gensym)) (level (gensym)) (binding (gensym)))
+ `(let ((,a-cons (dolist (,level (cdr (getenv)) nil)
+ (let ((,binding (assoc ,symbol ,level)))
+ (when ,binding (return ,binding))))))
+ (when ,a-cons
+ (if (eq (cdr ,a-cons) '<font color="#AA5500">*unbound*</font>)
+ '*unbound*
+ (cdr ,a-cons))))))))
+</pre>
+
+<p>The XLISP function
+<nobr><a href="../reference/symbol-function.htm">symbol-function</a></nobr>
+only works with symbols interned in the
+<a href="../reference/global-obarray.htm">*obarray*</a>, so it cannot return
+a function value, bound to a symbol in the lexical environment:</p>
+
+<pre class="example">
+(flet ((my-function (x) 'hello))
+ (symbol-function 'my-function)) <font color="#AA0000">; <- searches the *obarray*</font>
+=> <font color="#AA0000">error: unbound function - MY-FUNCTION</font>
+
+(flet ((my-function (x) 'hello))
+ (lsymbol-function 'my-function)) <font color="#008844">; <- searches the lexical environment</font>
+=> #<Closure-MY-FUNCTION...>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="lmacroexpand-1"></a>
+
+<hr>
+
+<h2>lmacroexpand-1</h2>
+
+<hr>
+
+<pre class="example">
+(defmacro <font color="#0000CC">with-static-env</font> (&rest body)
+ (let ((env (gensym)) (rval (gensym)))
+ `(let ((,env (getenv))) <font color="#008844">; environment snapshot</font>
+ (progv '(*evalhook*)
+ '((lambda (exp env)
+ (labels ((,rval (exp env) <font color="#008844">; recursive eval</font>
+ (format t "exp: ~a env: ~a ,env: ~a~%" exp env ,env)
+ (evalhook exp #',rval NIL ,env)))
+ (format t "exp: ~a env: ~a ,env: ~a~%" exp env ,env)
+ (evalhook exp #',rval NIL ,env))))
+ ,@body))))
+</pre>
+
+<pre class="example">
+(defmacro <font color="#0000CC">with-dynamic-env</font> (&rest body)
+ (let ((env (gensym)) (rval (gensym)))
+ `(let ((,env (getenv))) <font color="#008844">; environment snapshot</font>
+ (progv '(*evalhook*)
+ '((lambda (exp env)
+ (labels ((,rval (exp env) <font color="#008844">; recursive eval</font>
+ (format t "inner exp: ~a env: ~a~%" exp env)
+ (evalhook exp #',rval NIL env)))
+ (format t "outer exp: ~a env: ~a~%" exp env)
+ (evalhook exp #',rval NIL env))))
+ ,@body))))
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">display-env</font> (env &optional (exp nil exp-p))
+ (flet ((display-bindings (name bindings)
+ (format t <font color="#880000">" ~a bindings: ~s~%"</font> name bindings)
+ (let ((frame-counter 1))
+ (dolist (frame bindings)
+ (format t <font color="#880000">" ~a frame ~a: ~a~%"</font> name frame-counter frame)
+ (let ((binding-counter 1))
+ (dolist (binding frame)
+ (when (consp binding)
+ (format t <font color="#880000">" ~a ~a: ~s - value: ~s~%"</font>
+ name binding-counter (car binding) (cdr binding))
+ (incf binding-counter))))
+ (incf frame-counter)))))
+ (when exp-p (format t <font color="#880000">"eval: ~s~%"</font> exp))
+ (format t <font color="#880000">"environment: ~s~%"</font> env)
+ (display-bindings <font color="#880000">"variable"</font> (car env))
+ (display-bindings <font color="#880000">"function"</font> (cdr env))))
+
+(defmacro <font color="#0000CC">debug:env</font> ()
+ '(progv '(*evalhook*) '(nil)
+ (display-env (getenv))))
+
+(defmacro <font color="#0000CC">debug:env</font> ()
+ '(progv '(*evalhook*) '((lambda (exp env)
+ (display-env env)))
+ (eval nil)))
+
+(defmacro <font color="#0000CC">debug:env</font> (&rest body)
+ (when *evalhook*
+ (format t "DEBUG:ENV ")
+ (format t "*evalhook* was already modified~%"))
+ (if (null body)
+ '(progv '(<font color="#AA5500">*evalhook*</font>) '((lambda (exp env)
+ (display-env env)))
+ (eval nil))
+ (let ((init (gensym)) (rval (gensym)))
+ `(let ((,init (getenv))) <font color="#008844">; environment snapshot</font>
+ (progv '(<font color="#AA5500">*evalhook*</font>)
+ '((lambda (exp env)
+ (labels ((,rval (exp env) <font color="#008844">; recursive eval</font>
+ (display-env env exp)
+ (evalhook exp #',rval nil env)))
+ (display-env ,init exp)
+ (evalhook exp #',rval nil ,init))))
+ ,@body)))))
+
+(defmacro <font color="#0000CC">with-evalhook</font> (&rest body)
+ (let ((init (gensym)) (rval (gensym)) (hook (gensym)) debug)
+ `(let ((,init (getenv))) <font color="#008844">; environment snapshot</font>
+ (progv '(<font color="#AA5500">*evalhook*</font>)
+ '((lambda (exp env)
+ (labels ((,rval (exp env) <font color="#008844">; recursive eval</font>
+ ,(print *evalhook*)
+ ,(when T `(funcall ,*evalhook* exp env))
+
+ (evalhook exp #',rval nil env)))
+ (evalhook exp #',rval nil ,init))))
+ ,@body))))
+
+(defmacro <font color="#0000CC">with-current-environment</font> (&rest body)
+ (when <font color="#AA5500">*evalhook*</font> (error <font color="#880000">"*evalhook* already modified"</font>))
+ (let ((init (gensym)) (rval (gensym)) debug)
+ (when (eq :debug (car body)) (setq debug t body (cdr body)))
+ `(let ((,init (getenv))) <font color="#008844">; environment snapshot</font>
+ (progv '(<font color="#AA5500">*evalhook*</font>)
+ '((lambda (exp env)
+ (labels ((,rval (exp env) <font color="#008844">; recursive eval</font>
+ <font color="#008844">;; append environment from snapshot</font>
+ (setq env (cons (append (car env) (car ,init))
+ (append (cdr env) (cdr ,init))))
+ ,(when debug '(display-env env exp))
+ (evalhook exp #',rval nil env)))
+ <font color="#008844">;; start with environment snapshot</font>
+ ,(when debug `(display-env ,init exp))
+ (evalhook exp #',rval nil ,init))))
+ ,@body))))
+
+(defmacro <font color="#0000CC">with-env</font> (&rest body)
+ (let ((init (gensym)) (rval (gensym)))
+ `(let ((,init (getenv))) <font color="#008844">; environment snapshot</font>
+ (progv '(*evalhook*)
+ '((lambda (exp env)
+ (labels ((,rval (exp env) <font color="#008844">; recursive eval</font>
+ (display-env env exp)
+ (evalhook exp #',rval nil env)))
+ (display-env ,init exp)
+ (evalhook exp #',rval nil ,init))))
+ ,@body))))
+</pre>
+
+<pre class="example">
+(with-current-environment
+ (debug:env
+ body))
+
+(progv '(*evalhook)
+ '((lambda (exp env)
+ (labels ((rval (exp env)
+ (append-current-environment)
+ (debug:env ...)
+ (evalhook exp #'rval nil env)))
+ (evalhook exp #'rval nil init)))))
+
+(debug:env
+ (with-current-environment
+ body))
+
+(progv '(*evalhook)
+ '((lambda (exp env)
+ (labels ((rval (exp env)
+</pre>
+
+<pre class="example">
+(defmacro <font color="#0000CC">with-current-environment</font> (&rest body)
+ (when <font color="#AA5500">*evalhook*</font> (error <font color="#880000">"*evalhook* already modified"</font>))
+ (let ((debug nil) (init (gensym)) (rval (gensym)))
+ (when (eq :debug (car body)) (setq debug t body (cdr body)))
+ `(let ((,init (getenv))) <font color="#008844">; environment snapshot</font>
+ (progv '(<font color="#AA5500">*evalhook*</font>)
+ '((lambda (exp env)
+ (labels ((,rval (exp env) <font color="#008844">; recursive eval</font>
+ ,(cond (debug
+ `(setq env
+ (cons (append (car env) (car ,init))
+ (append (cdr env) (cdr ,init))))
+ '(display-env env exp)
+ `(evalhook exp #',rval nil env))
+ (t
+ `(evalhook exp #',rval nil
+ (cons (append (car env) (car ,init))
+ (append (cdr env) (cdr ,init))))))))
+ ,(when debug `(display-env ,init exp))
+ (evalhook exp #',rval nil ,init))))
+ ,@body))))
+</pre>
+
+<pre class="example">
+(setq *rvalhook* nil)
+
+(defmacro <font color="#0000CC">with-current-environment</font> (&rest body)
+ (let ((init (gensym)))
+ `(let ((,init (getenv)))
+ (rval-env #'(lambda (exp env)
+ (cons exp (cons (append (car env) (car ,init))
+ (append (cdr env) (cdr ,init)))))
+ ,@body))))
+
+(defmacro debug:env (&rest body)
+ (rval-env #'(lambda (exp env)
+ (display-env env exp)
+ (cons exp env))
+ ,@body))
+
+(defmacro <font color="#0000CC">run-rvalhooks</font> ()
+ (let ((func (gensym)) (result (gensym)))
+ `(dolist (,func <font color="#AA5500">*rvalhook*</font>)
+ (format t "func: ~a~%" ,func)
+ (format t "exp: ~a~%" exp)
+ (format t "env: ~a~%" env)
+ (let ((,result (eval (list ,func 'exp 'env) )))
+ (format t "result: ~a~%" ,result)
+ (format t "exp: ~a~%" exp)
+ (format t "car: ~a~%" (car ,result))
+ (format t "env: ~a~%" env)
+ (format t "cdr: ~a~%" (cdr ,result))
+ (setq exp (car ,result) env (cdr ,result))
+ ))))
+
+(defmacro <font color="#0000CC">rval-env</font> (function &rest body)
+ (format t "function: ~a~%" function)
+ (format t "body: ~a~%" body)
+ (or <font color="#AA5500">*evalhook*</font> (setq <font color="#AA5500">*rvalhook*</font> nil))
+ (format t "*rvalhook*: ~a~%" *rvalhook*)
+ (if <font color="#AA5500">*rvalhook*</font>
+ `(prog2
+ (push ,function <font color="#AA5500">*rvalhook*</font>)
+ (progn ,@body)
+ (setq <font color="#AA5500">*rvalhook*</font> (remove ,function <font color="#AA5500">*rvalhook*</font>)))
+ (let ((rval (gensym)) (func (gensym)) (result (gensym)))
+ `(prog2
+ (push ,function <font color="#AA5500">*rvalhook*</font>)
+ (progv '(<font color="#AA5500">*evalhook*</font>)
+ `((lambda (exp env)
+ (print 'hallo)
+ (labels ((,rval (exp env)
+ (run-rvalhooks)
+ (evalhook exp #',rval nil env)))
+ ; (run-rvalhooks)
+ (evalhook exp #',rval nil env))))
+ ,@body)
+ (setq <font color="#AA5500">*rvalhook*</font> (remove ,function <font color="#AA5500">*rvalhook*</font>))))))
+</pre>
+
+<p>*rvalhook* must be a list of functions, each taking two arguments 'exp'
+[the Lisp expressions to evaluate] and 'env' [the environment], returning
+a cons of the format <nobr>(exp . env)</nobr>.</p>
+
+<p>In case of an error, the
+<a href="../reference/global-evalhook.htm">*evalhook*</a> variable is
+automatically reset by the XLISP
+<nobr><a href="../reference/top-level.htm">top-level</a></nobr> function.
+This means that if <a href="../reference/global-evalhook.htm">*evalhook*</a>
+is <a href="../reference/nil.htm">NIL</a> and *rvalhook* is
+<nobr>non-<a href="../reference/nil.htm">NIL</a></nobr>, then *rvalhook* is
+invalid and must also be reset to <a href="../reference/nil.htm">NIL</a>
+before pushing the next function <nobr>on it</nobr>.</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">lmacroexpand-1</font> (form)
+ (if (not (and (consp form)
+ (eq 'quote (car form))
+ (symbolp (caadr form))))
+ form <font color="#008844">; if the form isn't '(symbol ... )</font>
+ (let ((a-cons (gensym)) (l-expr (gensym)))
+ `(let ((,a-cons (assoc ',(caadr form) (cadr (getenv)))))
+ (if (null ,a-cons) <font color="#008844">; (caadr form) = macro-name</font>
+ ,form <font color="#008844">; if no lexical binding was found</font>
+ (let ((,l-expr (get-lambda-expression (cdr ,a-cons))))
+ (if (eq 'macro (car ,l-expr)) <font color="#008844">; if l-expr is a macro</font>
+ (with-current-environment
+ <font color="#008844">;; create an *unbound* macro in the *obarray*</font>
+ (eval (append '(defmacro *unbound*) (cdr ,l-expr)))
+ <font color="#008844">;; expand the macro in the current environment</font>
+ (eval (list 'macroexpand-1 <font color="#008844">; (cdadr form) =</font>
+ (list 'quote <font color="#008844">; macro-arguments as list</font>
+ (cons '*unbound* ',(cdadr form))))))
+ ,form))))))) <font color="#008844">; if l-expr is not a macro</font>
+</pre>
+
+<pre class="example">
+(let ((x 1))
+ (macrolet ((test (arg)
+ `(progn
+ (print ,arg)
+ (print ,(eval x)))))
+ (lmacroexpand-1 '(test 'hallo))))
+=>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="known-problems"></a>
+
+<hr>
+
+<h2>Known Problems</h2>
+
+<hr>
+
+<p>A lexical variable with the symbol
+<a href="../reference/global-unbound.htm">*unbound*</a> as a variable value
+bound to it will continue to shadow a global variable with the same name,
+even if the the lexical variable is 'unbound':</p>
+
+<pre class="example">
+(setq x t) => T <font color="#008844">; create a global variable 'x'</font>
+
+(let ((x '*unbound*)) <font color="#008844">; create an unbound lexical variable 'x'</font>
+ (print x)) <font color="#008844">; try to print the global variable</font>
+<font color="#AA0000">error: unbound variable - X</font>
+</pre>
+
+<p>Tested with <nobr>Nyquist 3.03</nobr> in <nobr>December 2010</nobr>.</p>
+
+<p><b>Nyquist Bug:</b> let* causes infinite recursion problems with either
+progv, evalhook, or *evalhook* [still needs more investigation], so this
+doesnt work:</p>
+
+<pre class="example">
+(let* ((init (getenv)))
+ (progv '(*evalhook*)
+ '((lambda (exp env)
+ (labels ((rval (exp env)
+ (print init) <font color="#AA0000">; <- causes infinite recursion</font>
+ (evalhook exp #'rval nil env)))
+ (evalhook exp #'rval nil init))))
+ (eval nil)))
+=> <font color="#AA0000">infinite recursion</font>
+</pre>
+
+while exactly the same form using let instead of let* works:
+
+<pre class="example">
+(let ((init (getenv)))
+ (progv '(*evalhook*)
+ '((lambda (exp env)
+ (labels ((rval (exp env)
+ (print init) <font color="#008844">; <- no infinite recursion</font>
+ (evalhook exp #'rval nil env)))
+ (evalhook exp #'rval nil init))))
+ (eval nil)))
+(NIL) <font color="#008844">; PRINT output</font>
+=> NIL
+</pre>
+
+<p>Bug tested with <nobr>Nyquist 3.03</nobr> in <nobr>December 2010</nobr>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/evaluation.htm b/docsrc/xlisp/xlisp-doc/examples/evaluation.htm new file mode 100644 index 0000000..fc46780 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/evaluation.htm @@ -0,0 +1,131 @@ +<html><head>
+
+<title>Evaluation</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Evaluation</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#with-errset">with-errset</a> - evaluate expressions without entering the <nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr></nobr></li>
+<li><nobr><a href="#apply-star.htm">apply*</a> and <a href="#funcall-star.htm">funcall*</a> - work also with macros and special forms</nobr></li>
+</ol>
+
+<a name="with-errset"></a>
+
+<hr>
+
+<h2>with-errset</h2>
+
+<hr>
+
+<p>Evaluate an expression without entering the
+<nobr><a href="../manual/xlisp.htm#break-loop">Break Loop</a></nobr>
+on <a href="../reference/error.htm">error</a>
+<nobr>or <a href="../reference/cerror.htm">cerror</a></nobr>:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">with-errset</font> (expr &optional (print-flag nil))
+ `(progv '(<font color="#AA5500">*breakenable*</font>) '(nil)
+ (errset ,expr ,print-flag)))
+</pre>
+
+<p>See <a href="../reference/defmacro.htm">defmacro</a>,
+<a href="../reference/errset.htm">errset</a>,
+<a href="../reference/nil.htm">nil</a>,
+<a href="../reference/lambda-keyword-optional.htm.htm">&optional</a>,
+<a href="../reference/progv.htm">progv</a>.</p>
+
+<p><b>Note:</b> <a href="../reference/errset.htm">errset</a> does not
+protect against the <a href="../reference/break.htm">break</a> function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="apply-star"></a><a name="funcall-star"></a>
+
+<hr>
+
+<h2>apply* and funcall*</h2>
+
+<hr>
+
+<p>In Lisp, macros and <nobr>special forms</nobr> are no functions. This
+means that <a href="../reference/apply.htm">apply</a> and
+<a href="../reference/funcall.htm">funcall</a> only work with functions of
+type SUBR <nobr>[built-in</nobr> function] or CLOSURE [functions defined by
+<a href="defun.htm">defun</a>, <a href="flet.htm">flet</a>,
+<a href="labels.htm">labels</a>, or <a href="lambda.htm">lambda</a>], but
+with macros and <nobr>special forms</nobr> a '<nobr>bad function</nobr>'
+error is signalled. Here are two examples how to work around this
+behaviour:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">apply*</font> (function args)
+ (eval (cons function args)))
+
+(defun <font color="#0000CC">funcall*</font> (function args)
+ (eval (cons function args)))
+</pre>
+
+<p><b>Warning:</b> These functions can produce unwanted
+<nobr>side-effects</nobr> because macros and <nobr>special forms</nobr> do
+not need to conform to functional evaluation rules. Use them on your own
+risk.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
+
diff --git a/docsrc/xlisp/xlisp-doc/examples/examples.htm b/docsrc/xlisp/xlisp-doc/examples/examples.htm new file mode 100644 index 0000000..2140ebe --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/examples.htm @@ -0,0 +1,211 @@ +<html><head><title>XLISP Examples</title></head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+Examples |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>XLISP Examples</h1>
+
+<hr>
+
+<p><b>Nyquist/XLISP</b></p>
+
+<ul>
+<li><nobr><a href="lists.htm">Lists</a></nobr></li>
+<ul>
+<li><nobr>print-cons - print lists as dotted conses</nobr></li>
+<li><nobr>dolist* - a <a href="../reference/dolist.htm">dolist</a> version that can iterate dotted lists</nobr></li>
+</ul>
+<li><nobr><a href="arrays.htm">Arrays</a></nobr></li>
+<ul>
+<li><nobr>make-array* - create multi-dimensional arrays</nobr></li>
+<li><nobr>aref* - access multi-dimensional arrays</nobr></li>
+</ul>
+<li><nobr><a href="circular-lists.htm">Circular Access</a></nobr></li>
+<ul>
+<li><nobr>c-nth - circular list accessor</nobr></li>
+<li><nobr>c-aref - circular array accessor</nobr></li>
+</ul>
+<li><nobr><a href="hash-tables.htm">Hash Tables</a></nobr></li>
+<ul>
+<li><nobr>make-hash-table - create a hash-table</nobr></li>
+<li><nobr>puthash - store a key/value pair in a hash-table</nobr></li>
+<li><nobr>gethash - get a value from a hash-table by using a key</nobr></li>
+<li><nobr>remhash - remove a key/value pair from a hash-table</nobr></li>
+<li><nobr>clrhash - remove all key/value pairs from a hash-table</nobr></li>
+<li><nobr>hash-table-p - is this a hash-table?</nobr></li>
+<li><nobr>hash-table-size - get the number of buckets</nobr></li>
+<li><nobr>hash-table count - get the number of key/value pairs</nobr></li>
+<li><nobr>hash-table-test - get the :test argument given to to make-hash-table</nobr></li>
+<li><nobr>print-hash-table - print a hash-table in human-readable form</nobr></li>
+</ul>
+<li><nobr><a href="strings.htm">Strings and Characters</a></nobr></li>
+<ul>
+<li><nobr>string* - make a string out of everything</nobr></li>
+<li><nobr><a href="posix-chars.htm">POSIX Character Classes</a></nobr></li>
+</ul>
+<li><nobr><a href="sequences.htm">Sequences</a> - lists, strings, and arrays</nobr></li>
+<li><nobr><a href="predicates.htm">Predicates and Comparison</a></nobr></li>
+<li><nobr><a href="files.htm">Files and Directories</a></nobr></li>
+<li><nobr><a href="math.htm">Numbers</a></nobr></li>
+<ul>
+<li><nobr>Non-decimal Number Formats</nobr></li>
+<ul>
+<li><nobr><a href="binary.htm">Binary Integer Numbers</a></nobr></li>
+<li><nobr><a href="octal.htm">Octal Integer Numbers</a></nobr></li>
+<li><nobr><a href="hexadecimal.htm">Hexadecimal Integer Numbers</a></nobr></li>
+</ul>
+<li><nobr>divide-float - divide numbers as floating-point numbers</nobr></li>
+<li><nobr><a href="xlisp/ceiling.htm">ceiling</a> - truncate a number toward positive infinity</nobr></li>
+<li><nobr><a href="xlisp/floor.htm">floor</a> - truncate a number toward negative infinity</nobr></li>
+<li><nobr><a href="xlisp/ash.htm">ash</a> - arithmetic bit-shift left or right</nobr></li>
+<li><nobr><a href="xlisp/bsh.htm">bsh</a> - binary bit-shift left or right</nobr></li>
+<li><nobr>csh - circular bit-shift left or right</nobr></li>
+</ul>
+<li><nobr><a href="reader.htm">Reader</a></nobr></li>
+<ul>
+<li><nobr>read-from-string</nobr></li>
+<li><nobr>*readtable*</nobr></li>
+<ul>
+<li><nobr>print-readtable - print the XLISP *readtable* in human-readable form</nobr></li>
+<li><nobr>get-macro-character</nobr></li>
+<li><nobr>set-macro-character</nobr></li>
+</ul>
+</ul>
+</ul>
+
+<ul>
+<li><nobr><a href="apropos.htm">Apropos</a></nobr></li>
+<li><nobr><a href="macros.htm">Macro Programming</a></nobr></li>
+<li><nobr><a href="evaluation.htm">Evaluation</a></nobr></li>
+<li><nobr><a href="environment.htm">Environment</a></nobr></li>
+<li><nobr><a href="../objects/advanced-objects.htm">Advanced XLISP Objects</a></nobr></li>
+</ul>
+
+<ul>
+<li><nobr><a href="reader.htm">XLISP Reader</a></nobr></li>
+</ul>
+
+<p><b>Common Lisp</b> - written in Nyquist/XLISP</p>
+
+<ul>
+<li><nobr><a href="common-lisp.htm">Where is the Nyquist Common Lisp Library?</a></nobr></li>
+</ul>
+
+<ul>
+<li><nobr>Data and Control Flow</nobr></li>
+<ul>
+<li><nobr>Comparison</nobr></li>
+<ul>
+<li><nobr><a href="../reference/eq.htm">eq</a></nobr> - [Function] - test if arguments are identical</li>
+<li><nobr><a href="../reference/eql.htm">eql</a> - [Function] - test if arguments are identical or same integer value</nobr></li>
+<li><nobr><a href="../reference/equal.htm">equal</a> - [Function] - test if arguments are structurally equivalent</nobr></li>
+<li><nobr><a href="common-lisp/equalp.htm">cl:equalp</a> - [Function] - test arguments with 'equality' functions</nobr></li>
+</ul>
+<li><nobr><a href="common-lisp/multiple-values.htm">Multiple Values</a></nobr></li>
+<ul>
+<li><nobr>XLISP helpers</nobr></li>
+<ul>
+<li><nobr><a href="common-lisp/global-multiple-values.htm">cl:*multiple-values*</a> - [Variable] - signals if a function has returned multiple values</nobr></li>
+<li><nobr><a href="common-lisp/debug-mv.htm">cl:debug:mv</a> - [Function] - debug multiple value expressions</nobr></li>
+</ul>
+<li><nobr>Returning Multiple Values</nobr></li>
+<ul>
+<li><nobr><a href="common-lisp/values.htm">cl:values</a> - [Function] - return results from evaluated arguments as multiple values</nobr></li>
+<li><nobr><a href="common-lisp/values-list.htm">cl:values-list</a> - [Function] - return multiple values from a list unevaluated</nobr></li>
+</ul>
+<li><nobr>Working with Multiple Values</nobr></li>
+<ul>
+<li><nobr><a href="common-lisp/multiple-value-list.htm">cl:multiple-value-list</a> - [Macro] - evaluate an expression and return all values in a list</nobr></li>
+<li><nobr><a href="common-lisp/multiple-value-bind.htm">cl:multiple-value-bind</a> - [Macro] - bind multiple values to multiple <a href="../reference/let.htm">let</a> variables</nobr></li>
+<li><nobr><a href="common-lisp/multiple-value-setq.htm">cl:multiple-value-setq</a> - [Macro] - assign multiple values to multiple variables using <a href="../reference/setq.htm">setq</a></nobr></li>
+<li><nobr><a href="common-lisp/multiple-value-prog1.htm">cl:multiple-value-prog1</a> - [Macro] - eveluate multiple expressions, return the values of the first expression</nobr></li>
+<li><nobr><a href="common-lisp/multiple-value-call.htm">cl:multiple-value-call</a> - [Macro] - apply a function to multiple values collected in a list</nobr></li>
+</ul>
+</ul>
+</ul>
+<li><nobr><a href="common-lisp/numbers.htm">Numbers</a></nobr></li>
+<ul>
+<li><nobr><a href="common-lisp/rounding-and-truncation.htm">Rounding and Truncation</a></nobr></li>
+<ul>
+<li><nobr><a href="common-lisp/round.htm">cl:round</a> - round towards the next integer</nobr></li>
+<li><nobr><a href="common-lisp/truncate.htm">cl:truncate</a> - truncate towards zero</nobr></li>
+<li><nobr><a href="common-lisp/ceiling.htm">cl:ceiling</a> - truncate towards positive infinity</nobr></li>
+<li><nobr><a href="common-lisp/floor.htm">cl:floor</a> - truncate towards negative infinity</nobr></li>
+</ul>
+<li><nobr><a href="common-lisp/remainder-and-modulus.htm">Remainder and Modulus</a></nobr></li>
+<ul>
+<li><nobr><a href="common-lisp/rem.htm">cl:rem</a></nobr></li>
+<li><nobr><a href="common-lisp/mod.htm">cl:mod</a></nobr></li>
+</ul>
+<li><nobr>Exponentiation, Logarithms, and Roots</nobr></li>
+<ul>
+<li><nobr><a href="common-lisp/exp.htm">cl:exp</a> - compute 'e' to the power of 'x'</nobr></li>
+<li><nobr><a href="common-lisp/expt.htm">cl:expt</a> - compute 'x' to the power of 'y'</nobr></li>
+<li><nobr><a href="common-lisp/log.htm">cl:log</a> - logarithms of arbitrary base</nobr></li>
+<li><nobr><a href="common-lisp/sqrt.htm">cl:sqrt</a> - sqare root or arbitrary numbers</nobr></li>
+</ul>
+</ul>
+<li><nobr>Conses</nobr></li>
+<ul>
+<li><nobr>List Membership</nobr></li>
+<ul>
+<li><nobr>cl:member - [Function] - test for membership in lists and sub-elements</nobr></li>
+<li><nobr>cl:member-if - [Function] - search for the first element matching a predicate</nobr></li>
+<li><nobr>cl:member-if-not - [Function] - search for the first element not matching a predicate</nobr></li>
+</ul>
+<li><nobr>Non-destructive Removal</nobr></li>
+<ul>
+<li><nobr>cl:remove</nobr></li>
+<li><nobr>cl:remove-if</nobr></li>
+<li><nobr>cl:remove-if-not</nobr></li>
+</ul>
+<li><nobr>Destructive Removal = Deletion</nobr></li>
+<ul>
+<li><nobr>cl:delete</nobr></li>
+<li><nobr>cl:delete-if</nobr></li>
+<li><nobr>cl:delete-if-not</nobr></li>
+</ul>
+<li><nobr>Lists as Sets</nobr></li>
+<ul>
+<li><nobr>cl:pushnew - [Macro] -</nobr></li>
+<li><nobr>cl:union - [Function]</nobr></li>
+<li><nobr>cl:intersection - [Function]</nobr></li>
+<li><nobr>cl:set-difference - [Function]</nobr></li>
+<li><nobr>cl:set-exclusive-or - [Function]</nobr></li>
+<li><nobr>cl:subsetp - [Function]</nobr></li>
+</ul>
+</ul>
+<li><nobr>Sequences</nobr></li>
+<ul>
+<li><nobr>Subsequences</nobr></li>
+<ul>
+<li><nobr>cl:subseq - subsequences of lists, strings, or arrays</nobr></li>
+</ul>
+<li><nobr>Properties of elements in sequences:</nobr></li>
+<ul>
+<li><nobr>cl:find</nobr></li>
+<li><nobr>cl:count</nobr></li>
+<li><nobr>cl:position</nobr></li>
+</ul>
+<li><nobr>Predicates for testing sequences:</nobr></li>
+<ul>
+<li><nobr>cl:every</nobr></li>
+<li><nobr>cl:some</nobr></li>
+<li><nobr>cl:notevery</nobr></li>
+<li><nobr>cl:notany</nobr></li>
+</ul>
+<li><nobr>Functions to modify sequences:</nobr></li>
+<ul>
+<li><nobr>cl:map</nobr></li>
+</ul>
+</ul>
+</ul>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/files.htm b/docsrc/xlisp/xlisp-doc/examples/files.htm new file mode 100644 index 0000000..a43f4fe --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/files.htm @@ -0,0 +1,459 @@ +<html><head>
+
+<title>Files and Directories</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Files and Directories</h1>
+
+<hr>
+
+<ul>
+<li><nobr>Interactive Functions</nobr></li>
+<ul>
+<li><nobr><a href="#pwd">pwd</a> - returns the current working directory</nobr></li>
+<li><nobr><a href="#cd">cd</a> - changes the current working directory</nobr></li>
+</ul>
+<li><nobr>Testing Files and Directories</nobr></li>
+<ul>
+<li><nobr><a href="#directory-exists-p">directory-exists-p</a> - tests if a directory exists</nobr></li>
+<li><nobr><a href="#file-exists-p">file-exists-p</a> - tests if a file exists</nobr></li>
+<li><nobr><a href="#filename-exists-p">filename-exists-p</a> - tests if a file or directory exists</nobr></li>
+</ul>
+<li><nobr>Testing Filenames</nobr></li>
+<ul>
+<li><nobr><a href="#absolute-filename-p">absolute-filename-p</a> - tests if a string is an absolute filename</nobr></li>
+</ul>
+<li><nobr>System Environment Variables</nobr></li>
+<ul>
+<li><nobr><a href="#windows-p">windows-p</a> - tests if the operation system is a Windows system</nobr></li>
+<li><nobr><a href="#user-home-directory">user-home-directory</a> - returns path to the user's HOME directory</nobr></li>
+<li><nobr><a href="#expand-tilde">expand-tilde</a> - replaces "~/" with the user's HOME directory</nobr></li>
+</ul>
+</ul>
+
+<a name="pwd"></a>
+
+<hr>
+
+<h2>pwd</h2>
+
+<hr>
+
+<p>The 'pwd' function returns the current working directory:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">pwd</font> ()
+ (setdir <font color="#880000">"."</font>))
+</pre>
+
+<p>Ok, this function does not belong to the masterpieces of computer
+science, but (pwd) is much easier to remember than <nobr>(setdir
+".")</nobr>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cd"></a>
+
+<hr>
+
+<h2>cd</h2>
+
+<hr>
+
+<p>The 'cd' function changes the current working directory. <nobr>The
+directory</nobr> name must be given as a string:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">cd</font> (string)
+ (cond ((not (stringp string))
+ (error <font color="#880000">"argument must be a string"</font> string))
+ ((string= <font color="#880000">"."</font> string)
+ (setdir <font color="#880000">"."</font>))
+ (t
+ (let ((orig-dir (setdir <font color="#880000">"."</font>))
+ (new-dir (setdir string)))
+ (when (string/= orig-dir new-dir)
+ new-dir)))))
+</pre>
+
+<p>Possible actions and return values are:</p>
+
+<ul>
+
+<li><p>It the argument is not a string, then an error will be
+raised.</p></li>
+
+<li><p>If the directory name is ".", then the name of the current
+working directory is returned as a string. This is the same effect as if the
+directory has been changed to itself.</p></li>
+
+<li><p>If the directory has successfully been changed to the given
+directory, then the name of the new working directory is returned as a
+string.</p></li>
+
+<li><p>If the given directory has not been found, then NIL <nobr>[=
+false]</nobr> is returned.</p></li>
+
+</ul>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="directory-exists-p"></a>
+
+<hr>
+
+<h2>directory-exists-p</h2>
+
+<hr>
+
+<p>The '<nobr>directory-exists-p</nobr>' function tests if a directory
+exists. <nobr>The directory</nobr> name must be given as a string:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">directory-exists-p</font> (string)
+ (cond ((not (stringp string))
+ (error <font color="#880000">"argument must be a string"</font> string))
+ ((string= <font color="#880000">"."</font> string)
+ (setdir <font color="#880000">"."</font>))
+ (t
+ (let ((orig-dir (setdir <font color="#880000">"."</font>))
+ (new-dir (setdir string)))
+ (when (string/= orig-dir new-dir)
+ (setdir orig-dir)
+ new-dir)))))
+</pre>
+
+<p>Possible actions and return values are:</p>
+
+<ul>
+
+<li><p>It the argument is not a string, then an error will be
+raised.</p></li>
+
+<li><p>If the directory name is ".", then the absolute name of the
+current working directory is returned as a string. <nobr>This is</nobr> not
+a very useful test, but makes the return values consistent.</p></li>
+
+<li><p>If the directory has been found, then the absolute name of the
+directory is returned as a string.</p></li>
+
+<li><p>If the directory has not been found, then NIL <nobr>[= false]</nobr>
+is returned.</p></li>
+
+</ul>
+
+<p>The '<nobr>directory-exists-p</nobr>' function is nearly the same as the
+<a href="#cd">cd</a> function above. <nobr>The only</nobr> difference is
+that the working directory will automatically be changed back to the initial
+directory.</p>
+
+<p>On Unix, with <nobr>soft-links</nobr>, the absolute name of the target
+directory <nobr>[i.e. not</nobr> the name of the <nobr>link-file</nobr>
+itself, but the name of the directory the link <nobr>points to]</nobr> is
+returned.</p>
+
+<p><div class="box">
+
+<p><b>Implementation Notes</b></p>
+
+<p>The Nyquist 'setdir' function always returns absolute directory names,
+even if a relative directory name has been given as a string by the user.
+That's why it's not possible to reliably compare the return value of
+<nobr>(setdir string)</nobr> directly with 'string'. Instead the absolute
+name of the initial working directory, returned by <nobr>(setdir
+".")</nobr>, is compared to the absolute name, returned when
+<nobr>(setdir string)</nobr> tries to change the directory. <nobr>If
+both</nobr> return values are the same, then <nobr>(setdir string)</nobr>
+has failed because the directory has not been found.</p>
+
+<p>If the directory string is ".", then this trick doesn't work,
+because the initial directory is the same as the target directory, so even
+if the directory has 'successfully' been changed to itself, both return
+values still would be the same. This is one of the reasons why "."
+has a separate 'cond' clause. The other reason is of course that it makes
+not really much sense to change a directory to itself, that's why we save
+the work and just return the absolute name of the current working
+directory.</p>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="file-exists-p"></a>
+
+<hr>
+
+<h2>file-exists-p</h2>
+
+<hr>
+
+<p>The '<nobr>file-exists-p</nobr>' function tests if a file exists.
+<nobr>The file</nobr> name must be given as a string:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">file-exists-p</font> (string)
+ (if (not (stringp string))
+ (error <font color="#880000">"argument must be a string"</font> string)
+ (unless (directory-exists-p string)
+ (let (file-stream)
+ (unwind-protect
+ (setq file-stream (open string))
+ (when file-stream (close file-stream)))
+ (when file-stream string)))))
+</pre>
+
+<p>On Unix systems a directory is a special kind of file, so on Unix the
+XLisp 'open' function can open directories, too. That's why we first must
+make sure that no directory exists with the same name as the file that we
+are looking for.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="filename-exists-p"></a>
+
+<hr>
+
+<h2>filename-exists-p</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">filename-exists-p</font> (string)
+ (if (not (stringp string))
+ (error <font color="#880000">"argument must be a string"</font> string)
+ (or (directory-exists-p string)
+ (file-exists-p string)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="absolute-filename-p"></a>
+
+<hr>
+
+<h2>absolute-filename-p</h2>
+
+<hr>
+
+<p>The 'absolute-filename-p' function tests if a string is an absolute file
+or directory name:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">absolute-filename-p</font> (string)
+ (if (not (stringp string))
+ (error <font color="#880000">"argument must be a string"</font> string)
+ (let ((end (length string)))
+ (when (or (and (>= end 1) <font color="#008844">; Unix "/..."</font>
+ (char= #\/ (char string 0)))
+ (and (>= end 3) <font color="#008844">; Windows "[a-zA-Z]:[\/]..."</font>
+ (let ((char (char string 0)))
+ <font color="#008844">;; upper- or lowercase character a-z, A-Z</font>
+ (and (> (char-code (char-downcase char)) 96)
+ (< (char-code (char-downcase char)) 123)))
+ (char= #\: (char string 1))
+ (let ((char (char string 2)))
+ (or (char= #\\ char)
+ (char= #\/ char)))))
+ string))))
+</pre>
+
+
+<p>Note that it is only tested whether the beginning of the string
+matches the beginning of an absolute file or directory name. <nobr>It
+is</nobr> not tested whether the string reperesents a meaningful name.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="system-environment-variables"></a>
+
+<hr>
+
+<h2>System Environment Variables</h2>
+
+<a name="get-env"></a>
+
+<hr>
+
+<h2>get-env</h2>
+
+<hr>
+
+<p>[This function works only with <nobr>Audacity 1.3.13</nobr> and
+above.]</p>
+
+<p><div class="box">
+
+<dl>
+
+<dt><p><nobr>(<b>get-env</b> "<i>environment-variable</i>")</nobr></p></dt>
+
+
+
+
+</dl>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="windows-p"></a>
+
+<hr>
+
+<h2>windows-p</h2>
+
+<hr>
+
+<p>[This function works only with <nobr>Audacity 1.3.13</nobr> and
+above.]</p>
+
+<p>The '<nobr>windows-p</nobr>' function tests if the underlying operation
+system is a Microsoft <nobr>Windows[tm]</nobr> system:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">windows-p</font> ()
+ (let* ((home (let ((drive (get-env <font color="#880000">"HOMEDRIVE"</font>))
+ (path (get-env <font color="#880000">"HOMEPATH"</font>)))
+ (if (and drive path)
+ (strcat drive path)
+ (get-env <font color="#880000">"UserProfile"</font>))))
+ (path (get-env <font color="#880000">"PATH"</font>)))
+ (when home <font color="#008844">; if HOMEDRIVE + HOMEPATH or UserProfile exist</font>
+ (if path <font color="#008844">; search for Windows :\ drive-letter patterns</font>
+ (string-search ":\\" path)
+ (error <font color="#880000">"no PATH environment variable found"</font>)))))
+</pre>
+
+<p>Nquist has a <nobr>*file-separator*</nobr> variable, that could be used
+much easier to detect the operation system:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">windows-p</font> ()
+ (char= <font color="#AA5500">*file-separator*</font> #\\))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="user-home-directory"></a>
+
+<hr>
+
+<h2>user-home-directory</h2>
+
+<hr>
+
+<p>[This function works only with <nobr>Audacity 1.3.13</nobr> and
+above.]</p>
+
+<p>The '<nobr>user-home-directory</nobr>' function returns the path to the
+user's home directory on Linux, Mac, and Windows:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">user-home-directory</font> ()
+ (or (get-env <font color="#880000">"HOME"</font>)
+ (let ((drive (get-env <font color="#880000">"HOMEDRIVE"</font>))
+ (path (get-env <font color="#880000">"HOMEPATH"</font>)))
+ (when (and drive path)
+ (strcat drive path)))
+ (get-env <font color="#880000">"UserProfile"</font>)))
+</pre>
+
+<p>If the user's home directory could be identified, then the path to the
+home directory is returned as a string. <nobr>If the</nobr> user's home
+directory could not be identified, then <nobr>NIL [= false]</nobr> is
+returned.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(user-home-directory) <font color="#444444">=></font> <font color="#008844">"/home/edgar" ; Linux</font>
+(user-home-directory) <font color="#444444">=></font> <font color="#008844">"C:\\Documents and Settings\\Edgar" ; Windows</font>
+</pre>
+
+<p>On Windows there is no HOME variable defined by Windows itself, but most
+programs will respect a HOME variable, if one had been defined by the user.
+This means that on Windows, if a HOME variable exists, the HOME variable
+will be used instead of HOMEDRIVE and HOMEPATH or 'UserProfile'.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="expand-tilde"></a>
+
+<hr>
+
+<h2>expand-tilde</h2>
+
+<hr>
+
+<p>[This function works only with <nobr>Audacity 1.3.13</nobr> and
+above.]</p>
+
+<pre class="example">
+(defun <font color="#0000CC">expand-filename</font> (string)
+ (cond ((not (stringp string))
+ (error <font color="#880000">"argument must be a string"</font> string))
+ ((and (> (length string) 1)
+ (char= #\~ (char string 0))
+ (or (char= #\/ (char string 1))
+ (char= #\\ (char string 1))))
+ (strcat (user-home-directory)
+ (subseq string 1)))
+ (t string)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
+
diff --git a/docsrc/xlisp/xlisp-doc/examples/hash-tables.htm b/docsrc/xlisp/xlisp-doc/examples/hash-tables.htm new file mode 100644 index 0000000..3a74ffa --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/hash-tables.htm @@ -0,0 +1,496 @@ +<html><head>
+
+<title>Hash Tables</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Hash Tables</h1>
+
+<hr>
+
+<p>The internal XLISP 'hash' function from 'xlsym.c':</p>
+
+<pre class="example">
+<font color="#008844">/* hash - hash a symbol name string */</font>
+int <font color="#0000CC">hash</font>(char *str, int len)
+{
+ int i;
+ for (i = 0; *str; )
+ i = (i << 2) ^ *str++;
+ i %= len;
+ return (i < 0 ? -i : i);
+}
+</pre>
+
+<p>In XLISP this would look like:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">lisp-hash</font> (string table-size)
+ (let ((i 0))
+ (dotimes (index (length string))
+ (setq i (logxor (bsh i 2) (char-code (char string index)))))
+ (setq i (rem i table-size))
+ (if (minusp i) (- i) i)))
+</pre>
+
+<p>A <a href="../reference/hash.htm">hash</a> function is a kind of random
+number generator, where the same input always produces the same output
+number. <nobr>The XLISP</nobr> <a href="../reference/hash.htm">hash</a>
+function computes equally distributed integer numbers in a given range from
+the characters of an input string.</p>
+
+<p>A very simple example:</p>
+
+<ol>
+
+<li><p>We want to store <nobr>4 strings</nobr> in <nobr>2 lists</nobr>,
+stored in <nobr>2 array</nobr> elements:</p>
+
+<pre class="example">
+> (setq my-array (make-array 2))
+#(NIL NIL) <font color="#008844">; NIL NIL = two empty lists</font>
+</pre>
+
+<p>If the array index is computed by the
+<a href="../reference/hash.htm">hash</a> function, then the equally
+distributed numbers make sure that every list will contain approximately
+the same number of strings:</p>
+
+<pre class="example">
+> (dolist (string '("a" "b" "c" "d") my-array)
+ (push string (aref my-array (<font color="#AA0000">hash</font> string (length my-array)))))
+#(("d" "b") ("c" "a"))
+</pre>
+
+<p>The order of the strings in the array was computed by the
+<a href="../reference/hash.htm">hash</a> function, it is not the same order
+as given to <a href="../reference/dolist.htm">dolist</a>.</p></li>
+
+<li><p><nobr>If we</nobr> now search for a string in the lists then the
+<a href="../reference/hash.htm">hash</a> function will tell us the number of
+the array element with the list containing the string because the same input
+string to the <a href="../reference/hash.htm">hash</a> function always
+produces the same output number, as long as the same
+'<nobr>table-size</nobr>' [the same number of array elements] is used:</p>
+
+<pre class="example">
+> (dolist (string '("a" "b" "c" "d"))
+ (format t "~s = ~s~%" string
+ (aref my-array (<font color="#AA0000">hash</font> string (length my-array)))))
+"a" = ("c" "a")
+"b" = ("d" "b")
+"c" = ("c" "a")
+"d" = ("d" "b")
+NIL
+</pre>
+
+<p>The <a href="../reference/hash.htm">hash</a> function will always find
+the correct list as long as the number of array elements has not
+changed.</p> </li>
+
+</ol>
+
+<p>The two main tasks of the <a href="../reference/hash.htm">hash</a>
+<nobr>function are</nobr>:</p>
+
+<ol>
+
+<li><p>Make sure that all lists contain approximately the same number of
+elements, independent from the characters in the input strings, no matter if
+the strings are very similar or completely different. With the
+<a href="../reference/hash.htm">hash</a> function it will nearly never
+happen that one list contains all strings while all other lists are
+empty.</p></li>
+
+<li><p>With the same 'name' and '<nobr>table-size</nobr>' arguments the
+<a href="../reference/hash.htm">hash</a> function will always return exactly
+the same integer number, so a string can always be found no matter in what
+order the strings are stored in the lists of the array.</p></li>
+
+</ol>
+
+<p>Now we can find strings stored in lists, but we want to store and find
+arbitrary things. Therefore we replace the ordinary lists with association
+lists:</p>
+
+<pre class="example">
+> (setq my-array (make-array 2))
+#(() ())
+
+> (dolist (a-cons '(("a" . 1) ("b" . 2) ("c" . 3) ("d" . 4)) my-array)
+ (push a-cons (aref my-array (<font color="#AA0000">hash</font> (car a-cons) (length my-array)))))
+#((("d" . 4) ("b" . 2)) (("c" . 3) ("a" . 1)))
+</pre>
+
+<p>We now have an array like this:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td></td>
+ <td align="center"><nobr>Array </nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td align="right"><nobr><code> </code>0<code> </code></nobr></td>
+ <td class="button"><nobr>Association List 1</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td class="button"><nobr><code>(("d" . 4) ("b" . 2))</code></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td align="right"><nobr><code> </code>1<code> </code></nobr></td>
+ <td class="button"><nobr>Association List 2</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td class="button"><nobr><code>(("c" . 3) ("a" . 1))</code></nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>The association lists give the flexibility to store an arbitrary number
+of <nobr>key/value</nobr> pairs, we are not limited by the fixed number of
+array elements, while the array together with the
+<a href="../reference/hash.htm">hash</a> function gives much more speed than
+a single association list if we want to manage a big number of
+ <nobr>key/value pairs</nobr>.</p>
+
+<p>With a big number of key/value pairs it is faster to keep them in many
+small association lists than in one single <nobr>big list</nobr>. Arrays
+provide random access, where every element can be accessed in the same time,
+while a list can only be searched from the beginning up to the matching
+element. <nobr>The longer</nobr> the list, the slower the search
+becomes.</p>
+
+<p>With the <a href="../reference/hash.htm">hash</a> function we find the
+association list containing <nobr>the key</nobr>:</p>
+
+<pre class="example">
+> (dolist (key '("a" "b" "c" "d"))
+ (format t "~s = ~s~%" key
+ (aref my-array (<font color="#AA0000">hash</font> key (length my-array)))))
+"a" = (("c" . 3) ("a" . 1))
+"b" = (("d" . 4) ("b" . 2))
+"c" = (("c" . 3) ("a" . 1))
+"d" = (("d" . 4) ("b" . 2))
+NIL
+</pre>
+
+<p>With the <a href="../reference/assoc.htm">assoc</a> function we find the
+<nobr>key/value pair</nobr>:</p>
+
+<pre class="example">
+> (dolist (key '("a" "b" "c" "d"))
+ (format t "~s = ~s~%" key
+ (<font color="#AA0000">assoc</font> key (aref my-array (<font color="#AA0000">hash</font> key (length my-array)))
+ :test #'equal)))
+"a" = ("a" . 1)
+"b" = ("b" . 2)
+"c" = ("c" . 3)
+"d" = ("d" . 4)
+NIL
+</pre>
+
+<p>With the <a href="../reference/cdr.htm">cdr</a> function we get the
+value:</p>
+
+<pre class="example">
+> (dolist (key '("a" "b" "c" "d"))
+ (format t "~s = ~s~%" key
+ (<font color="#AA0000">cdr</font> (<font color="#AA0000">assoc</font> key (aref my-array (<font color="#AA0000">hash</font> key (length my-array)))
+ :test #'equal))))
+"a" = 1
+"b" = 2
+"c" = 3
+"d" = 4
+NIL
+</pre>
+
+<p>And now we have our first working <nobr>hash-table</nobr>.</p>
+
+<p>But we still have one problem. <nobr>The
+<a href="../reference/hash.htm">hash</a></nobr> function works only with
+symbols or strings, while <a href="../reference/assoc.htm">assoc</a> can
+also work with numbers, strings and even lists as 'key' argument. <nobr>To
+make</nobr> our <nobr>hash-table</nobr> work with all types
+<a href="../reference/assoc.htm">assoc</a> can handle, we must make the
+<a href="../reference/hash.htm">hash</a> function happy and convert the
+'key' argument with <a href="../reference/format.htm">format</a> into a
+string before computing the <nobr>hash index:</nobr></p>
+
+<pre class="example">
+> (setq my-array (make-array 2))
+#(() ())
+
+> (dolist (a-cons '((#\x . 1) ((y z) . 2) (12 . 3) (6.5 . 4)) my-array)
+ (push a-cons (aref my-array (<font color="#AA0000">hash</font> (<font color="#AA0000">format</font> nil "~s" (car a-cons))
+ (length my-array)))))
+#(((12 . 3) (#\x . 1)) ((6.5 . 4) ((Y Z) . 2)))
+
+> (dolist (key '(#\x (y z) 12 6.5))
+ (format t "~s = ~s~%" key
+ (<font color="#AA0000">cdr</font> (<font color="#AA0000">assoc</font> key (aref my-array (<font color="#AA0000">hash</font> (<font color="#AA0000">format</font> nil "~s" key)
+ (length my-array)))
+ :test #'equal))))
+#\x = 1
+(Y Z) = 2
+12 = 3
+6.5 = 4
+NIL
+</pre>
+
+<p>Wonderful.</p>
+
+<p>A final quirk still needs to be solved. Maybe you have noticed the :test
+argument to <a href="../reference/assoc.htm">assoc</a>. Like with all Lisp
+functions providing :test arguments, the
+<a href="../reference/assoc.htm">assoc</a> :test defaults to
+<a href="../reference/eql.htm">eql</a> [because
+<a href="../reference/eq.htm">eq</a> is unreliable with numbers, and
+<a href="../reference/eql.htm">eql</a> is faster
+<nobr>than <a href="../reference/equal.htm">equal</a>]</nobr>, but
+<a href="../reference/eql.htm">eql</a> doesn't work with
+<nobr>floating-point</nobr> numbers, strings and lists, so we had to
+<nobr>use <a href="../reference/equal.htm">equal</a></nobr>.</p>
+
+<p>The typical Lisp solution is to provide a :test argument to the
+'make-hash-table' function, so the programmer can choose which function to
+use. <nobr>The :test</nobr> argument to 'make-hash-table' becomes a property
+of the <nobr>hash-table</nobr> itself, so the :test only needs to be given
+once, at the time when the <nobr>hash-table</nobr> is created, and not every
+time the <nobr>hash-table</nobr> is accessed afterwards.</p>
+
+<p>We have the problem that <nobr>hash-tables</nobr> are no
+<nobr>built-in</nobr> XLISP data type and we want use
+<nobr>make-hash-table</nobr> in the same way
+<nobr>as <a href="../reference/make-array.htm">make-array</a></nobr>:</p>
+
+<pre class="example">
+(setq my-hash-table (make-hash-table <font color="#0000CC">size</font> :test #'equal))
+</pre>
+
+<p>Here the make-hash-table function has no access to the property list of
+the '<nobr>my-hash-table</nobr>' symbol, so the only solution is to make the
+:test function become part of the <nobr>hash-table</nobr> itself:</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td></td>
+ <td align="center"><nobr>Array </nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td align="right"><nobr><code> </code>0<code> </code></nobr></td>
+ <td class="button"><nobr>Test Function</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><nobr>the :test argument to
+ <a href="../reference/assoc.htm">assoc</a></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td align="right"><nobr><code> </code>1<code> </code></nobr></td>
+ <td class="button"><nobr>Association List 1</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><nobr>((<i>key1</i> . <i>value1</i>)
+ ... (<i>keyN</i> . <i>valueN</i>))</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td align="right"><nobr><code> </code>2<code> </code></nobr></td>
+ <td class="button"><nobr>Association List 2</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><nobr>((<i>key1</i> . <i>value1</i>)
+ ... (<i>keyN</i> . <i>valueN</i>))</nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td align="right"><nobr><code> </code>3<code> </code></nobr></td>
+ <td class="button"><nobr>Association List 3</nobr></td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><nobr>((<i>key1</i> . <i>value1</i>)
+ ... (<i>keyN</i> . <i>valueN</i>))</nobr></td>
+</tr>
+<tr>
+ <td></td>
+ <td align="center"><nobr>...<code> </code></nobr></td>
+</tr>
+<tr>
+ <td height="2px"></td>
+</tr>
+<tr>
+ <td align="right"><nobr><code> </code><i>n</i><code> </code></nobr></td>
+ <td class="button"><nobr>Association List <i>n</i></nobr></td>
+ <td><nobr> → </nobr></td>
+ <td width="100%"><nobr>((<i>key1</i> . <i>value1</i>)
+ ... (<i>keyN</i> . <i>valueN</i>))</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>This is the final layout of our <nobr>hash-tables</nobr>, so we can start
+to implement the <nobr>hash-table</nobr> functions.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="make-hash-table"></a>
+
+<hr>
+
+<h2>make-hash-table</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">make-hash-table</font> (size &optional (test #'eql))
+ (and (< size 1) (error <font color="#880000">"hash-table minimum size is 1"</font> size))
+ (let ((hash-table (make-array (1+ size))))
+ (setf (aref hash-table 0) test)
+ hash-table))
+
+(defun <font color="#0000CC">gethash</font> (key hash-table)
+ (let* ((size (1- (length hash-table)))
+ (index (1+ (hash (format nil "~s" key) size)))
+ (a-list (aref hash-table index))
+ (test (aref hash-table 0)))
+ (cdr (assoc key a-list :test test))))
+
+(defun <font color="#0000CC">puthash</font> (key value hash-table)
+ (let* ((size (1- (length hash-table)))
+ (index (1+ (hash (format nil "~s" key) size)))
+ (a-list (aref hash-table index))
+ (test (aref hash-table 0))
+ (a-cons (assoc key a-list :test test)))
+ (setf (aref hash-table index)
+ (cons (cons key value)
+ (if a-cons
+ (remove-if #'(lambda (x)
+ (funcall test key (car x)))
+ a-list)
+ a-list)))))
+
+(defun <font color="#0000CC">remhash</font> (key hash-table)
+ (let* ((size (1- (length hash-table)))
+ (index (1+ (hash (format nil "~s" key) size)))
+ (a-list (aref hash-table index))
+ (test (aref hash-table 0))
+ (a-cons (assoc key a-list :test test)))
+ (and a-cons
+ (setf (aref hash-table index)
+ (remove-if #'(lambda (x)
+ (funcall test key (car x)))
+ a-list)))
+ a-cons))
+
+(defun <font color="#0000CC">clrhash</font> (hash-table)
+ (let ((size (1- (length hash-table))))
+ (do ((index 1 (1+ index)))
+ ((> index size))
+ (setf (aref hash-table index) nil))
+ hash-table))
+
+(defun <font color="#0000CC">hash-table-p</font> (expr)
+ (and (arrayp expr) <font color="#008844">; expression is an array</font>
+ (> (length expr) 1) <font color="#008844">; with more than one elements</font>
+ (fboundp (aref expr 0)) <font color="#008844">; first element is a function</font>
+ (let ((size (1- (length expr)))) <font color="#008844">; all other</font>
+ (do ((index 1 (1+ index))) <font color="#008844">; elements are lists</font>
+ ((or (> index size)
+ (not (listp (aref expr index))))
+ (> index size))))))
+
+(defun <font color="#0000CC">hash-table-count</font> (hash-table)
+ (let ((size (1- (length hash-table)))
+ (entries 0))
+ (do ((index 1 (1+ index)))
+ ((> index size))
+ (setf entries (+ entries (length (aref hash-table index)))))
+ entries))
+
+(defun <font color="#0000CC">hash-table-size</font> (hash-table)
+ (1- (length hash-table)))
+
+(defun <font color="#0000CC">hash-table-test</font> (hash-table)
+ (aref hash-table 0))
+
+(defun <font color="#0000CC">print-hash-table</font> (hash-table)
+ (if (not (arrayp hash-table))
+ (format t <font color="#880000">";; Not an array: ~s~%"</font> hash-table)
+ (dotimes (index (length hash-table))
+ (let ((element (aref hash-table index)))
+ (cond ((not (listp element))
+ (format t <font color="#880000">";; array element ~a: ~s~%"</font> index element))
+ ((null element)
+ (format t <font color="#880000">";; bucket ~a: ()~%"</font> index))
+ (t
+ (format t <font color="#880000">";; bucket ~a:~%"</font> index)
+ (let ((entry-counter 1))
+ (dolist (entry element)
+ (format t <font color="#880000">";; ~a.~a: ~s~%"</font> index entry-counter entry)
+ (incf entry-counter)))))))))
+</pre>
+
+
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
+
diff --git a/docsrc/xlisp/xlisp-doc/examples/hexadecimal.htm b/docsrc/xlisp/xlisp-doc/examples/hexadecimal.htm new file mode 100644 index 0000000..4b483b0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/hexadecimal.htm @@ -0,0 +1,151 @@ +<html><head>
+
+<title>Hexadecimal Integer Numbers</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Hexadecimal Integer Numbers</h1>
+
+<hr>
+
+<p>XLISP provides the <a href="../manual/xlisp.htm#hexadecimal">#x</a>
+<nobr>read-macro</nobr> for hexadecimal numbers:</p>
+
+<pre class="example">
+#x0 => 0 #x8 => 8 #x10 => 16
+#x1 => 1 #x9 => 9 #x11 => 17
+#x2 => 2 #xa => 10 #x12 => 18
+#x3 => 3 #xb => 11 #x13 => 19
+#x4 => 4 #xc => 12 #x14 => 20
+#x5 => 5 #xd => 13 #x15 => 21
+#x6 => 6 #xe => 14 #x16 => 22
+#x7 => 7 #xf => 15 #x17 => 23
+</pre>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>hex-string</b> <i>integer</i> [<i>all</i>])</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>all</i> - a boolean expression<br>
+returns - the <i>integer</i> in hexadecimal form as string</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">hex-string</font> (integer &optional all)
+ (if (integerp integer)
+ (let ((fmt (if all
+ (or (dolist (bits '(16 32 64 128) nil)
+ (let ((fixnum (round (expt 2.0 (1- bits)))))
+ (and (plusp (1- fixnum))
+ (minusp fixnum)
+ (return (format nil <font color="#880000">"%.~ax"</font> (/ bits 4))))))
+ (error <font color="#880000">"integer limit not found"</font>))
+ <font color="#880000">"%x"</font>)))
+ (progv '(<font color="#AA5500">*integer-format*</font>) (list fmt)
+ (format nil <font color="#880000">"~a"</font> integer)))
+ (error <font color="#880000">"not an integer"</font> integer)))
+</pre>
+
+<p>The '<nobr>hex-string</nobr>' function converts the 'integer' argument
+into hexadecimal form and returns is as a string. <nobr>If the</nobr>
+optional 'all' argument is not given or
+<a href="../reference/nil.htm">NIL</a>, leading zeros are not included in
+the string. <nobr>If the</nobr> optional 'all' argument is
+<nobr>non-<a href="../reference/nil.htm">NIL</a></nobr>, all digits of the
+internal representation of the 'integer' argument, including leading zeros,
+are contained in the string. This is useful for debugging integer overflow
+and <nobr>bit-wise</nobr> functions.</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>hex</b> <i>integer</i> [<i>all</i>])</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>all</i> - a boolean expression<br>
+prints - the <i>integer</i> in hexadecimal form<br>
+returns - the <i>integer</i> argument</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">hex</font> (integer &optional all)
+ (if (integerp integer)
+ (format t <font color="#880000">"#x~a~%"</font> (hex-string integer all))
+ (format t <font color="#880000">";; not an integer~%"</font>))
+ integer)
+</pre>
+
+<p>The 'hex' function prints the 'integer' argument in hexadecimal form on
+the screen. Together with the
+<a href="../manual/xlisp.htm#hexadecimal">#x</a> <nobr>read-macro</nobr>
+this can be used for interactive hexadecimal computations.</p>
+
+<pre class="example">
+> (hex 12345678)
+#xbc614e
+12345678
+
+> (hex (+ #x1f #xa3))
+#xc2
+194
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/lists.htm b/docsrc/xlisp/xlisp-doc/examples/lists.htm new file mode 100644 index 0000000..34f9053 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/lists.htm @@ -0,0 +1,580 @@ +<html><head>
+
+<title>Lists</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Lists</h1>
+
+<hr>
+
+<p>Lists are also <a href="sequences.htm">Sequences</a>.</p>
+
+<ul>
+<li><nobr><a href="#print-cons">print-cons</a> - print lists as conses</nobr></li>
+<li><nobr><a href="#dolist-star">dolist*</a> - a <a href="../reference/dolist.htm">dolist</a> version that can iterate dotted lists</nobr></li>
+<li><nobr>List Accessors</nobr></li>
+<ul>
+<li><nobr><a href="#cl-list-accessor">cl:list:unary-accessor</a></nobr></li>
+<li><nobr><a href="#cl-list-accessor">cl:list:binary-accessor</a></nobr></li>
+</ul>
+<li><nobr>List Membership</nobr></li>
+<ul>
+<li><nobr><a href="#cl-member">cl:member</a> - [Function] - test for membership in lists and sub-elements</nobr></li>
+<li><nobr><a href="#cl-member-if">cl:member-if</a> - [Function] - search for the first element matching a predicate</nobr></li>
+<li><nobr><a href="#cl-member-if-not">cl:member-if-not</a> - [Function] - search for the first element not matching a predicate</nobr></li>
+</ul>
+<li><nobr>Non-destructive Removal</nobr></li>
+<ul>
+<li><nobr>cl:remove</nobr></li>
+<li><nobr>cl:remove-if</nobr></li>
+<li><nobr>cl:remove-if-not</nobr></li>
+</ul>
+<li><nobr>Destructive Removal = Deletion</nobr></li>
+<ul>
+<li><nobr>cl:delete</nobr></li>
+<li><nobr>cl:delete-if</nobr></li>
+<li><nobr>cl:delete-if-not</nobr></li>
+</ul>
+<li><nobr>Lists as Sets</nobr></li>
+<ul>
+<li><nobr><a href="#cl-pushnew">cl:pushnew</a> - [Macro] -</nobr></li>
+<li><nobr><a href="#cl-union">cl:union</a></nobr> - [Function]</li>
+<li><nobr><a href="#cl-intersection">cl:intersection</a> - [Function]</nobr></li>
+<li><nobr><a href="#cl-set-difference">cl:set-difference</a> - [Function]</nobr></li>
+<li><nobr><a href="#cl-set-exclusive-or">cl:set-exclusive-or</a> - [Function]</nobr></li>
+<li><nobr><a href="#cl-subsetp">cl:subsetp</a> - [Function]</nobr></li>
+</ul>
+</ul>
+
+<a name="print-cons"></a>
+
+<hr>
+
+<h2>print-cons</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">print-cons</font> (item)
+ (labels ((cons-string (item)
+ (case (type-of item)
+ (array (let ((end (length item))
+ (result <font color="#880000">""</font>))
+ (dotimes (index end)
+ (let ((string (cons-string (aref item index))))
+ (setq result
+ (if (eql 0 index)
+ (format nil <font color="#880000">"#(~a"</font> string)
+ (format nil <font color="#880000">"~a ~a"</font> result string)))))
+ (format nil <font color="#880000">"~a)"</font> result)))
+ (character (format nil <font color="#880000">"~s"</font> item))
+ (cons (format nil <font color="#880000">"(~a . ~a)"</font>
+ (cons-string (car item))
+ (cons-string (cdr item))))
+ (string (format nil <font color="#880000">"\"~a\""</font> item))
+ (t item))))
+ (format t <font color="#880000">"~a~%"</font> (cons-string item))
+ item))
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+> (print-cons '(1 2 3))
+(1 . (2 . (3 . NIL)))
+(1 2 3)
+</pre>
+
+<p>The 'print-cons' function is useful for debugging association lists,
+where <a href="../reference/print.htm">print</a> often fails to display the
+correct layout:</p>
+
+<pre class="example">
+> (print-cons (cons '((1 . 2) (3 . 4)) '((a . b) (c . d))))
+(((1 . 2) . ((3 . 4) . NIL)) . ((A . B) . ((C . D) . NIL)))
+(((1 . 2) (3 . 4)) (A . B) (C . D)) <font color="#008844">; <- output of PRINT</font>
+</pre>
+
+<p>Do not think that <a href="../reference/print.htm">print</a> is bad, it
+saves you from reading things like this:</p>
+
+<pre class="example">
+> (print-cons '(defun hello-world ()
+ (print "Hello World!")))
+(DEFUN . (HELLO-WORLD . (NIL . ((PRINT . ("Hello World!" . NIL)) . NIL))))
+(DEFUN HELLO-WORLD NIL (PRINT "Hello World!")) <font color="#008844">; <- output of PRINT</font>
+</pre>
+
+<p>Test this if you don't believe:</p>
+
+<pre class="example">
+> (DEFUN . (HELLO-WORLD . (NIL . ((PRINT . ("Hello World!" . NIL)) . NIL))))
+HELLO-WORLD
+
+> (hello-world)
+"Hello World!"
+</pre>
+
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="dolist-star"></a>
+
+<hr>
+
+<h2>dolist*</h2>
+
+<hr>
+
+<p>A <a href="../reference/dolist.htm">dolist</a> version that can iterate
+dotted lists:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">dolist*</font> (fargs &rest body)
+ (let ((list (gensym)))
+ `(let ((,list ,(second fargs)))
+ (if (not (listp ,list))
+ (error <font color="#880000">"not a list"</font> ,list)
+ (do ((,(first fargs) (first ,list)
+ (if (consp ,list) (first ,list) ,list)))
+ ((null ,list))
+ (setq ,list (and (consp ,list) (rest ,list)))
+ ,@body)))))
+</pre>
+
+<pre class="example">
+(dolist (i '(1 2 3)) (print i)) <font color="#008844">; prints 1 2 3</font>
+(dolist* (i '(1 2 3)) (print i)) <font color="#008844">; prints 1 2 3</font>
+
+(dolist (i '(1 2 . 3)) (print i)) <font color="#008844">; prints 1 2</font>
+(dolist* (i '(1 2 . 3)) (print i)) <font color="#008844">; prints 1 2 3</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-member"></a>
+
+<hr>
+
+<h2>cl:member</h2>
+
+<hr>
+
+<p>XLISP already has the <a href="../reference/member.htm">member</a>
+function to for search elements in lists:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<a href="../reference/member.htm">member</a> <i>expr list</i> [{:test | :test-not} <i>test</i>])</dt>
+<dd><i>expr</i> - the expression to find [an atom or a list]<br>
+<i>list</i> - the list to search<br>
+<i>test</i> - optional test function, default is <a href="../reference/eql.htm">eql</a><br>
+returns - the remainder of the list starting with <i>expr</i></dd>
+</dl>
+
+</div></p>
+
+<nobr>The 'cl:member' function provides an additional :key argument for
+accessing <nobr>sub-elements</nobr> in the list:</nobr>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>cl:member</b> <i>expr list</i> [{:test | :test-not} <i>test</i> :key <i>key</i>])</dt>
+<dd><i>expr</i> - the expression to find [an atom or a list]<br>
+<i>list</i> - the list to search<br>
+<i>test</i> - an optional test function, default is <a href="../reference/eql.htm">eql</a><br>
+<i>key</i> - an optional accessor function for sub-elements in the list<br>
+returns - the remainder of the list starting with <i>expr</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:member</font> (expr list &key test test-not key)
+ (and test test-not (error <font color="#880000">"both :TEST and :TEST-NOT specified"</font>))
+ (if key
+ (cond (test
+ (member expr list
+ :test #'(lambda (x y)
+ (funcall test x (funcall key y)))))
+ (test-not
+ (member expr list
+ :test-not #'(lambda (x y)
+ (funcall test-not x (funcall key y)))))
+ (t (member expr list
+ :test #'(lambda (x y)
+ (eql x (funcall key y))))))
+ (cond (test (member expr list :test test))
+ (test-not (member expr list :test-not test-not))
+ (t (member expr list)))))
+</pre>
+
+<p>Test if the number 4 matches the first or the second element in several
+sublists:</p>
+
+<pre class="example">
+(cl:member 4 '((1 2) (3 4) (5 6)) :key #'first) => NIL <font color="#008844">; no match</font>
+(cl:member 4 '((1 2) (3 4) (5 6)) :key #'second) => ((3 4) (5 6)) <font color="#008844">; number found</font>
+</pre>
+
+<p>Subtle differences between XLISP and Common Lisp:</p>
+
+<pre class="example">
+<font color="#008844">;; Lisp Form XLISP Common Lisp</font>
+(member 1 '(1 2 . 3)) => (1 2 . 3) => (1 2 . 3)
+(member 2 '(1 2 . 3)) => (2 . 3) => (2 . 3)
+(member 3 '(1 2 . 3)) => NIL => <font color="#AA0000">error: not a proper list</font>
+</pre>
+
+
+<p>Here is a 'cl:member' version that behaves <nobr>error-conform</nobr> to
+<nobr>Common Lisp</nobr> but produces an unintelligible backtrace in case of
+Lisp errors. <nobr>I also</nobr> have found no way how to macroexpand
+macrolets, so debugging this function is a real pain.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:member</font> (expr list &key test test-not key)
+ (and test test-not (error <font color="#880000">"both :TEST and :TEST-NOT specified"</font>))
+ (macrolet ((internal-loop (list)
+ `(do ()
+ <font color="#008844">;; termination test</font>
+ ((or (not (consp list))
+ ,(if key
+ (cond (test `(funcall ,test ,expr (funcall ,key (car list))))
+ (test-not `(not (funcall ,test ,expr (funcall ,key (car list)))))
+ (t `(eql ,expr (funcall ,key (car list)))))
+ (cond (test `(funcall ,test ,expr (car list)))
+ (test-not `(not (funcall ,test ,expr (car list))))
+ (t `(eql ,expr (car list))))))
+ <font color="#008844">;; return value</font>
+ (if (not (listp list))
+ (error <font color="#AA0000">"a proper list must not end with"</font> list)
+ list))
+ <font color="#008844">;; body</font>
+ (setq list (cdr list)))))
+ (internal-loop list)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-member-if"></a>
+
+<hr>
+
+<h2>cl:member-if</h2>
+
+<hr>
+
+<p>Here are two functions to search for elements that satisfy a given
+predicate:</p>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>member-if</b> <i>predicate list</i> [:key <i>key</i>])</nobr></dt>
+<dd><i>predicate</i> - a test function with one argument<br>
+<i>list</i> - the list to search<br>
+<i>key</i> - optional accessor function for sub-elements in the list<br>
+returns - the remainder of the list starting with the first matching element</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:member-if-not</font> (predicate list &key key)
+ (member nil list :test (if key
+ #'(lambda (x y)
+ (funcall predicate (funcall key y)))
+ #'(lambda (x y)
+ (funcall predicate y)))))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-member-if-not"></a>
+
+<hr>
+
+<h2>cl:member-if-not</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>member-if-not</b> <i>predicate list</i> [:key <i>key</i>])</nobr></dt>
+<dd><i>predicate</i> - a test function with one argument<br>
+<i>list</i> - the list to search<br>
+<i>key</i> - optional accessor function for sub-elements in the list<br>
+returns - the remainder of the list starting with the first non-matching element</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:member-if-not</font> (predicate list &key key)
+ (member nil list :test-not (if key
+ #'(lambda (x y)
+ (funcall predicate (funcall key y)))
+ #'(lambda (x y)
+ (funcall predicate y)))))))
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:member-if #'plusp '(-2 -1 0 1 2)) => (1 2) <font color="#008844">; 1 = first positive number</font>
+(cl:member-if-not #'minusp '(-2 -1 0 1 2)) => (0 1 2) <font color="#008844">; 0 = first non-negative number</font>
+</pre>
+
+<p>More test functions see <a href="predicates.htm">Predicates</a>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-list-accessor"></a>
+
+<hr>
+
+<h2>cl:list:accessor</h2>
+
+<hr>
+
+<p>The 'lists as sets' functions have common :test, <nobr>:test-not</nobr>
+and :key parameters:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:list:accessor</font> (test test-not &optional key)
+ (if (and test test-not)
+ (error <font color="#880000">"both :TEST and :TEST-NOT specified"</font>))
+ (if key
+ (cond (test `(lambda (x y)
+ (funcall ,test (funcall ,key x)
+ (funcall ,key y))))
+ (test-not `(lambda (x y)
+ (not (funcall ,test-not (funcall ,key x)
+ (funcall ,key y)))))
+ (t `(lambda (x y)
+ (eql (funcall ,key x) (funcall ,key y)))))
+ (cond (test `(lambda (x y)
+ (funcall ,test x y)))
+ (test-not `(lambda (x y)
+ (not (funcall ,test-not x y))))
+ (t `(lambda (x y)
+ (eql x y))))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-pushnew"></a>
+
+<hr>
+
+<h2>cl:pushnew</h2>
+
+<hr>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-union"></a>
+
+<hr>
+
+<h2>cl:union</h2>
+
+<hr>
+
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>union</b> <i>list1 list2</i> [{:test | :test-not} <i>test</i> :key <i>key</i>])</nobr></dt>
+<dd><i>listN</i> - a list of symbols or numbers<br>
+returns - the union of <i>list1</i> and <i>list2</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">union</font> (a b)
+ (let (result)
+ (dolist (element a)
+ (unless (member element result)
+ (push element result)))
+ (dolist (element b)
+ (unless (member element result)
+ (push element result)))
+ result))
+</pre>
+
+<p>The 'cl:union' function returns a list that contains every element that
+occurs in either 'list1' or 'list2'.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-intersection"></a>
+
+<hr>
+
+<h2>cl:intersection</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(intersection <i>list1 list2</i> [{:test | :test-not} <i>test</i> :key <i>key</i>])</nobr></dt>
+<dd><i>listN</i> - a list of symbols or numbers<br>
+returns - the intersection of <i>list1</i> and <i>list2</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">intersection</font> (a b)
+ (let (result)
+ (dolist (element a)
+ (when (member element b)
+ (push element result)))
+ result))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-set-difference"></a>
+
+<hr>
+
+<h2>cl:set-difference</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>set-difference</b> <i>list1 list2</i>)</nobr></dt>
+<dd><i>listN</i> - a list of symbols or numbers<br>
+returns - the set-difference of <i>list1</i> and <i>list2</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">set-difference</font> (a b)
+ (remove-if #'(lambda (element)
+ (member element b))
+ a))
+</pre>
+
+<p>An element of list1 appears in the result if and only if it does not
+match any element of list2.</p>
+
+<pre class="example">
+(set-difference '(1 2 3) '(2 3 4)) => (1)
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-set-exclusive-or"></a>
+
+<hr>
+
+<h2>cl:set-exclusive-or</h2>
+
+<hr>
+
+<p>The result contains precisely those elements of list1 and list2 that
+appear in no matching pair.</p>
+
+<pre class="example">
+(set-exclusive-or '(1 2 3) '(2 3 4)) => (1 4)
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-subsetp"></a>
+
+<hr>
+
+<h2>cl:subsetp</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>subsetp</b> <i>list1 list2</i>)</nobr></dt>
+<dd><i>listN</i> - a list of symbols or numbers<br>
+returns - <a href="t.htm"> T </a> if <i>list1</i> is a subset of <i>list2</i>, NIL otherwise</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">subsetp</font> (a b)
+ (let ((result t))
+ (dolist (element a)
+ (when (not (member element b)
+ (setf result nil)
+ (return))))
+ result))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
+
diff --git a/docsrc/xlisp/xlisp-doc/examples/macros.htm b/docsrc/xlisp/xlisp-doc/examples/macros.htm new file mode 100644 index 0000000..1781381 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/macros.htm @@ -0,0 +1,302 @@ +<html><head>
+
+<title>Macros</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Macro Programming</h1>
+
+<hr>
+
+<ul>
+<li><nobr><a href="#with-unique-names">with-unique-names</a> - create local <a href="../reference/gensym.htm">gensym</a> variables</nobr></li>
+</ul>
+
+<p><div class="box">
+
+<p><b>Note:</b> The best book for Lisp macro programming is Paul
+Graham's '<nobr>On Lisp</nobr>', available for free under:</p>
+
+<ul>
+<li><nobr><a href="http://www.paulgraham.com/onlisp.html"
+>http://www.paulgraham.com/onlisp.html</a></nobr></li>
+</ul>
+
+</div></p>
+
+<a name="with-unique-names"></a>
+
+<hr>
+
+<h2>with-unique-names</h2>
+
+<hr>
+
+<p>See <a href="http://www.cliki.net/WITH-UNIQUE-NAMES"
+>http://www.cliki.net/WITH-UNIQUE-NAMES</a>. This macro also appears in
+<nobr>Chapter 11</nobr> of Paul Graham's
+<nobr><a href="http://www.paulgraham.com/onlisp.html">On Lisp</a></nobr>
+under the name '<nobr>with-gensyms</nobr>'.</p>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<b>with-unique-names</b> (<i>symbols</i>) <i>body</i>)</nobr></dt>
+<dd><i>symbols</i> - a list of Lisp symbols, representing variable names<br>
+<i>body</i> - some Lisp code to execute<br>
+returns - the <i>body</i> with all <i>symbols</i> bound to different
+<a href="../reference/gensym.htm">gensym</a>s</dd>
+</dl>
+
+</div></p>
+
+<p>The '<nobr>with-unique-names</nobr>' macro helps to avoid name clashes in
+Lisp macros.</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">with-unique-names</font> (symbols &rest body)
+ `(let ,(mapcar #'(lambda (x) `(,x (gensym))) symbols) ,@body))
+</pre>
+
+<p>The '<nobr>with-unique-names</nobr>' macro belongs to the category of
+<nobr>write-only</nobr> code. <nobr>No matter</nobr> how you write it, it's
+nearly impossible to understand its meaning by reading the macro definition.
+<nobr>It's easier</nobr> to understand if you look at the macro
+expansion:</p>
+
+<pre class="example">
+> (macroexpand-1 '(with-unique-names (a b c)
+ `(let ((,a 1) (,b 2) (,c 3))
+ (list ,a ,b ,c))))
+
+(let ((a (gensym)) (b (gensym)) (c (gensym)))
+ `(let ((,a 1) (,b 2) (,c 3))
+ (list ,a ,b ,c)))
+</pre>
+
+<p>This translates in practice to the following idea:</p>
+
+<pre class="example">
+(let ((a (gensym)) (b (gensym)) (c (gensym))) <font color="#008844">; outside the expansion</font>
+ `(let ((<font color="#AA5500">gensym1</font> 1) (<font color="#AA5500">gensym2</font> 2) (<font color="#AA5500">gensym3</font> 3)) <font color="#008844">; inside the expansion</font>
+ (list <font color="#AA5500">gensym1 gensym2 gensym3</font>)))
+</pre>
+
+<p>The variable names 'a', 'b', and 'c' have been replaced inside the macro
+expansion by three <a href="../reference/gensym.htm">gensym</a>s. This way a
+variable name inside the macro expansion cannot accidentally collide with a
+variable of the same name in the environment of the macro's expansion like
+shown here:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">print-macro</font> (x) <font color="#008844">; bad example</font>
+ `(let ((<font color="#AA0000">macro-var</font> 'macro))
+ (print ,x)))
+
+> (let ((<font color="#AA0000">local-var</font> 'let)) <font color="#008844">; this works</font>
+ (print local-var)
+ (print-macro local-var))
+LET <font color="#008844">; printed by PRINT</font>
+LET <font color="#008844">; printed by PRINT-MACRO</font>
+
+> (let ((<font color="#AA0000">macro-var</font> 'let)) <font color="#008844">; this doesn't</font>
+ (print macro-var)
+ (print-macro macro-var))
+LET <font color="#008844">; printed by PRINT</font>
+MACRO <font color="#008844">; printed by PRINT-MACRO</font>
+</pre>
+
+<p>The reason for this behaviour is that the '<nobr>print-macro</nobr>'
+<nobr>expands to:</nobr></p>
+
+<pre class="example">
+> (let ((<font color="#AA0000">local-var</font> 'let)) <font color="#008844">; this works</font>
+ (print local-var)
+ (let ((<font color="#AA0000">macro-var</font> 'macro))
+ (print local-var)))
+LET <font color="#008844">; LOCAL-VAR inside the first LET</font>
+LET <font color="#008844">; LOCAL-VAR inside the second LET</font>
+
+> (let ((<font color="#AA0000">macro-var</font> 'let)) <font color="#008844">; this doesn't</font>
+ (print macro-var)
+ (let ((<font color="#AA0000">macro-var</font> 'macro))
+ (print macro-var)))
+LET <font color="#008844">; MACRO-VAR inside the first LET</font>
+MACRO <font color="#008844">; MACRO-VAR inside the second LET</font>
+</pre>
+
+<p>Now the same example with unique names. Note the
+<a href="..reference/backquote.htm">comma</a> before the
+'<nobr>macro-var</nobr>' inside the
+<nobr><a href="../reference/let.htm">let</a> form of the macro
+definition:</nobr></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">print-macro</font> (x) <font color="#008844">; good example</font>
+ (with-unique-names (<font color="#AA0000">macro-var</font>)
+ `(let ((,<font color="#AA0000">macro-var</font> 'macro))
+ (print ,x))))
+
+> (let ((<font color="#AA0000">macro-var</font> 'let)) <font color="#008844">; now it works</font>
+ (print macro-var)
+ (print-macro macro-var))
+LET <font color="#008844">; printed by PRINT</font>
+LET <font color="#008844">; printed by PRINT-MACRO</font>
+</pre>
+
+<p>The reason why it works is that the '<nobr>print-macro</nobr>' now
+<nobr>expands to:</nobr></p>
+
+<pre class="example">
+> (let ((<font color="#AA0000">macro-var</font> 'let)) <font color="#008844">; works</font>
+ (print macro-var)
+ (let ((<font color="#AA5500">gensym</font> 'macro))
+ (print macro-var)))
+LET <font color="#008844">; MACRO-VAR inside the first LET</font>
+LET <font color="#008844">; MACRO-VAR inside the second LET</font>
+</pre>
+
+<nobr>Now '<nobr>macro-var</nobr>' can even be used as a variable name
+inside the macro definition without colliding with the
+'<nobr>macro-var</nobr>' bound
+<nobr>by <a href="../reference/let.htm">let</a>:</nobr></nobr>
+
+<pre class="example">
+(defmacro <font color="#0000CC">print-macro</font> (x) <font color="#008844">; good example</font>
+ (with-unique-names (<font color="#AA0000">macro-var</font>)
+ `(let ((,<font color="#AA0000">macro-var</font> 'macro))
+ (print ,<font color="#AA0000">macro-var</font>)
+ (print ,x))))
+
+> (let ((<font color="#AA0000">macro-var</font> 'let)) <font color="#008844">; works</font>
+ (print macro-var)
+ (print-macro macro-var))
+LET <font color="#008844">; MACRO-VAR printed inside LET</font>
+MACRO <font color="#008844">; GENSYMed MACRO-VAR, printed inside PRINT-MACRO</font>
+LET <font color="#008844">; MACRO-VAR bound by LET, printed inside PRINT-MACRO</font>
+</pre>
+
+<p>The expansion of the '<nobr>print-macro</nobr>' shows why this works:</p>
+
+<pre class="example">
+> (let ((<font color="#AA0000">macro-var</font> 'let)) <font color="#008844">; works</font>
+ (print macro-var)
+ (let ((<font color="#AA5500">gensym</font> 'macro))
+ (print <font color="#AA5500">gensym</font>)
+ (print macro-var)))
+LET <font color="#008844">; MACRO-VAR printed inside LET</font>
+MACRO <font color="#008844">; GENSYMed MACRO-VAR printed inside PRINT-MACRO</font>
+LET <font color="#008844">; MACRO-VAR bound by LET, printed inside PRINT-MACRO</font>
+</pre>
+
+<p>You can give as many variable names as you like to
+'<nobr>with-unique-names</nobr>', the
+<a href="../reference/gensym.htm">gensym</a> management is done
+automatically:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">print-macro</font> (x y z)
+ (with-unique-names (a b c)
+ `(let ((,a 1) (,b 2) (,c 3))
+ (format t <font color="#880000">"outside: a: ~a b: ~a c: ~a~%"</font> ,x ,y ,z)
+ (format t <font color="#880000">" inside: a: ~a b: ~a c: ~a~%"</font> ,a ,b ,c))))
+
+> (let ((a 'a) (b 'b) (c 'c))
+ (print-macro a b c))
+outside: a: A b: B c: C
+ inside: a: 1 b: 2 c: 3
+</pre>
+
+<p>Two things you still have to care about:</p>
+
+<ol>
+
+<li><p>The 'unique names' should not use the same smbol names as the
+parameter variables of the macro, otherwise you will have the same
+'shadowing' effect like in ordinary Lisp functions. This is not a real
+problem because when writing a macro you can see the parameter names before
+your eyes, while you usually cannot see the variable names of the
+environment, where the macro will be expanded. <nobr>You also</nobr> do not
+have to care which variable names had been used in a macro if you call the
+macro from arbitrary Lisp code, where you usually cannot see the code of the
+macro definition.</p></li>
+
+<li><p>The local <a href="../reference/gensym.htm">gensym</a>ed variables
+now themselves must be expanded by writing a
+<a href="../reference/backquote.htm">comma</a> in front of each when they appear
+inside a <a href="../reference/backquote.htm">backquote</a> scope.
+This sometimes can lead to tricky situations, because the
+<a href="../reference/backquote.htm">comma</a> expansion of the symbol does not
+produce the variable's value, instead it produces the name of the
+<a href="../reference/gensym.htm">gensym</a>, which holds the value.
+<nobr>But this</nobr> is a general phenomenon of
+<a href="../reference/gensym.htm">gensym</a>s in Lisp macro programming
+and not a bug of the '<nobr>with-unique-names</nobr>' macro.</p></li>
+
+</ol>
+
+<p>The alternative would be writing:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">print-macro</font> (x y z)
+ (let ((a (gensym)) (b (gensym)) (c (gensym)))
+ `(let ((,a 1) (,b 2) (,c 3))
+ (format t <font color="#880000">"outside: a: ~a b: ~a c: ~a~%"</font> ,x ,y ,z)
+ (format t <font color="#880000">" inside: a: ~a b: ~a c: ~a~%"</font> ,a ,b ,c))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/math.htm b/docsrc/xlisp/xlisp-doc/examples/math.htm new file mode 100644 index 0000000..b1a6414 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/math.htm @@ -0,0 +1,824 @@ +<html><head>
+
+<title>Math</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Math</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#number-types">Number Types</a></nobr></li>
+<li><nobr><a href="#integer-limits">Integer Limits</a></nobr></li>
+<li><nobr><a href="#rounding-and-truncation">Rounding and Truncation</a></nobr></li>
+<ul>
+<li><nobr><a href="#cl-round">cl:round</a> - round towards the next integer</nobr></li>
+<li><nobr><a href="#cl-truncate">cl:truncate</a> - truncate towards zero</nobr></li>
+<li><nobr><a href="#cl-ceiling">cl:ceiling</a> - truncate towards positive infinity</nobr></li>
+<li><nobr><a href="#cl-floor">cl:floor</a> - truncate towards negative infinity</nobr></li>
+</ul>
+<li><nobr><li><nobr><a href="#remainder-and-modulus">Remainder and Modulus</a></nobr></li></nobr></li>
+<ul>
+<li><nobr><a href="#cl-rem">cl:rem</a></nobr></li>
+<li><nobr><a href="#cl-mod">cl:mod</a></nobr></li>
+</ul>
+<li><nobr>Power and Roots</nobr></li>
+<ul>
+<li><nobr><a href="#cl-exp">cl:exp</a> - compute 'e' to the power of 'x'</nobr></li>
+<li><nobr><a href="#cl-expt">cl:expt</a> - compute 'x' to the power of 'y'</nobr></li>
+<li><nobr><a href="#cl-log">cl:log</a></nobr></li>
+<li><nobr><a href="#cl-sqrt">cl:sqrt</a></nobr></li>
+</ul>
+</ol>
+
+<hr>
+
+<h2>Number Types</h2>
+
+<hr>
+
+<p>Nyquist/XLISP only knows two types of numers:</p>
+
+<ul>
+<li><nobr><b>fixnum</b> - integer numbers</nobr></li>
+<li><nobr><b>flonum</b> - floating-point numbers</nobr></li>
+</ul>
+
+<p>In Nyquist/XLISP, there are no ratios or complex numbers. Even if the
+math functions on this page are modelled after <nobr>Common Lisp</nobr>, no
+attempt is made to emulate these numbers.</p>
+
+<a name="integer-limits"></a>
+
+<hr>
+
+<h2>Integer Limits</h2>
+
+<hr>
+
+<pre class="example">
+(setq <font color="#AA5500">*most-positive-fixnum*</font> 2147483647)
+(setq <font color="#AA5500">*most-negative-fixnum*</font> -2147483648)
+</pre>
+
+<p><b>Note:</b> these are the limits for <nobr>32-bit</nobr> machines.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">fixnum-bits</font> ()
+ (dolist (bits '(15 31 63) nil)
+ (let ((fixnum (round (expt 2.0 bits))))
+ (and (plusp (1- fixnum))
+ (minusp fixnum)
+ (return (1+ bits))))))
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">fixnum-limits</font> ()
+ (if (dolist (bits '(15 31 63) nil)
+ (let* ((negative (round (expt 2.0 bits)))
+ (positive (1- negative)))
+ (when (and (plusp positive)
+ (minusp negative))
+ (setq most-positive-fixnum positive
+ most-negative-fixnum negative)
+ (return t))))
+ most-positive-fixnum
+ (error <font color="#880000">"fixnum limit not found"</font>)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="print-float"></a>
+
+<hr>
+
+<h2>print-float</h2>
+
+<hr>
+
+<p>The '<nobr>print-float</nobr>' function prints
+<nobr>floating-point</nobr> numbers ending in '.0' as
+<nobr>floating-point</nobr> numbers and not as integers:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">print-float</font> (item)
+ (if (not (floatp item))
+ item
+ (let ((string (format nil <font color="#880000">"~a"</font> item)))
+ (if (not (string-search <font color="#880000">"."</font> string))
+ (strcat string <font color="#880000">".0"</font>)
+ string))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="divide-float"></a>
+
+<hr>
+
+<h2>divide-float</h2>
+
+<hr>
+
+<p>An easy way to force a sequence of integers to be divided as floating
+point numbers is to insert the number 1.0 after the first argument in the
+list of arguments to the divider function or to explicitely convert the
+first argument into a floating point number by using the XLISP <a
+href="float.htm">float</a> function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">divide-float</font> (&rest args)
+ (if (null args)
+ (error <font color="#880000">"too few arguments"</font>)
+ (apply #'/ (cons (float (first args)) (rest args)))))
+</pre>
+
+<p>See <a href="apply.htm">apply</a>, <a href="cons.htm">cons</a>,
+<a href="defun.htm">defun</a>, <a href="error.htm">error</a>,
+<a href="first.htm">first</a>, <a href="float.htm">float</a>,
+<a href="if.htm">if</a>, <a href="null.htm">null</a>,
+<a href="rest.htm">rest</a>,
+<a href="lambda-keyword-rest.htm">&rest</a>.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(divide-float 1) => 1.0
+(divide-float 1 2) => 0.5
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="rounding-and-truncation"></a>
+
+<hr>
+
+<h2>Rounding and Truncation</h2>
+
+<hr>
+
+<p>The <a href="#cl-round">cl:round</a>,
+<a href="#cl-truncate">cl:truncate</a>,
+<a href="#cl-ceiling">cl:ceiling</a> and
+<a href="#cl-floor">cl:floor</a> functions divide a number by a divisor,
+returning a quotient and a remainder:</p>
+
+<p><div class="box">
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="#cl-round">cl:round</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="#cl-truncate">cl:truncate</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="#cl-ceiling">cl:ceiling</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+<tr valign="top">
+ <td align="right"><nobr>(<a href="#cl-floor">cl:floor</a> </nobr></td>
+ <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+ <td><nobr> ⇒ </nobr></td>
+ <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+</tbody></table></p>
+
+<p><nobr>
+<i>quotient</i> * <i>divisor</i> + <i>remainder</i> = <i>number</i></nobr></p>
+
+</div></p>
+
+<p>The 'quotient' always represents a mathematical integer. <nobr>The
+'remainder'</nobr> is an integer if both 'number' and 'divisor' arguments
+are integers, and a <nobr>floating-point</nobr> number if either the
+'number' or the 'divisor' or both are <nobr>floating-point</nobr>
+numbers.</p>
+
+<p>With Nyquist/XLISP, the 'quotient' is always directly returned by the
+function, while a list:</p>
+
+<pre class="example">
+(<font color="#0000CC">quotient remainder</font>)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="values.htm#cl-global-multiple-values">cl:*multiple-values*</a> is
+set to <a href="../reference/t.htm"> T </a> to signal that
+<a href="values.htm">Multiple Values</a> are returned.</p>
+
+Examples:
+
+<pre class="example">
+(cl:round 3.5) => 4 <font color="#008844">; *rslt* = ( 4 -0.5)</font>
+(cl:truncate 3.5) => 3 <font color="#008844">; *rslt* = ( 3 0.5)</font>
+(cl:ceiling 3.5) => 4 <font color="#008844">; *rslt* = ( 4 -0.5)</font>
+(cl:floor 3.5) => 3 <font color="#008844">; *rslt* = ( 3 0.5)</font>
+
+(cl:round -3.5) => -4 <font color="#008844">; *rslt* = (-4 0.5)</font>
+(cl:truncate -3.5) => -3 <font color="#008844">; *rslt* = (-3 -0.5)</font>
+(cl:ceiling -3.5) => -3 <font color="#008844">; *rslt* = (-3 -0.5)</font>
+(cl:floor -3.5) => -4 <font color="#008844">; *rslt* = (-4 0.5)</font>
+</pre>
+
+Force integer division:
+
+<pre class="example">
+(cl:truncate 3.0 2.0) => 1
+(/ (truncate 3.0) (truncate 2.0)) => 1
+(/ 3 4) => 1
+</pre>
+
+<p><div class="box">
+
+<p><b>Implementation Notes</b></p>
+
+<pre class="example">
+(defun <font color="#0000CC">name</font> (number &optional (divisor (if (<font color="#AA0000">integerp</font> number) 1 1.0)))
+ ... )
+</pre>
+
+<p>The <a href="../reference/integerp.htm">integerp</a> test in the
+parameter list signals an error if the 'number' argument is not a number,
+also the <nobr><a href="../reference/division.htm"> / </a>
+[division]</nobr> function signals errors if the 'divisor' argument is zero
+or not a number, so we do not explicitely need to test the arguments.</p>
+
+<p>The <nobr><a href="#cl-ceiling">cl:ceiling</a></nobr> and <nobr><a
+href="#cl-floor">cl:floor</a></nobr> functions test if 'number' is an
+integer multiple of 'divisor' by comparing the results of an integer
+division and a <nobr>floating-point</nobr> division:</p>
+
+<pre class="example">
+(let ((<font color="#AA0000">i-quotient</font> (/ (truncate number) (truncate divisor)))
+ (<font color="#AA0000">f-quotient</font> (/ (float number) divisor)))
+ (if (= <font color="#AA0000">i-quotient f-quotient</font>)
+ ...
+</pre>
+
+<p>I'm not sure if this really catches all cases <nobr>[e.g.
+regarding</nobr> floating point precision], but have found no problems so
+far.</p>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-round"></a>
+
+<hr>
+
+<h2>cl:round</h2>
+
+<hr>
+
+<p>The '<nobr>cl:round</nobr>' function truncates towards the next
+integer:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>round</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of runding the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the round operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:round</font> (number &optional (divisor
+ (if (integerp number) 1 1.0)
+ divisor-p))
+ (let* ((x (/ (float number) divisor))
+ (quotient (cond ((and (not divisor-p) (integerp number)) number)
+ ((= number divisor) 1)
+ ((plusp x) (truncate (+ x 0.5)))
+ ((= (- x 0.5) (truncate (- x 0.5)))
+ (if (minusp x)
+ (1- (truncate x))
+ (truncate x)))
+ (t (truncate (- x 0.5))))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The '<nobr>cl:round</nobr>' function computes a quotient that has been rounded to the
+nearest mathematical integer. <nobr>If the</nobr> mathematical quotient is
+exactly halfway between two integers, [that is, it has the form
+<nobr>'integer+1/2']</nobr>, then the quotient has been rounded to the even
+[divisible <nobr>by two]</nobr> integer. <nobr>See
+<a href="#rounding-and-truncation">Rounding and Truncation</a></nobr>
+above for more details.</p>
+
+<pre class="example">
+(round 3.5) => 4
+(round -3.5) => -3
+
+(cl:round 3.5) => 4 <font color="#008844">; *rslt* = ( 4 -0.5)</font>
+(cl:round -3.5) => -4 <font color="#008844">; *rslt* = (-4 0.5)</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-truncate"></a>
+
+<hr>
+
+<h2>cl:truncate</h2>
+
+<hr>
+
+<p>The '<nobr>cl:truncate</nobr>' function truncates towards zero:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>truncate</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of truncating the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the truncate operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:truncate</font> (number &optional (divisor (if (integerp number) 1 1.0)))
+ (let ((quotient (truncate (/ (float number) divisor))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The '<nobr>cl:truncate</nobr>' function computes a quotient that has been
+truncated towards zero. That is, the quotient represents the mathematical
+integer of the same sign as the mathematical quotient, and that has the
+greatest integral magnitude not greater than that of the mathematical
+quotient. <nobr>See
+<a href="#rounding-and-truncation">Rounding and Truncation</a></nobr>
+above for more details.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-ceiling"></a>
+
+<hr>
+
+<h2>cl:ceiling</h2>
+
+<hr>
+
+<p>The '<nobr>cl:ceiling</nobr>' function truncates towards positive
+infinity:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>ceiling</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of truncating the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the truncate operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:ceiling</font> (number &optional (divisor
+ (if (integerp number) 1 1.0)
+ divisor-p))
+ (let ((quotient
+ (cond ((and (not divisor-p) (integerp number)) number)
+ ((= number divisor) 1)
+ (t (let ((i-quotient (/ (truncate number) (truncate divisor)))
+ (f-quotient (/ (float number) divisor)))
+ (if (or (= i-quotient f-quotient) <font color="#008844">; integer result</font>
+ (not (plusp f-quotient)))
+ (truncate f-quotient)
+ (1+ (truncate f-quotient))))))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The '<nobr>cl:ceiling</nobr>' function computes a quotient that has been
+truncated toward positive infinity. That is, the quotient represents the
+smallest mathematical integer that is not smaller than the mathematical
+result. <nobr>See
+<a href="#rounding-and-truncation">Rounding and Truncation</a></nobr>
+above for more details.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-floor"></a>
+
+<hr>
+
+<h2>cl:floor</h2>
+
+<hr>
+
+<p>The '<nobr>cl:floor</nobr>' function truncates towards negative infinity:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>floor</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td valign="top"><nobr>returns</nobr></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the result of truncating the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+ <td></td>
+ <td valign="top"><nobr> - </nobr></td>
+ <td width="100%">the remainder of the truncate operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:floor</font> (number &optional (divisor
+ (if (integerp number) 1 1.0)
+ divisor-p))
+ (let ((quotient
+ (cond ((and (not divisor-p) (integerp number)) number)
+ ((= number divisor) 1)
+ (t (let ((i-quotient (/ (truncate number) (truncate divisor)))
+ (f-quotient (/ (float number) divisor)))
+ (if (or (= i-quotient f-quotient) <font color="#008844">; integer result</font>
+ (not (minusp f-quotient)))
+ (truncate f-quotient)
+ (1- (truncate f-quotient))))))))
+ (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+ <font color="#AA5500">cl:*multiple-values*</font> t)
+ quotient))
+</pre>
+
+<p>The <nobr>'cl:floor</nobr>' function computes a quotient that has been
+truncated toward negative infinity. That is, the quotient represents the
+largest mathematical integer that is not larger than the mathematical
+quotient. <nobr>See
+<a href="#rounding-and-truncation">Rounding and Truncation</a></nobr>
+above for more details.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="remainder-and-modulus"></a>
+
+<hr>
+
+<h2>Remainder and Modulus</h2>
+
+<hr>
+
+<p>The <a href="#cl-mod">cl:mod</a> and <a href="#cl-rem">cl:rem</a>
+function are generalizations of the modulus and remainder functions.
+<nobr>The <a href="#cl-mod">cl:mod</a></nobr> function performs the
+<a href="#cl-floor">cl:floor</a> operation on its arguments and returns the
+remainder of the <a href="#cl-floor">cl:floor</a> operation.
+<nobr>The <a href="#cl-rem">cl:rem</a></nobr> function performs the
+<a href="cl-truncate">cl:truncate</a> operation on its arguments and returns
+the remainder of the <a href="cl-truncate">cl:truncate</a> operation.
+<nobr>The <a href="#cl-mod">cl:mod</a></nobr> and
+<a href="#cl-rem">cl:rem</a> functions are the modulus and remainder
+functions when the 'number' and 'divisor' arguments both are integers.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-rem"></a>
+
+<hr>
+
+<h2>cl:rem</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>rem</b> <i>number divisor</i>)</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+<i>divisor</i> - an integer or floating-point number<br>
+returns - the remainder of a <a href="cl-truncate">cl:truncate</a> operation</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:rem</font> (number divisor)
+ (if (= (abs number) (abs divisor))
+ (if (and (integerp number) (integerp divisor)) 0 0.0)
+ (let ((quotient (truncate (/ (float number) divisor))))
+ (- number (* quotient divisor)))))
+</pre>
+
+<p>The '<nobr>cl:rem</nobr>' function performs the
+<a href="cl-truncate">cl:truncate</a> operation on its arguments and returns
+the remainder of the <a href="cl-truncate">cl:truncate</a> operation.
+<nobr>The result</nobr> is either zero or an integer or
+<nobr>floating-point</nobr> number with the same sign as the 'number'
+argument. <nobr>If both</nobr> arguments are integer numbers, the
+'<nobr>cl:rem</nobr>' function is equal to the mathematical remainder
+function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-mod"></a>
+
+<hr>
+
+<h2>cl:mod</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>mod</b> <i>number divisor</i>)</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+<i>divisor</i> - an integer or floating-point number<br>
+returns - the remainder of a <a href="#cl-floor">cl:floor</a> operation</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:mod</font> (number divisor)
+ (if (= (abs number) (abs divisor))
+ (if (and (integerp number) (integerp divisor)) 0 0.0)
+ (let* ((i-quotient (/ (truncate number) (truncate divisor)))
+ (f-quotient (/ (float number) divisor))
+ (quotient (if (or (= i-quotient f-quotient) <font color="#008844">; integer result</font>
+ (not (minusp f-quotient)))
+ (truncate f-quotient)
+ (1- (truncate f-quotient)))))
+ (- number (* quotient divisor)))))
+</pre>
+
+<p>The '<nobr>cl:mod</nobr>' function performs the
+<a href="#cl-floor">cl:floor</a> operation on its arguments and returns the
+remainder of the <a href="#cl-floor">cl:floor</a> operation. <nobr>The
+result</nobr> is either zero or an integer or <nobr>floating-point</nobr>
+number with the same sign as the 'divisor' argument. <nobr>If both</nobr>
+arguments are integer numbers, the '<nobr>cl:rem</nobr>' function is equal
+to the mathematical modulus function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-exp"></a>
+
+<hr>
+
+<h2>cl:exp</h2>
+
+<hr>
+
+<p>The '<nobr>cl:exp</nobr>' function does the same as the Nyquist/XLISP
+<a href="../reference/exp.htm">exp</a> function, but it also accepts
+integer numbers as argument:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>exp</b> <i>power</i>)</dt>
+<dd><i>power</i> - an integer or floating-point number<br>
+returns - the result of <nobr>'e' [2.7128]</nobr> to the power of <i>power</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:exp</font> (x)
+ (exp (float x)))
+</pre>
+
+<p>The '<nobr>cl:exp</nobr>' function computes <nobr>'e' [2.7128]</nobr>
+raised to the specified 'power'. <nobr>The result</nobr> is always a
+<nobr>floating-point</nobr> number.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-expt"></a>
+
+<hr>
+
+<h2>cl:expt</h2>
+
+<hr>
+
+<p>The '<nobr>cl:expt</nobr>' function computes the result of 'x' to the
+power <nobr>of 'y'</nobr>:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>expt</b> <i>base power</i>)</dt>
+<dd><i>base</i> - the base<br>
+<i>power</i> - the exponent<br>
+returns - the result of <i>base</i> to the power of <i>power</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:expt</font> (x y)
+ (let ((power (expt (float x) y)))
+ (if (and (integerp x) (integerp y))
+ (round power)
+ power)))
+</pre>
+
+<p>See <a href="../reference/and.htm">and</a>,
+<a href="../reference/defun.htm">defun</a>,
+<a href="../reference/expt.htm">expt</a>,
+<a href="../reference/float.htm">float</a>,
+<nobr><a href="../reference/if.htm"> if </a></nobr>,
+<a href="../reference/integerp.htm">integerp</a>,
+<a href="../reference/let.htm">let</a>,
+<a href="../reference/power.htm">power</a>,
+<a href="../reference/round.htm">round</a>.</p>
+
+<p>The '<nobr>cl:expt</nobr>' function accepts integer and floating point
+numbers as arguments. <nobr>If both</nobr> arguments are integer numbers,
+the result will be an integer number, <nobr>if one</nobr> or both arguments
+are <nobr>floating-point</nobr> numbers, the result will be a
+<nobr>floating-point</nobr> number. <nobr>In contrast</nobr> to the
+Nyquist/XLISP <a href="../reference/expt.htm">expt</a> function, the
+'<nobr>cl:expt</nobr>' function specifies exactly two arguments.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-log"></a>
+
+<hr>
+
+<h2>cl:log</h2>
+
+<hr>
+
+<p>The '<nobr>cl:log</nobr>' function does the same as the Nyquist/XLISP
+<a href="../reference/log.htm">log</a> function, but also accepts
+integer numbers and has an optional 'base' argument:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>log</b> <i>number</i> [<i>base</i>])</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+<i>base</i> - an integer or floating-point number<br>
+returns - the the logarithm of <i>number</i> in base <i>base</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:log</font> (number &optional base)
+ (if base
+ (if (zerop base)
+ 0.0
+ (/ (log (float number)) (log (float base))))
+ (log (float number))))
+</pre>
+
+<p>The '<nobr>cl:log</nobr>' function returns the logarithm of 'number' in
+base 'base'. <nobr>If 'base'</nobr> is not supplied its value <nobr>is
+'e'</nobr>, the base of the natural logarithms. <nobr>If the</nobr> 'base'
+argument is zero, then 'cl:log' returns zero. <nobr>The result</nobr> is
+always a <nobr>floating-point</nobr> number.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-sqrt"></a>
+
+<hr>
+
+<h2>cl:sqrt</h2>
+
+<hr>
+
+<p>The '<nobr>cl:sqrt</nobr>' function does the same as the Nyquist/XLISP
+<a href="../reference/sqrt.htm">sqrt</a> function, but it also accepts
+integer numbers as argument:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>sqrt</b> <i>number</i>)</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+returns - the square root of <i>number</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:sqrt</font> (x)
+ (sqrt (float x)))
+</pre>
+
+<p><nobr>The result</nobr> is always a <nobr>floating-point</nobr>
+number.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/octal.htm b/docsrc/xlisp/xlisp-doc/examples/octal.htm new file mode 100644 index 0000000..f72ba4d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/octal.htm @@ -0,0 +1,148 @@ +<html><head>
+
+<title>Octal Integer Numbers</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Octal Integer Numbers</h1>
+
+<hr>
+
+<p>XLISP provides the <a href="../manual/xlisp.htm#octal">#o</a>
+<nobr>read-macro</nobr> for octal numbers:</p>
+
+<pre class="example">
+#o0 => 0 #o10 => 8 #o20 => 16
+#o1 => 1 #o11 => 9 #o21 => 17
+#o2 => 2 #o12 => 10 #o22 => 18
+#o3 => 3 #o13 => 11 #o23 => 19
+#o4 => 4 #o14 => 12 #o24 => 20
+#o5 => 5 #o15 => 13 #o25 => 21
+#o6 => 6 #o16 => 14 #o26 => 22
+#o7 => 7 #o17 => 15 #o27 => 23
+</pre>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>oct-string</b> <i>integer</i> [<i>all</i>])</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>all</i> - a boolean expression<br>
+returns - the <i>integer</i> in octal form as string</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">oct-string</font> (integer &optional all)
+ (if (integerp integer)
+ (let ((fmt (if all
+ (or (dolist (bits '(16 32 64 128) nil)
+ (let ((fixnum (round (expt 2.0 (1- bits)))))
+ (and (plusp (1- fixnum))
+ (minusp fixnum)
+ (return (format nil <font color="#880000">"%.~ao"</font>
+ (1+ (/ bits 3)))))))
+ (error <font color="#880000">"integer limit not found"</font>))
+ <font color="#880000">"%o"</font>)))
+ (progv '(<font color="#AA5500">*integer-format*</font>) (list fmt)
+ (format nil <font color="#880000">"~a"</font> integer)))
+ (error <font color="#880000">"not an integer"</font> integer)))
+</pre>
+
+<p>The '<nobr>oct-string</nobr>' function converts the 'integer' argument
+into octal form and returns is as a string. <nobr>If the</nobr>
+optional 'all' argument is not given or
+<a href="../reference/nil.htm">NIL</a>, leading zeros are not included in
+the string. <nobr>If the</nobr> optional 'all' argument is
+<nobr>non-<a href="../reference/nil.htm">NIL</a></nobr>, all digits of the
+internal representation of the 'integer' argument, including leading zeros,
+are contained in the string. This is useful for debugging integer overflow
+and <nobr>bit-wise</nobr> functions.</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>oct</b> <i>integer</i> [<i>all</i>])</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>all</i> - a boolean expression<br>
+prints - the <i>integer</i> in octal form<br>
+returns - the <i>integer</i> argument</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">oct</font> (integer &optional all)
+ (if (integerp integer)
+ (format t <font color="#880000">"#o~a~%"</font> (oct-string integer all))
+ (format t <font color="#880000">";; not an integer~%"</font>))
+ integer)
+</pre>
+
+<p>The 'oct' function prints the 'integer' argument in octal form on
+the screen. Together with the
+<a href="../manual/xlisp.htm#octal">#o</a> <nobr>read-macro</nobr>
+this can be used for interactive octal computations.</p>
+
+<pre class="example">
+> (oct 12345678)
+#o57060516
+12345678
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/posix-chars.htm b/docsrc/xlisp/xlisp-doc/examples/posix-chars.htm new file mode 100644 index 0000000..9e6c4e0 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/posix-chars.htm @@ -0,0 +1,459 @@ +<html><head>
+
+<title>Characters and Strings</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>POSIX Character Classes</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#posix-character-classes">POSIX Character Classes</a></nobr></li>
+<li><nobr><a href="#internal-functions">Internal Functions</a></nobr></li>
+<li><nobr><a href="#user-functions">User Functions</a></nobr></li>
+</ol>
+
+<hr>
+
+<h2>POSIX Character Classes</h2>
+
+<hr>
+
+<p>The functions on this page implement tests for the standard POSIX
+character classes, where all functions return the tested character if the
+test succeeds, or <a href="../reference/nil.htm">NIL</a></nobr> if the test
+fails.</p>
+
+<p>The <nobr>built-in</nobr> XLISP character test functions
+<a href="../reference/upper-case-p.htm">upper-case-p</a>,
+<a href="../reference/lower-case-p.htm">lower-case-p</a>,
+<a href="../reference/both-case-p.htm">both-case-p</a>,
+<a href="../reference/alphanumericp.htm">alphanumericp</a>, return the
+boolean values <a href="../reference/t.htm"> T </a> or
+<a href="../reference/nil.htm">NIL</a> instead of the tested character,
+while <a href="../reference/digit-char-p.htm">digit-char-p</a> returns an
+integer <nobr>or <a href="../reference/nil.htm">NIL</a></nobr>, what is
+handy if you want to convert arbitrary Lisp symbols into numbers without
+producing an error, but all this is impractical for writing a string
+parser.</p>
+
+<p><nobr>The <a href="#internal-functions">Internal Functions</a></nobr>
+do not check if the argument is a character and therefore are faster than
+the <nobr><a href="#user-functions">User Functions</a></nobr>. Also note
+that XLISP is limited to ASCII characters, so there is no way to find out if
+an unicode character is upper- or lowercase if the character code is greater
+than <nobr>ASCII 127</nobr>.</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td colspan="3"><nobr><b>POSIX</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><b>Internal</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><b>User Function</b></nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>alnum</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-alnum-p">char:alnum-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#alnum-character-p">alnum-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>alphanumeric = [a-z], [A-Z], [0-9]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>alpha</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-alpha-p">char:alpha-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#alpha-character-p">alpha-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>alphabetic = [a-z], [A-Z]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>blank</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-blank-p">char:blank-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#blank-character-p">blank-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>space and horizontal-tab</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>cntrl</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-cntrl-p">char:cntrl-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#cntrl-character-p">cntrl-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>code-chars 0-31 and 127</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>digit</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-digit-p">char:digit-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#digit-character-p">digit-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>decimal = [0-9]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>graph</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-graph-p">char:graph-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#graph-character-p">graph-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>graphical = alnum + punct</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>lower</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-lower-p">char:lower-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#lower-character-p">lower-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>lowercase = [a-z]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>print</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-print-p">char:print-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#print-character-p">print-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>printable = alnum + punct + space</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>punct</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-punct-p">char:punct-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#punct-character-p">punct-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>punctuation marks</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>space</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-space-p">char:space-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#space-character-p">space-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>characters producing whitespace</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>upper</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-upper-p">char:upper-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#upper-character-p">upper-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>uppercase = [A-Z]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>xdigit</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-xdigit-p">char:xdigit-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#xdigit-character-p">xdigit-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>hexadecimal = [0-9], [a-f], [A-F]</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p>The main difference is:</p>
+
+<pre class="example">
+> (char:alnum-p 'nonsense-value)
+<font color="#AA0000">error: bad argument type - NONSENSE-VALUE</font>
+
+> (alnum-character-p 'nonsense-value)
+NIL
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="internal-functions"></a>
+
+<hr>
+
+<h2>Internal Functions</h2>
+
+<hr>
+
+<p>The internal functions are based on <nobr>built-in</nobr> XLISP
+functions, there are no external dependencies.</p>
+
+<a name="char-alnum-p"></a>
+
+<pre class="example">
+<font color="#008844">;; alphanumeric characters = a-z, A-z, 0-9</font>
+
+(defun <font color="#0000CC">char:alnum-p</font> (char)
+ (and (alphanumericp char)
+ char))
+<a name="char-alpha-p"></a>
+<font color="#008844">;; alphabetic characters = a-z, A-Z</font>
+
+(defun <font color="#0000CC">char:alpha-p</font> (char)
+ (and (both-char-p char)
+ char))
+<a name="char-blank-p"></a>
+<font color="#008844">;; blanks = space and horizontal-tab</font>
+
+(defun <font color="#0000CC">char:blank-p</font> (char)
+ (and (or (char= char #\Space)
+ (char= char #\Tab))
+ char))
+<a name="char-cntrl-p"></a>
+<font color="#008844">;; control characters = code-chars 0-31 and 127</font>
+
+(defun <font color="#0000CC">char:cntrl-p</font> (char)
+ (let ((code (char-code char)))
+ (and (or (<= 0 code 31)
+ (= code 127))
+ char)))
+<a name="char-digit-p"></a>
+<font color="#008844">;; decimal digits = 0-9</font>
+
+(defun <font color="#0000CC">char:digit-p</font> (char)
+ (and (digit-char-p char)
+ char))
+<a name="char-graph-p"></a>
+<font color="#008844">;; graphical characters = alnum + punct</font>
+
+(defun <font color="#0000CC">char:graph-p</font> (char)
+ (and (<= 33 (char-code char) 126)
+ char))
+<a name="char-lower-p"></a>
+<font color="#008844">;; lowercase characters = a-z</font>
+
+(defun <font color="#0000CC">char:lower-p</font> (char)
+ (and (lower-case-p char)
+ char))
+<a name="char-print-p"></a>
+<font color="#008844">;; printable characters = alnum + punct + space</font>
+
+(defun <font color="#0000CC">char:print-p</font> (char)
+ (and (<= 32 (char-code char) 126)
+ char))
+<a name="char-punct-p"></a>
+<font color="#008844">;; punctuation marks</font>
+
+(defun <font color="#0000CC">char:punct-p</font> (char)
+ (let ((code (char-code char)))
+ (and (or (<= 33 code 47) <font color="#008844">; ! " # $ % & ' ( ) * + , - . /</font>
+ (<= 58 code 64) <font color="#008844">; : ; < = > ? @</font>
+ (<= 91 code 96) <font color="#008844">; [ \ ] ^ _ `</font>
+ (<= 123 code 126)) <font color="#008844">; { | } ~</font>
+ char)))
+<a name="char-space-p"></a>
+<font color="#008844">;; characters producing whitespace</font>
+<font color="#008844">;;</font>
+<font color="#008844">;; 9 = horizontal tab 10 = line feed 11 = vertical tab</font>
+<font color="#008844">;; 12 = form feed 13 = carriage return 32 = space</font>
+
+(defun <font color="#0000CC">char:space-p</font> (char)
+ (and (member (char-code char) '(9 10 11 12 13 32))
+ char))
+<a name="char-upper-p"></a>
+<font color="#008844">;; uppercase characters = A-Z</font>
+
+(defun <font color="#0000CC">char:upper-p</font> (char)
+ (and (upper-case-p char)
+ char))
+<a name="char-xdigit-p"></a>
+<font color="#008844">;; hexadecimal digits = 0-9, a-f, A-F</font>
+
+(defun <font color="#0000CC">char:xdigit-p</font> (char)
+ (and (or (digit-char-p char)
+ (let ((code (char-code char)))
+ (or (<= 65 code 70) <font color="#008844">; A-Z</font>
+ (<= 97 code 102)))) <font color="#008844">; a-z</font>
+ char))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="user-functions"></a>
+
+<hr>
+
+<h2>User Functions</h2>
+
+<hr>
+
+<p>The user functions are based on the
+<nobr><a href="#internal-functions">Internal Functions</a></nobr> above.
+There are no other dependencies.</p>
+
+<a name="alnum-character-p"></a>
+
+<pre class="example">
+<font color="#008844">;; alphanumeric characters = a-z, A-z, 0-9</font>
+
+(defun <font color="#0000CC">alnum-character-p</font> (char)
+ (and (characterp char)
+ (char:alnum-p char)))
+<a name="alpha-character-p"></a>
+<font color="#008844">;; alphabetic characters = a-z, A-Z</font>
+
+(defun <font color="#0000CC">alpha-character-p</font> (char)
+ (and (characterp char)
+ (char:alpha-p char)))
+<a name="blank-character-p"></a>
+<font color="#008844">;; blanks = space and horizontal-tab</font>
+
+(defun <font color="#0000CC">blank-character-p</font> (char)
+ (and (characterp char)
+ (char:blank-p char)))
+<a name="cntrl-character-p"></a>
+<font color="#008844">;; control characters = code-chars 0-31 and 127</font>
+
+(defun <font color="#0000CC">cntrl-character-p</font> (char)
+ (and (characterp char)
+ (char:cntrl-p char)))
+<a name="digit-character-p"></a>
+<font color="#008844">;; decimal digits = 0-9</font>
+
+(defun <font color="#0000CC">digit-character-p</font> (char)
+ (and (characterp char)
+ (char:digit-p char)))
+<a name="graph-character-p"></a>
+<font color="#008844">;; graphical characters = alnum + punct</font>
+
+(defun <font color="#0000CC">graph-character-p</font> (char)
+ (and (characterp char)
+ (char:graph-p char)))
+<a name="lower-character-p"></a>
+<font color="#008844">;; lowercase characters = a-z</font>
+
+(defun <font color="#0000CC">lower-character-p</font> (char)
+ (and (characterp char)
+ (char:lower-p char)))
+<a name="print-character-p"></a>
+<font color="#008844">;; printable characters = alnum + punct + space</font>
+
+(defun <font color="#0000CC">print-character-p</font> (char)
+ (and (characterp char)
+ (char:print-p char)))
+<a name="punct-character-p"></a>
+<font color="#008844">;; punctuation marks</font>
+
+(defun <font color="#0000CC">punct-character-p</font> (char)
+ (and (characterp char)
+ (char:punct-p char)))
+<a name="space-character-p"></a>
+<font color="#008844">;; characters producing whitespace</font>
+
+(defun <font color="#0000CC">space-character-p</font> (char)
+ (and (characterp char)
+ (char:space-p char)))
+<a name="upper-character-p"></a>
+<font color="#008844">;; uppercase characters = A-Z</font>
+
+(defun <font color="#0000CC">upper-character-p</font> (char)
+ (and (characterp char)
+ (char:upper-p char)))
+<a name="xdigit-character-p"></a>
+<font color="#008844">;; hexadecimal digits = 0-9, a-f, A-F</font>
+
+(defun <font color="#0000CC">xdigit-character-p</font> (char)
+ (and (characterp char)
+ (char:xdigit-p char)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/predicates.htm b/docsrc/xlisp/xlisp-doc/examples/predicates.htm new file mode 100644 index 0000000..5846f2d --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/predicates.htm @@ -0,0 +1,526 @@ +<html><head>
+
+<title>Predicates</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Predicates and Comparison</h1>
+
+<hr>
+
+<p>Lisp has extensive support for <nobr>run-time</nobr> tests.</p>
+
+<p><nobr><b>Generalized Lisp Functions</b> - slower than the build-ins, but no errors</nobr></p>
+
+<ol>
+<li><nobr><a href="#built-in-xlisp-functions">Built-in XLISP Functions</a></nobr></li>
+<li><nobr>Generalized Comparison - one or more arguments</nobr></li>
+<ul>
+<li><nobr><a href="#equalp">equalp</a> - compares expressions with 'equality' functions.</nobr></li>
+</ul>
+<li><nobr>Symbol Predicates - one argument</nobr></li>
+<ul>
+<li><nobr><a href="#variablep">variablep</a> - is this a symbol with a variable value bound to it?</nobr></li>
+<li><nobr><a href="#functionp">functionp</a> - is this a function or a symbol with a function value bound to it?</nobr></li>
+<li><nobr><a href="#specialp">specialp</a> - is this a special form or a symbol with a special form bound to it?</nobr></li>
+<li><nobr><a href="#subrp">macrop</a> - is this a Lisp macro or a symbol with a Lisp macro bound to it?</nobr></li>
+</ul>
+<li><nobr>Function Predicates - one argument</nobr></li>
+<ul>
+<li><nobr><a href="#subrp">subrp</a> - is this a build-in function?</nobr></li>
+<li><nobr><a href="#fsubrp">fsubrp</a> - is this a build-in special form?</nobr></li>
+<li><nobr><a href="#closurep">closurep</a> - is this a user-defined function?</nobr></li>
+</ul>
+<li><nobr>Character Predicates - one argument</nobr></li>
+<ul>
+<li><nobr><a href="strings.htm#posix">POSIX Character Classes</a></nobr></li>
+</ul>
+</ol>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="built-in-xlisp-functions"></a>
+
+<hr>
+
+<h2>Built-in XLISP Functions</h2>
+
+<hr>
+
+<ol>
+<li><nobr><b>Boolean Predicates</b> - one argument [all types]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/not.htm">not</a> - does this expression evaluate to false?</nobr></li>
+</ul>
+<li><nobr><b>Generalized Comparison</b> - two arguments [all types]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/eq.htm">eq</a> - are the expressions identical?</nobr></li>
+<li><nobr><a href="../reference/eql.htm">eql</a> - are the expressions identical or equal numbers?</nobr></li>
+<li><nobr><a href="../reference/equal.htm">equal</a> - do the <a href="../reference/print.htm">print</a>ed expressions look the same?</nobr></li>
+</ul>
+<li><nobr><b>Type Predicates</b> - one argument [all types]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/atom.htm">atom</a> - is this an atom?</nobr></li>
+<li><nobr><a href="../reference/symbolp.htm">symbolp</a> - is this a symbol?</nobr></li>
+<ul>
+<li><nobr><b>Symbol Predicates</b> - one argument [error if not a symbol]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/boundp.htm">boundp</a> - has the symbol a variable value?</nobr></li>
+<li><nobr><a href="../reference/fboundp.htm">fboundp</a> - has the symbol a function value?</nobr></li>
+</ul>
+</ul>
+<li><nobr><a href="../reference/numberp.htm">numberp</a> - is this a number?</nobr></li>
+<ul>
+<li><nobr><b>Number Predicates</b> - one argument [error if not a number]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/plusp.htm">plusp</a> - is the number positive?</nobr></li>
+<li><nobr><a href="../reference/minusp.htm">minusp</a> - is the number negative?</nobr></li>
+<li><nobr><a href="../reference/zerop.htm">zerop</a> - is the number equal to zero?</nobr></li>
+<li><nobr><a href="../reference/integerp.htm">integerp</a> - is the number an integer?</nobr></li>
+<ul>
+<li><nobr><b>Integer Predicates</b> - one argument [error if not an integer]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/evenp.htm">evenp</a> - is the integer even?</nobr></li>
+<li><nobr><a href="../reference/oddp.htm">oddp</a> - is the integer odd?</nobr></li>
+</ul>
+</ul>
+<li><nobr><a href="../reference/floatp.htm">floatp</a> - is the number a floating-point number?</nobr></li>
+</ul>
+<li><nobr><b>Numerical Comparison</b> - one or more arguments [error if not numbers only]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/number-lessp.htm"> < </a> - true if all numbers are monotonically increasing</nobr></li>
+<li><nobr><a href="../reference/number-not-greaterp.htm"> <= </a> - true if all numbers are monotonically nondecreasing</nobr></li>
+<li><nobr><a href="../reference/number-equal.htm"> = </a> - true if all all numbers are the same value</nobr></li>
+<li><nobr><a href="../reference/number-not-equal.htm"> /= </a> - true if no two numbers have the same value</nobr></li>
+<li><nobr><a href="../reference/number-not-lessp.htm"> >= </a> - true if all numbers are monotonically nonincreasing</nobr></li>
+<li><nobr><a href="../reference/number-greaterp.htm"> > </a> - true if all numbers are monotonically decreasing</nobr></li>
+</ul>
+</ul>
+<li><nobr><a href="../reference/null.htm">null</a> - is this an empty list?</nobr></li>
+<li><nobr><a href="../reference/consp.htm">consp</a> - is it a non-empty list?</nobr></li>
+<li><nobr><a href="../reference/listp.htm">listp</a> - is this a list?</nobr></li>
+<ul>
+<li><nobr><b>List Predicates</b> - one argument [error if not a list]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/endp.htm">endp</a> - is this the end of a list?</nobr></li>
+</ul>
+</ul>
+<li><nobr><a href="../reference/stringp.htm">stringp</a> - is this a string?</nobr></li>
+<ul>
+<li><nobr><b>String Comparison</b> - one or more arguments [error if not strings only]</nobr></li>
+<ul>
+<li><nobr>Case Sensitive</nobr></li>
+<ul>
+<li><nobr><a href="../reference/string-lessp-s.htm">string<</a> - test for less than in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/string-not-greaterp-s.htm">string<=</a> - test for less than or equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/string-equal-s.htm">string=</a> - test for equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/string-not-equal-s.htm">string/=</a> - test for not equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/string-not-lessp-s.htm">string>=</a> - test for greater than or equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/string-greaterp-s.htm">string></a> - test for greater than in ASCII ordering</nobr></li>
+</ul>
+<li><nobr>Case Insensitive</nobr></li>
+<ul>
+<li><nobr><a href="../reference/string-lessp-i.htm">string-lessp</a> - is this less than in ASCII ordering ?</nobr></li>
+<li><nobr><a href="../reference/string-not-greaterp-i.htm">string-not-greaterp</a> - is this not greater than in ASCII ordering ?</nobr></li>
+<li><nobr><a href="../reference/string-equal-i.htm">string-equal</a> - is this equal in ASCII ordering ?</nobr></li>
+<li><nobr><a href="../reference/string-not-equal-i.htm">string-not-equal</a> - is this not equal in ASCII ordering ?</nobr></li>
+<li><nobr><a href="../reference/string-not-lessp-i.htm">string-not-lessp</a> - is this not less than in ASCII ordering ?</nobr></li>
+<li><nobr><a href="../reference/string-greaterp-i.htm">string-greaterp</a> - is this greater than in ASCII ordering ?</nobr></li>
+</ul>
+<li><nobr>See also <a href="strings.htm#unicode">Unicode</a> examples.</nobr></li>
+</ul>
+</ul>
+<li><nobr><a href="../reference/characterp.htm">characterp</a> - is this a character?</nobr></li>
+<ul>
+<li><nobr><b>Character Predicates</b> - one argument [error if not a character]</nobr></li>
+<ul>
+<li><nobr><a href="../reference/upper-case-p.htm">upper-case-p</a> - is this an upper case character?</nobr></li>
+<li><nobr><a href="../reference/lower-case-p.htm">lower-case-p</a> - is this a lower case character?</nobr></li>
+<li><nobr><a href="../reference/both-case-p.htm">both-case-p</a> - is this an alphabetic [either case] character?</nobr></li>
+<li><nobr><a href="../reference/digit-char-p.htm">digit-char-p</a> - is this a digit character?</nobr></li>
+<li><nobr><a href="../reference/alphanumericp.htm">alphanumericp</a> - is this an alphabetic or a digit character?</nobr></li>
+<li><nobr>See also <a href="strings.htm#posix">POSIX Character Classes</a>.</nobr></li>
+</ul>
+<li><nobr><b>Character Comparison</b> - one or more arguments [error if not characters only]</nobr></li>
+<ul>
+<li><nobr>Case Sensitive</nobr></li>
+<ul>
+<li><nobr><a href="../reference/char-lessp-s.htm">char<</a> - test for less than in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/char-not-greaterp-s.htm">char<=</a> - test for less than or equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/char-equal-s.htm">char=</a> - test for equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/char-not-equal-s.htm">char/=</a> - test for not equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/char-not-lessp-s.htm">char>=</a> - test for greater than or equal to in ASCII ordering</nobr></li>
+<li><nobr><a href="../reference/char-greaterp-s.htm">char></a> - test for greater than in ASCII ordering</nobr></li>
+</ul>
+<li><nobr>Case Insensitive</nobr></li>
+<ul>
+<li><nobr><a href="../reference/char-lessp-i.htm">char-lessp</a> - is this less than in ASCII ordering?</nobr></li>
+<li><nobr><a href="../reference/char-not-greaterp-i.htm">char-not-greaterp</a> - is this not greater than in ASCII ordering ?</nobr></li>
+<li><nobr><a href="../reference/char-equal-i.htm">char-equal</a> - is this equal in ASCII ordering?</nobr></li>
+<li><nobr><a href="../reference/char-not-equal-i.htm">char-not-equal</a> - is this not equal in ASCII ordering?</nobr></li>
+<li><nobr><a href="../reference/char-not-lessp-i.htm">char-not-lessp</a> - is this not less than in ASCII ordering ?</nobr></li>
+<li><nobr><a href="../reference/char-greaterp-i.htm">char-greaterp</a> - is this greater than in ASCII ordering?</nobr></li>
+</ul>
+<li><nobr>See also <a href="strings.htm#unicode">Unicode</a> examples.</nobr></li>
+</ul>
+</ul>
+<li><nobr><a href="../reference/arrayp.htm">arrayp</a> - is this an array?</nobr></li>
+<li><nobr><a href="../reference/streamp.htm">streamp</a> - is this a stream?</nobr></li>
+<li><nobr><a href="../reference/objectp.htm">objectp</a> - is this an object?</nobr></li>
+<li><nobr>filep - is this a file?</nobr></li>
+<li><nobr>soundp - is this a sound?</nobr></li>
+</ul>
+</ol>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="equalp"></a>
+
+<hr>
+
+<h2>equalp</h2>
+
+<hr>
+
+<p>Two expressions are 'equalp':</p>
+
+<ul>
+
+<li><p>If two numbers <nobr>are
+<a href="../reference/number-equal.htm"> = </a></nobr>
+numerical equal.</p></li>
+
+<li><p>If two characters are
+<nobr><a href="../reference/char-equal.htm">char-equal</a></nobr>.</p></li>
+
+<li><p>If two strings are <nobr><a
+href="../reference/string-equal.htm">string-equal</a></nobr>.</p></li>
+
+<li><p>If the two <a href="../reference/car.htm">car</a>s in conses are
+'equalp' and the two <a href="../reference/cdr.htm">cdr</a>s in conses
+are 'equalp'.</p></li>
+
+<li><p>If two arrays have the same number of elements and dimensions, and
+the corresponding elements in all dimensions are 'equalp'.</p></li>
+
+</ul>
+
+<pre class="example">
+(defun <font color="#0000CC">equalp</font> (expr-1 expr-2)
+ (or (equal expr-1 expr-2)
+ (and (numberp expr-1) (numberp expr-2) (= expr-1 expr-2))
+ (let ((type (type-of expr-1)))
+ (when (eq type (type-of expr-2))
+ (case type
+ (character (char-equal expr-1 expr-2))
+ (string (string-equal expr-1 expr-2))
+ (cons (do ((x (first expr-1)
+ (if (consp expr-1) (first expr-1) expr-1))
+ (y (first expr-2)
+ (if (consp expr-2) (first expr-2) expr-2)))
+ ((or (null expr-1)
+ (null expr-2)
+ (not (equalp x y)))
+ (and (null expr-1)
+ (null expr-2)))
+ (setq expr-1 (and (consp expr-1) (rest expr-1))
+ expr-2 (and (consp expr-2) (rest expr-2)))))
+ (array (let ((end (length expr-1)))
+ (when (eql end (length expr-2))
+ (dotimes (index end t)
+ (and (not (equalp (aref expr-1 index)
+ (aref expr-2 index)))
+ (return nil)))))))))))
+</pre>
+
+<p><b>cons:</b> I used <a href="../reference/do.htm">do</a> instead of
+recursion because XLISP has only two kilobytes stack size. <nobr>The
+(<a href="../reference/consp.htm">consp</a> <i>expr</i>)</nobr> tests are
+necessary because in a dotted list the last
+<a href="../reference/rest.htm">rest</a> element is not a cons.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(equalp 1 1.0) => T
+(equalp #\a #\A) => T
+(equalp "Abc" "aBc") => T
+(equalp '(1 #\a "Abc") '(1.0 #\A "aBc")) => T
+(equalp #(1 #\a "Abc") #(1.0 #\A "aBc")) => T
+</pre>
+
+<p>Nested expressions only match if the nesting matches:</p>
+
+<pre class="example">
+(equalp '(1 <font color="#AA0000">(</font>2 3<font color="#AA0000">)</font>) '(1.0 <font color="#AA0000">(</font>2.0 3.0<font color="#AA0000">)</font>) => T
+(equalp '(1 <font color="#AA0000">(</font>2 3<font color="#AA0000">)</font>) '(<font color="#AA0000">(</font>1.0 2.0<font color="#AA0000">)</font> 3.0) => NIL
+(equalp '(<font color="#AA0000">(</font>1 2<font color="#AA0000">)</font> 3) '(<font color="#AA0000">(</font>1.0 2.0<font color="#AA0000">)</font> 3.0) => T
+(equalp '(<font color="#AA0000">(</font>1 2<font color="#AA0000">)</font> 3) '(1.0 <font color="#AA0000">(</font>2.0 3.0<font color="#AA0000">)</font>) => NIL
+</pre>
+
+<p>A character does not match a string with the same character:</p>
+
+<pre class="example">
+(equalp #\a "a") => NIL
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="variablep"></a>
+
+<hr>
+
+<h2>variablep</h2>
+
+<hr>
+
+<p>The 'variablep' macro tests if a Lisp expression evaluates to a symbol
+with a valid variable value bound to it in the current global or lexical
+environment:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">variablep</font> (expr)
+ `(and (symbolp ,expr)
+ (valuep ,expr)))
+</pre>
+
+<p>Depends on <a href="environment.htm#valuep">valuep</a>, see
+<a href="../reference/and.htm">and</a>,
+<a href="../reference/defmacro.htm">defmacro</a>,
+<a href="../reference/symbolp.htm">symbolp</a>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="functionp"></a>
+
+<hr>
+
+<h2>functionp</h2>
+
+<hr>
+
+<p>The 'functionp' macro tests if a Lisp expression eveluates to a function
+or a symbol with a valid function value bound to it in the current global or
+lexical environment:</p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">functionp</font> (expr)
+ `(case (type-of ,expr)
+ (closure (eq 'lambda (car (get-lambda-expression ,expr))))
+ (subr t)
+ (symbol (and (or (lfboundp ,expr) (fboundp ,expr))
+ (functionp (function ,(if (consp expr) (cadr expr) expr)))))
+ (t nil)))
+</pre>
+
+<p>Depends on <a href="environment.htm#lfboundp">lfboundp</a>, see
+<a href="../reference/and.htm">and</a>,
+<a href="../reference/caar.htm">cadr</a>,
+<a href="../reference/car.htm">car</a>,
+<a href="../reference/case.htm">case</a>,
+<a href="../manual/xlisp.htm#data-types">closure</a>,
+<a href="../reference/defmacro.htm">defmacro</a>,
+<a href="../reference/eq.htm">eq</a>,
+<a href="../reference/fboundp.htm">fboundp</a>,
+<a href="../reference/function.htm">function</a>,
+<nobr><a href="../reference/get-lambda-expression.htm">get-lambda-expression</a></nobr>,
+<a href="../reference/lambda.htm">lambda</a>,
+<a href="../reference/nil.htm">nil</a>,
+<a href="../reference/or.htm">or</a>,
+<a href="../manual/xlisp.htm#data-types">subr</a>,
+<a href="../manual/xlisp.htm#data-types">symbol</a>,
+<nobr><a href="../reference/t.htm"> t </a></nobr>,
+<nobr><a href="../reference/type-of.htm">type-of</a></nobr>.</p>
+
+<p>The awkward <nobr>(function ,(if (consp expr) (cadr expr) expr))</nobr>
+construct is necessary because the
+<a href="../reference/function.htm">function</a> special form needs a
+<nobr>pre-evaluated</nobr> argument, what must be
+done at <nobr>macro-expansion</nobr> time, so an additional
+<nobr><a href="../reference/consp.htm">consp</a></nobr> test is
+needed if the 'expr' argument is a list at all, otherwise
+<a href="../reference/cadr.htm">cadr</a> will produce an error.</p>
+
+Examples:
+
+<pre class="example">
+(functionp #'car) => T <font color="#008844">; subr = built-in function</font>
+(functionp 'car) => T <font color="#008844">; symbol with a function value</font>
+
+(functionp #'and) => NIL <font color="#008844">; fsubr = built-in special form</font>
+(functionp "and") => NIL <font color="#008844">; string</font>
+
+(defun a () nil) => A <font color="#008844">; closure = user-defined function</font>
+(functionp #'a) => T <font color="#008844">; closure</font>
+(functionp 'a) => T <font color="#008844">; symbol with a function value</font>
+
+(setq b #'a) => A <font color="#008844">; function A stored in variable B</font>
+(fboundp 'b) => NIL <font color="#008844">; no function B found</font>
+(fboundp b) => T <font color="#008844">; variable B evaluates to function A</font>
+
+(functionp #'(lambda () nil)) => T <font color="#008844">; closure</font>
+(functionp '(lambda () nil)) => NIL <font color="#008844">; list</font>
+(functionp (lambda () nil)) => T <font color="#008844">; closure</font>
+
+(functionp #'functionp) => NIL <font color="#008844">; macro</font>
+
+(let ((x nil)) <font color="#008844">; lexical variable</font>
+ (functionp x))
+=> NIL
+
+(flet ((y () nil)) <font color="#008844">; lexical closure</font>
+ (functionp y))
+=> T
+
+(labels ((z () nil)) <font color="#008844">; lexical closure</font>
+ (functionp z))
+=> T
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="specialp"></a>
+
+<hr>
+
+<h2>specialp</h2>
+
+<hr>
+
+<pre class="example">
+(defmacro <font color="#0000CC">specialp</font> (expr)
+ `(case (type-of ,expr)
+ (fsubr t)
+ (symbol (and (or (lfboundp ,expr) (fboundp ,expr))
+ (functionp (function ,(if (consp expr) (cadr expr) expr)))))
+ (t nil)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="macrop"></a>
+
+<hr>
+
+<h2>macrop</h2>
+
+<hr>
+
+<pre class="example">
+(defmacro <font color="#0000CC">macrop</font> (expr)
+ `(case (type-of ,expr)
+ (closure (eq 'macro (car (get-lambda-expression ,expr))))
+ (symbol (and (or (lfboundp ,expr) (fboundp ,expr))
+ (macrop (function ,(if (consp expr) (cadr expr) expr)))))
+ (t nil)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="subrp"></a>
+
+<hr>
+
+<h2>subrp</h2>
+
+<hr>
+
+<p>The 'subrp' function returns T if the symbol is a build-in function.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">subrp</font> (symbol)
+ (eq 'subr (type-of symbol)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="fsubrp"></a>
+
+<hr>
+
+<h2>fsubrp</h2>
+
+<hr>
+
+<p>The 'fsubrp' function returns T if the symbol is a build-in special
+function.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">fsubrp</font> (symbol)
+ (eq 'fsubr (type-of symbol)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="closurep"></a>
+
+<hr>
+
+<h2>closurep</h2>
+
+<hr>
+
+<p>The 'closurep' function returns T if the symbol is a user-defined
+function.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">closurep</font> (symbol)
+ (eq 'closure (type-of symbol)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
+
diff --git a/docsrc/xlisp/xlisp-doc/examples/reader.htm b/docsrc/xlisp/xlisp-doc/examples/reader.htm new file mode 100644 index 0000000..8321c48 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/reader.htm @@ -0,0 +1,311 @@ +<html><head>
+
+<title>XLISP reader</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Reader</h1>
+
+<hr>
+
+
+
+<hr>
+
+<h2>read-from-string</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">read-from-string</font> (string)
+ (read (make-string-input-stream string)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="global-readtable"></a>
+
+<hr>
+
+<h2>*readtable*</h2>
+
+<hr>
+
+<p>The <a href="../reference/global-readtable.htm">*readtable*</a> system
+variable contains the reader table array. <nobr>The table</nobr> is
+<nobr>128 entries</nobr> <nobr>[0..127]</nobr> for each of the
+<nobr>7-bit</nobr> ASCII characters that XLISP
+<nobr>can <a href="../reference/read.htm">read</a></nobr>.</p>
+
+<ul>
+<li><nobr><a href="../reference/read.htm">read</a> - function to read a lisp expression</nobr></li>
+<li><nobr><a href="../reference/global-readtable.htm">*readtable*</a> - system variable, holding the readtable</nobr></li>
+<ul>
+<li><nobr><a href="../reference/nil.htm">NIL</a> - invalid character</nobr></li>
+<li><nobr><a href="../reference/keyword-constituent.htm">:constituent</a> - symbol constituent</nobr></li>
+<li><nobr><a href="../reference/keyword-sescape.htm">:sescape</a> - whitespace character</nobr></li>
+<li><nobr><a href="../reference/keyword-mescape.htm">:mescape</a> - multiple escape character</nobr></li>
+<li><nobr><a href="../reference/keyword-white-space.htm">:white-space</a> - single escape character</nobr></li>
+<li><nobr><a href="../reference/keyword-tmacro.htm">:tmacro</a> - terminating readmacro</nobr></li>
+<li><nobr><a href="../reference/keyword-nmacro.htm">:nmacro</a> - non-terminating readmacro</nobr></li>
+</ul>
+</ul>
+
+<p>See also the
+<nobr><a href="../manual/xlisp.htm#lexical-conventions">Lexical Conventions</a></nobr>
+and <a href="../manual/xlisp.htm#the-readtable">Readtable</a> sections in the
+<nobr>XLISP 2.0</nobr> manual.</p>
+
+<a name="print-readtable"></a>
+
+<hr>
+
+<h2>print-readtable</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">print-readtable</font> ()
+ (dotimes (index 128)
+ (format t <font color="#880000">"ASCII-~a ~a = ~a~%"</font>
+ (cond ((<= 0 index 9) (format nil "00~a" index))
+ ((<= 10 index 99) (format nil "0~a" index))
+ (t index))
+ (if (< 31 index 127)
+ (code-char index)
+ (case index
+ (0 "[null] ")
+ (1 "[start of heading] ")
+ (2 "[start of text] ")
+ (3 "[end of text] ")
+ (4 "[end of transmission] ")
+ (5 "[enquiry] ")
+ (6 "[acknowledge] ")
+ (7 "[terminal bell] ")
+ (8 "[backspace] ")
+ (9 "[horizontal tab] ")
+ (10 "[line feed] ")
+ (11 "[vertical tab] ")
+ (12 "[form feed] ")
+ (13 "[carriage return] ")
+ (14 "[shift out] ")
+ (15 "[shift in] ")
+ (16 "[data link escape] ")
+ (17 "[device control 1, xon] ")
+ (18 "[device control 2] ")
+ (19 "[device control 3, xoff]")
+ (20 "[device control 4] ")
+ (21 "[negative acknowledge] ")
+ (22 "[synchronous idle] ")
+ (23 "[end transmission block]")
+ (24 "[cancel line] ")
+ (25 "[end of medium] ")
+ (26 "[substitute] ")
+ (27 "[escape] ")
+ (28 "[file separator] ")
+ (29 "[group separator] ")
+ (30 "[record separator] ")
+ (31 "[unit separator] ")
+ (127 "[delete]")))
+ (aref <font color="#AA5500">*readtable*</font> index))))
+</pre>
+
+<hr>
+
+<h2>get-macro-character</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>get-macro-character</b> <i>char</i>)</dt>
+<dd><i>char</i> - a character<br>
+returns - the code associated with the
+<a href="../reference/global-readtable.htm">*readtable*</a> entry or
+<a href="../reference/nil.htm">NIL</a></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">get-macro-character</font> (char)
+ (if (consp (aref <font color="#AA5500">*readtable*</font> (char-code char)))
+ (cdr (aref <font color="#AA5500">*readtable*</font> (char-int char)))
+ nil))
+</pre>
+
+<p> The '<nobr>get-macro-character</nobr>' function returns the code that
+will be executed when the specified character 'char' is encountered by the
+XLISP reader.</p>
+
+<p>The 'get-macro-character' function will return a
+<a href="../reference/nil.htm">NIL</a> value if the table entry is
+<nobr><a href="../reference/nil.htm">NIL</a> ,</nobr>
+<nobr><a href="../reference/keyword-constituent.htm">:constituent</a> ,</nobr>
+<nobr><a href="../reference/keyword-sescape.htm">:sescape</a> ,</nobr>
+<a href="../reference/keyword-mescape.htm">:mescape</a> or
+<a href="../reference/keyword-white-space.htm">:white-space</a>. If the table entry is
+<a href="../reference/keyword-tmacro.htm">:tmacro</a> or
+<nobr><a href="../reference/keyword-nmacro.htm">:nmacro</a> ,</nobr> then the code
+associated with the entry is returned.
+<a href="../reference/keyword-tmacro.htm">:tmacro</a> is used for a terminating
+read-macro. <a href="../reference/keyword-nmacro.htm">:nmacro</a> is used for a
+non-terminating read-macro. 'get-macro-character' does not differentiate
+whether the code returned is a
+<a href="../reference/keyword-tmacro.htm">:tmacro</a> or an
+<a href="../reference/keyword-nmacro.htm">:nmacro</a>.</p>
+
+<p>The function returned may be a built-in read-macro function or a user
+defined <a href="../reference/lambda.htm">lambda</a> expression. The function
+takes two parameters, an input stream specification, and an integer that is
+the character value. The function should return
+<a href="../reference/nil.htm">NIL</a> if the character is 'white-space' or a
+value <a href="../reference/cons.htm">cons</a>ed with
+<a href="../reference/nil.htm">NIL</a> to return the value.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(get-macro-character #\() => #<Subr-(null): #...></font>
+(get-macro-character #\#) => #<Subr-(null): #...></font>
+(get-macro-character #\Space) => NIL</font>
+</pre>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<a name="set-macro-character"></a>
+
+<hr>
+
+<h2>set-macro-character</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>set-macro-character</b> <i>char function</i> [<i>termination-flag</i>])</dt>
+<dd><i>char</i> - a character expression<br>
+<i>function</i> - a function definition<br>
+<i>termination-flag</i> - an expression, <a href="../reference/nil.htm">NIL</a> or
+non-<a href="../reference/nil.htm">NIL</a><br>
+returns - always returns <a href="../reference/t.htm"> T </a></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">set-macro-character</font> (char function &optional terminate-p)
+ (setf (aref <font color="#AA5500">*readtable*</font> (char-code char))
+ (cons (if terminate-p :tmacro :nmacro) function))
+ t)
+</pre>
+
+<p>The '<nobr>set-macro-character</nobr>' function installs the code that
+will be executed when the specified character 'char' is encountered by the
+XLISP reader.</p>
+
+<p>The 'set-macro-character' function only allows you to put in a
+terminating read-macro function <a href="../reference/keyword-tmacro.htm">:tmacro</a> or
+a non-terminating read-macro-function
+<a href="../reference/keyword-nmacro.htm">:nmacro</a>. If the 'termflag' is present and
+non-<nobr><a href="../reference/nil.htm">NIL</a> ,</nobr> then the 'function'
+will be put in <a href="../reference/global-readtable.htm">*readtable*</a> as a
+<a href="../reference/keyword-tmacro.htm">:tmacro</a> entry. If 'termflag' is not present
+or <nobr><a href="../reference/nil.htm">NIL</a> ,</nobr> then 'function' will
+be put in <a href="../reference/global-readtable.htm">*readtable*</a> as a
+<a href="../reference/keyword-nmacro.htm">:nmacro</a> entry. The 'function' can be a
+built-in read-macro function or a user defined
+<a href="../reference/defun.htm">defun</a> symbol or a
+<a href="../reference/lambda.htm">lambda</a> expression.</p>
+
+<p>The 'function' takes two parameters, an input stream specification, and
+an integer that is the character value. The 'function' should return
+<a href="../reference/nil.htm">NIL</a> if the character is 'white-space' or a
+value <a href="../reference/cons.htm">cons</a>ed with
+<a href="../reference/nil.htm">NIL</a> to return the value. The function
+'set-macro-character' always returns
+<a href="../reference/t.htm"> T </a>.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+> (print "hi") % comment
+"hi"
+"hi"
+<font color="#AA0000">error: unbound variable - %</font> <font color="#008844">; % is interpreted as a variable</font>
+
+> (setq readtable-backup *readtable*)
+#( ... very-long-value ... )
+
+> (set-macro-character #\% (get-macro-character #\;) t)
+T
+
+> (print "hi") % comment
+"hi" <font color="#008844">; no error because</font>
+"hi" <font color="#008844">; % is now a comment character</font>
+
+> (setq *readtable* readtable-backup)
+#( ... very-long-value ... )
+</pre>
+
+<p><b>Important:</b> before manipulating the XLISP
+<a href="../reference/global-readtable.htm">*readtable*</a> it's always a
+good idea to store the original contents in some other variable.</p>
+
+<p><nobr> <a href="#top">Back to Top</nobr></a></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/sequences.htm b/docsrc/xlisp/xlisp-doc/examples/sequences.htm new file mode 100644 index 0000000..fb69a4b --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/sequences.htm @@ -0,0 +1,563 @@ +<html><head>
+
+<title>Sequences</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Sequences</h1>
+
+<hr>
+
+<p>Sequences are <a href="lists.htm">Lists</a>,
+<a href="strings.htm">Strings</a>,
+<nobr>or <a href="arrays.htm">Arrays</a></nobr>.</p>
+
+<ul>
+<li><nobr><a href="#sequencep">sequencep</a> - test if a Lisp object is a sequence</nobr></li>
+<li><nobr><a href="#length">length</a> - the length of a sequence</nobr></li>
+<li><nobr><a href="#identity">identity</a> - do nothing, just return the value</nobr></li>
+<li><nobr><a href="#cl-subseq">cl:subseq</a> - subsequences of lists, strings, or arrays</nobr></li>
+<li><nobr>Properties of elements in sequences:</nobr></li>
+<ul>
+<li><nobr>find</nobr></li>
+<li><nobr>count</nobr></li>
+<li><nobr>position</nobr></li>
+</ul>
+<li><nobr>Predicates for testing sequences:</nobr></li>
+<ul>
+<li><nobr>every</nobr></li>
+<li><nobr>some</nobr></li>
+<li><nobr>notevery</nobr></li>
+<li><nobr>notany </nobr></li>
+</ul>
+<li><nobr>Functions to modify sequences:</nobr></li>
+<ul>
+<li><nobr>map</nobr></li>
+<li><nobr>flatten</nobr></li>
+</ul>
+</ul>
+
+<a name="sequencep"></a>
+
+<hr>
+
+<h2>sequencep</h2>
+
+<hr>
+
+<p>The following example demonstrates how a XLISP expression can be tested
+for being a sequence:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">sequencep</font> (x)
+ (and (lboundp 'x) <font color="#008844">; not *unbound*</font>
+ (or (and (listp x) <font color="#008844">; a list or NIL</font>
+ (consp (last x))) <font color="#008844">; but not a dotted list</font>
+ (stringp x) <font color="#008844">; or a string</font>
+ (arrayp x)))) <font color="#008844">; or an array</font>
+</pre>
+
+<p>Depends on <a href="environment.htm#lboundp">lboundp</a>,
+see also <a href="../reference/and.htm">and</a>,
+<a href="../reference/arrayp.htm">arrayp</a>,
+<a href="../reference/consp.htm">consp</a>,
+<a href="../reference/defun.htm">defun</a>,
+<a href="../reference/last.htm">last</a>,
+<a href="../reference/listp.htm">listp</a>,
+<a href="../reference/or.htm">or</a>,
+<a href="../reference/stringp.htm">stringp</a>.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="length"></a>
+
+<hr>
+
+<h2>length</h2>
+
+<hr>
+
+<p>XLISP already knows sequences, even if the manual doesn't explicitely
+<nobr>tell you:</nobr></p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<a href="../reference/length.htm">length</a> <i>expr</i>)</dt>
+<dd><i>expr</i> - expression, evaluating to a list, string, or array<br>
+returns - the length of the list, string, or array</dd>
+</dl>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="identity"></a>
+
+<hr>
+
+<h2>identity</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">identity</font> (x)
+ x)
+</pre>
+
+<p>The 'identity' function is handy if a mapping function needs a '<nobr>do
+nothing</nobr>, just return the value' function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-subseq"></a>
+
+<hr>
+
+<h2>cl:subseq</h2>
+
+<hr>
+
+<p>XLISP already has a <a href="../reference/subseq.htm">subseq</a> function
+returning a subsequence of a string:</p>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(<a href="../reference/subseq.htm">subseq</a> <i>string start</i> [<i>end</i>])</nobr></dt>
+<dd><i>string</i> - a string expression<br>
+<i>start</i> - the position of the first element, an integer<br>
+<i>end</i> - the position following last element, defaults to the end of the sequence<br>
+returns - the substring between <i>start</i> and <i>end</i></dd>
+</dl>
+
+</div></p>
+
+<p>The 'cl:subseq' function works like
+<a href="../reference/subseq.htm">subseq</a>, but returns subsequences of
+lists, strings, and arrays:</p>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(cl:<b>subseq</b> <i>sequence start</i> [<i>end</i>])</nobr></dt>
+<dd><i>sequence</i> - a list, string, or array<br>
+<i>start</i> - the position of the first element, an integer<br>
+<i>end</i> - the position following last element, defaults to the end of the sequence<br>
+returns - the subsequence in the same type as <i>sequence</i></dd>
+</dl>
+
+</div></p>
+
+<p>The 'cl:subseq' function creates a sequence that is a copy of the
+subsequence of 'sequence' bounded by 'start' and 'end'. 'cl:subseq' always
+allocates a new sequence for a result, it never shares storage with an old
+sequence. <nobr>The resulting</nobr> subsequence is always of the same type
+as the input sequence.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:subseq</font> (sequence start &optional (end nil end-p))
+ (let ((type (type-of sequence)))
+ (if (not (member type '(nil cons string array)))
+ (error <font color="#880000">"not a sequence"</font> sequence)
+ (let* ((length (length sequence))
+ (end (or end length)))
+ (cond ((or (> start length) (minusp start))
+ (error <font color="#880000">"start index out of bounds"</font> start))
+ ((and end-p (or (> end length) (minusp end)))
+ (error <font color="#880000">"end index out of bounds"</font> end))
+ ((> start end)
+ (error (format nil <font color="#880000">"bad range start ~a end ~a"</font> start end)))
+ (t (case type
+ (nil nil)
+ (cons (if (not (consp (last sequence)))
+ <font color="#008844">;; a dotted list is not a sequence</font>
+ (error <font color="#880000">"not a proper sequence"</font> sequence)
+ (if (>= start end)
+ nil
+ (nthcdr start
+ (if end-p
+ (reverse
+ (nthcdr (- length end)
+ (reverse sequence)))
+ sequence)))))
+ (string (subseq sequence start end))
+ (array (if (>= start end)
+ (make-array 0)
+ (let ((new-array (make-array (- end start))))
+ (do ((n-index 0 (1+ n-index))
+ (s-index start (1+ s-index)))
+ ((>= s-index end))
+ (setf (aref new-array n-index)
+ (aref sequence s-index)))
+ new-array))))))))))
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:subseq "012345" 2) => "2345"
+(cl:subseq "012345" 3 5) => "34"
+
+(cl:subseq '(0 1 2 3 4 5) 2) => (2 3 4 5)
+(cl:subseq '(0 1 2 3 4 5) 3 5) => (3 4)
+
+(cl:subseq #(0 1 2 3 4 5) 2) => #(2 3 4 5)
+(cl:subseq #(0 1 2 3 4 5) 3 5) => #(3 4)
+</pre>
+
+<p>In XLISP, neither <a href="../reference/subseq.htm">subseq</a> nor
+'cl:subseq' can be used as arguments to
+<a href="../reference/setf.htm">setf</a>.
+<nobr>See <a href="#cl-replace">cl:replace</a></nobr> below how to replace
+subsequences.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="cl-replace"></a>
+
+<hr>
+
+<h2>cl:replace</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt><nobr>(cl:<b>replace</b> <i>sequence1 sequence2</i> &key <i>start1 end1 start2 end2</i>)</nobr></dt>
+<dd><i>sequenceN</i> - a list, string, or array<br>
+<i>startN</i> - the position of the first element in <i>sequenceN</i>, an integer<br>
+<i>endN</i> - the position following last element in <i>sequenceN</i>, defaults to the end of <i>sequenceN</i><br>
+returns - the subsequence in the same type as <i>sequence</i></dd>
+</dl>
+
+</div></p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<h2>map</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+
+<dt><nobr><b>map</b> <i>result-type function</i> <i>sequence-1</i> [<i>sequence-2</i> ...]</nobr></dt>
+<dd><i>result-type</i> - list, string, or array<br>
+<i>function</i> - a function, applied to each element of each sequenceN<br>
+<i>sequenceN</i> - a list, string, or array<br>
+returns - a sequence where each element is the result of applying the function to each element of each sequenceN</dd>
+</dl>
+
+<dl>
+
+</div></p>
+
+<p>The 'sequence:string' function can handle lists and arrays containing not
+only characters but also strings, because XLISP Unicode characters are
+represented as strings.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">sequence:string</font> (sequence)
+ (if (stringp sequence)
+ sequence
+ (let ((result <font color="#880000">""</font>))
+ (flet ((strcat-element (element)
+ (let ((string (cond ((stringp element) element)
+ ((characterp element) (string element))
+ (t (error <font color="#880000">"not a character or string"</font>
+ element)))))
+ (setq result (strcat result string)))))
+ (case (type-of sequence)
+ (array (let ((end (length sequence)))
+ (dotimes (index end)
+ (if (eq (aref sequence index) '*unbound*)
+ (error <font color="#880000">"not a character or string"</font> '*unbound*)
+ (strcat-element (aref sequence index))))))
+ (cons (let ((end (length sequence)))
+ (if (not (consp (last sequence)))
+ (error <font color="#880000">"not a proper sequence"</font> sequence)
+ (dotimes (index end)
+ (if (eq (nth index sequence) '*unbound*)
+ (error <font color="#880000">"not a character or string"</font> '*unbound*)
+ (strcat-element (nth index sequence)))))))
+ (nil nil)
+ (t (error <font color="#880000">"not a sequence"</font> sequence)))
+ result))))
+
+(defun <font color="#0000CC">list-to-string</font> (list)
+ (let ((string ""))
+ (dolist (element list string)
+ (setq string (strcat string (if (consp element)
+ (list-to-string element)
+ (format nil "~a" element)))))))
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">sequence:vector</font> (sequence)
+ (if (not (boundp 'sequence))
+ (error <font color="#880000">"not a sequence"</font> '*unbound*)
+ (let ((type (type-of sequence)))
+ (if (not (member type '(array cons nil string)))
+ (error <font color="#880000">"not a sequence"</font> sequence)
+ (let* ((end (length sequence))
+ (result (make-array end)))
+ (unless (zerop end)
+ (case type
+ (array (dotimes (index end)
+ (setf (aref result index)
+ (if (eq (aref sequence index) '*unbound*)
+ '*unbound*
+ (aref sequence index)))))
+ (cons (if (not (consp (last sequence)))
+ (error <font color="#880000">"not a proper sequence"</font> sequence)
+ (dotimes (index end)
+ (setf (aref result index)
+ (if (eq (nth index sequence) '*unbound*)
+ '*unbound*
+ (nth index sequence))))))
+ (string (dotimes (index end)
+ (setf (aref result index)
+ (char sequence index))))))
+ result)))))
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">sequence:array</font> (sequence)
+ (let ((type (type-of sequence)))
+ (if (not (member type '(array cons nil string)))
+ (error <font color="#880000">"not a sequence"</font> sequence)
+ (let* ((end (length sequence))
+ (result (make-array end)))
+ (if (zerop end)
+ result
+ (labels ((array-element (element index)
+ (setf (aref result index)
+ (if (or (consp element) (arrayp element))
+ (sequence:array element)
+ element))))
+ (case type
+ (array (dotimes (index end)
+ (if (eq (aref sequence index) '*unbound*)
+ (setf (aref result index) '*unbound*)
+ (array-element (aref sequence index) index))))
+ (cons (if (not (consp (last sequence)))
+ (error <font color="#880000">"not a proper sequence"</font> sequence)
+ (dotimes (index end)
+ (if (eq (nth index sequence) '*unbound*)
+ (setf (aref result index) '*unbound*)
+ (array-element (nth index sequence) index)))))
+ (string (dotimes (index end)
+ (setf (aref result index)
+ (char sequence index)))))
+ result))))))
+
+
+(defun <font color="#0000CC">list-to-array</font> (list)
+ (let* ((end (length list))
+ (array (make-array end)))
+ (dotimes (index end array)
+ (let ((element (nth index list)))
+ (setf (aref array index) (if (consp element)
+ (list-to-array element)
+ element))))))
+
+(defun <font color="#0000CC">list-from-input</font> (input)
+ (let (result)
+ (dolist (element input) <font color="#008844">; input is always a list</font>
+ (format t ";; ~s ~s~%" element (type-of element))
+ (case (type-of element)
+ (nil (push element result))
+ (cons (if (consp (last element))
+ (push element result)
+ (error <font color="#880000">"not a proper list"</font> element)))
+ (array (let (local (end (length element)))
+ (dotimes (index end)
+ (push (aref element index) local))
+ (push (reverse local) result)))
+ (string (let (local (end (length element)))
+ (dotimes (index end)
+ (push (char element index) local))
+ (push (reverse local) result)))
+ (t (error <font color="#880000">"not a sequence"</font> element))))
+ (reverse result)))
+
+(defun <font color="#0000CC">list-from-input*</font> (input &optional recursion-p)
+ (let (result)
+ (labels ((test (element)
+ (if (member (type-of element) '(array cons string))
+ (list-from-input* element t)
+ (if (or recursion-p (null element))
+ element
+ (error <font color="#880000">"not a sequence"</font> element)))))
+ (format t ";; ~s~%" input)
+ (case (type-of input)
+ (nil (push input result))
+ (cons (if (consp (last input))
+ (dolist (element input)
+ (push (test element) result))
+ (error <font color="#880000">"not a proper list"</font> input)))
+ (array (let ((end (length input)))
+ (dotimes (index end)
+ (push (test (aref input index)) result))))
+ (string (let ((end (length input)))
+ (dotimes (index end)
+ (push (test (char input index)) result))))
+ (t (error <font color="#880000">"not a sequence"</font> input)))
+ (reverse result))))
+
+(defun <font color="#0000CC">map</font> (result-type function &rest sequences)
+ (if (not (member result-type '(list string array)))
+ (error <font color="#880000">"invalid result type"</font> result-type)
+ (let* ((input-list (list-from-input sequences))
+ (result (if function
+ (apply #'mapcar (cons function input-list))
+ (if (rest sequences)
+ input-list
+ (first input-list)))))
+ (case result-type
+ (list result)
+ (string (list-to-string result))
+ (array (list-to-array result))))))
+
+(defun <font color="#0000CC">mapcar*</font> (function &rest lists)
+ (unless (or (null lists)
+ (dolist (list lists nil)
+ (and (null list) (return t))))
+ (let ((end (length lists))
+ (result nil))
+ (do ((stop nil) (recurse t t)) (stop)
+ (let (local)
+ (dotimes (index end)
+ (let ((first (first (nth index lists)))
+ (rest (rest (nth index lists))))
+ (push first local)
+ (unless (consp first) (setq recurse nil))
+ (setf (nth index lists) rest)
+ (when (null rest) (setq stop t))))
+ (setq local (reverse local))
+ (format t ";; local: ~a~%" local)
+ (format t ";; lists: ~a~%" lists)
+ (format t ";; recurse: ~a~%" recurse)
+ (if recurse
+ (push (apply #'mapcar* (cons function local)) result)
+ (push (apply function local) result))))
+ (reverse result))))
+
+(defun <font color="#0000CC">map*</font> (result-type function &rest sequences)
+ (if (not (member result-type '(list string array)))
+ (error <font color="#880000">"invalid result type"</font> result-type)
+ (let* ((input-list (list-from-input* sequences))
+ (result (if function
+ (apply #'mapcar* (cons function input-list))
+ (if (rest sequences)
+ input-list
+ (first input-list)))))
+ (format t ";; ~s~%" input-list)
+ (case result-type
+ (list result)
+ (string (list-to-string result))
+ (array (list-to-array result))))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name=""></a>
+
+<hr>
+
+<dt><nobr><b>find</b> <i>item sequence</i> &key <i>from-end test test-not start end key</i> ⇒ <i>element</i></nobr></dt>
+<dt><nobr><b>find-if</b> predicate sequence &key from-end start end key ⇒ element</nobr></dt>
+<dt><nobr><b>find-if-not</b> predicate sequence &key from-end start end key ⇒ element</nobr></dt>
+
+<dd><p>Search for an element of the sequence bounded by start and end that
+satisfies the predicate or that satisfies the test or test-not, as
+appropriate.</p></dd>
+
+<dt><nobr><b>count</b> item sequence &key from-end start end key test test-not ⇒ n</nobr></dt>
+<dt><nobr><b>count-if</b> predicate sequence &key from-end start end key ⇒ n</nobr></dt>
+<dt><nobr><b>count-if-not</b> predicate sequence &key from-end start end key ⇒ n</nobr></dt>
+
+<dd><p>Count and return the number of elements in the sequence bounded by
+start and end that satisfy the test. </p></dd>
+
+<dt><b>position</b> item sequence &key from-end test test-not start end key ⇒ position</dt>
+<dt><b>position-if</b> predicate sequence &key from-end start end key ⇒ position</dt>
+<dt><b>position-if-not</b> predicate sequence &key from-end start end key ⇒ position</dt>
+
+<dd><p>Search sequence for an element that satisfies the test. The position
+returned is the index within sequence of the leftmost (if from-end is true)
+or of the rightmost (if from-end is false) element that satisfies the test;
+otherwise nil is returned. The index returned is relative to the left-hand
+end of the entire sequence, regardless of the value of start, end, or
+from-end.</p></dd>
+
+</dl>
+
+<pre class="example">
+(defun <font color="#0000CC">list-find</font> (element list &key from-end test test-not start end)
+ (when from-end (setq list (reverse-list)))
+ (first (cond (test (member element list :test test))
+ (test-not (member element list :test-not test-not))
+ (t (member element list)))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/strings.htm b/docsrc/xlisp/xlisp-doc/examples/strings.htm new file mode 100644 index 0000000..1842c08 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/strings.htm @@ -0,0 +1,802 @@ +<html><head>
+
+<title>Characters and Strings</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Characters and Strings</h1>
+
+<hr>
+
+<p>Strings are also <a href="sequences.htm">Sequences</a>.</p>
+
+<ul>
+<li><nobr><a href="#make-string">make-string</a> - make a string of a specific number of characters</nobr></li>
+<li><nobr><a href="#string-star">string*</a> - make a string out of arbitrary Lisp expressions</nobr></li>
+<li><nobr><a href="#posix">POSIX Character Classes</a> - character predicates</nobr></li>
+<li><nobr><a href="#unicode">Unicode Strings</a></nobr></li>
+<ul>
+<li><nobr><a href="#utf-8-byte-p">utf-8-byte-p</a> - tests if a XLISP character is a valid UTF-8 byte</nobr></li>
+<li><nobr><a href="#utf-8-bytes">utf-8-bytes</a> - returns the number of bytes of an UTF-8 character</nobr></li>
+<li><nobr><a href="#utf-8-bytes">utf-8-string-to-list</a> - converts an UTF-8 string to a list of 'string-characters'</nobr></li>
+<li><nobr><a href="#utf-8-bytes">utf-8-list-to-string</a> - converts a list of 'string-characters' to an XLISP string</nobr></li>
+</ul>
+</ul>
+
+<a name=""></a>
+
+<hr>
+
+<h2>make-string</h2>
+
+<hr>
+
+<pre class="example">
+(defun <font color="#0000CC">make-string</font> (length initial-element)
+ (cond ((not (and (integerp length)
+ (plusp length)))
+ (error <font color="#AA0000">"not a positive integer"</font> length))
+ ((not (characterp initial-element))
+ (error <font color="#AA0000">"not a character"</font> initial-element))
+ (t
+ (let ((element (string initial-element))
+ (string <font color="#AA0000">""</font>))
+ (dotimes (x length)
+ (setq string (strcat string element)))
+ string))))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="string-star"></a>
+
+<hr>
+
+<h2>string*</h2>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+
+<dt><nobr>(<b>string*</b> [<i>expr1</i> ...])</nobr></dt>
+<dd><i>exprN</i> - arbitrary Lisp expressions<br>
+returns - the expression[s], converted and concatenated into a single string</dd>
+</dl>
+
+<dl>
+
+</div></p>
+
+<p>The 'string*' function tries to make a string out of everything:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">string*</font> (&rest items)
+ (if (null items)
+ <font color="#880000">""</font>
+ (let ((end (length items))
+ (result <font color="#880000">""</font>))
+ (labels ((strcat-element (element)
+ (let ((string (if (or (consp element) (arrayp element))
+ (string* element)
+ (format nil <font color="#880000">"~a"</font> element))))
+ (setq result (strcat result string)))))
+ (dotimes (index end)
+ (if (eq (nth index items) '*unbound*)
+ (strcat-element <font color="#880000">"*UNBOUND*"</font>)
+ (let ((item (nth index items)))
+ (case (type-of item)
+ (cons (let ((end (length item)))
+ (when (not (consp (last item))) (incf end))
+ (dotimes (index end)
+ (if (eq (nth index item) '*unbound*)
+ (strcat-element <font color="#880000">"*UNBOUND*"</font>)
+ (strcat-element (nth index item))))))
+ (array (let ((end (length item)))
+ (dotimes (index end)
+ (if (eq (aref item index) '*unbound*)
+ (strcat-element <font color="#880000">"*UNBOUND*"</font>)
+ (strcat-element (aref item index))))))
+ (t (strcat-element item))))))
+ result))))
+</pre>
+
+<p>Examples:</p>
+
+<pre class="example">
+(string*) => ""
+
+(string* #\A "B" 'c) => "ABC"
+(string* 1 2 3) => "123"
+
+(string* 1 "st") => "1st"
+(string* "2" #\n #\d) => "2nd"
+
+(setq a 3) => 3
+(string* 'a "=" a) => "A=3"
+</pre>
+
+<p>Nested expressions will be flattened:</p>
+
+<pre class="example">
+(string* #(1 (#\2) "3")) => "123"
+</pre>
+
+<p>The result may contain nonsense:</p>
+
+<pre class="example">
+(string* #'car) => "#<Subr-CAR: #8645768>"
+(string* '(lambda (x) (print x))) => "LAMBDAXPRINTX"
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="posix"></a>
+
+<hr>
+
+<h2>POSIX Character Classes</h2>
+
+<hr>
+
+<p>The <nobr>built-in</nobr> XLISP character test functions
+<a href="../reference/upper-case-p.htm">upper-case-p</a>,
+<a href="../reference/lower-case-p.htm">lower-case-p</a>,
+<a href="../reference/both-case-p.htm">both-case-p</a>, return the boolean
+values <a href="../reference/t.htm"> T </a> or
+<a href="../reference/nil.htm">NIL</a> instead of the tested character,
+while <a href="../reference/digit-char-p.htm">digit-char-p</a> returns an
+integer <nobr>or <a href="../reference/nil.htm">NIL</a></nobr>, what is
+handy if you want to convert arbitrary Lisp symbols into numbers without
+producing an error, but all this is impractical for writing a string
+parser.</p>
+
+<p>The following functions implement tests for the standard POSIX character
+classes, where all functions return the tested character if the test
+succeeds, or <a href="../reference/nil.htm">NIL</a></nobr> if the test
+fails. <nobr>The 'internal'</nobr> functions do not check if the argument is
+a character and therefore are faster than the 'user' functions. Also note
+that XLISP is limited to ASCII characters, so there is no way to find out if
+an unicode character is upper- or lowercase if the character code is greater
+than <nobr>ASCII 127</nobr>.</p>
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td colspan="3"><nobr><b>POSIX</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><b>Internal</b></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><b>User Function</b></nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>alnum</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-alnum-p">char:alnum-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#alnum-character-p">alnum-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>alphanumeric = [a-z], [A-Z], [0-9]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>alpha</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-alpha-p">char:alpha-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#alpha-character-p">alpha-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>alphabetic = [a-z], [A-Z]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>blank</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-blank-p">char:blank-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#blank-character-p">blank-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>space and horizontal-tab</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>cntrl</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-cntrl-p">char:cntrl-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#cntrl-character-p">cntrl-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>code-chars 0-31 and 127</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>digit</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-digit-p">char:digit-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#digit-character-p">digit-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>decimal = [0-9]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>graph</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-graph-p">char:graph-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#graph-character-p">graph-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>graphical = alnum + punct</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>lower</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-lower-p">char:lower-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#lower-character-p">lower-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>lowercase = [a-z]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>print</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-print-p">char:print-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#print-character-p">print-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>printable = alnum + punct + space</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>punct</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-punct-p">char:punct-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#punct-character-p">punct-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>punctuation marks</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>space</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-space-p">char:space-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#space-character-p">space-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>characters producing whitespace</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>upper</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-upper-p">char:upper-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#upper-character-p">upper-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>uppercase = [A-Z]</nobr></td>
+</tr>
+<tr>
+ <td><nobr><code> </code></nobr></td>
+ <td><nobr>[:</nobr></td>
+ <td align="center"><nobr>xdigit</nobr></td>
+ <td><nobr>:]</nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#char-xdigit-p">char:xdigit-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td><nobr><a href="#xdigit-character-p">xdigit-character-p</a></nobr></td>
+ <td><nobr> - </nobr></td>
+ <td width="100%"><nobr>hexadecimal = [0-9], [a-f], [A-F]</nobr></td>
+</tr>
+</tbody></table></p>
+
+<p><b>Internal Functions</b> for POSIX character classes:</p>
+
+<a name="char-alnum-p"></a>
+
+<pre class="example">
+<font color="#008844">;; alphanumeric characters = a-z, A-z, 0-9</font>
+
+(defun <font color="#0000CC">char:alnum-p</font> (char)
+ (and (alphanumericp char)
+ char))
+<a name="char-alpha-p"></a>
+<font color="#008844">;; alphabetic characters = a-z, A-Z</font>
+
+(defun <font color="#0000CC">char:alpha-p</font> (char)
+ (and (both-char-p char)
+ char))
+<a name="char-blank-p"></a>
+<font color="#008844">;; blanks = space and horizontal-tab</font>
+
+(defun <font color="#0000CC">char:blank-p</font> (char)
+ (and (or (char= char #\Space)
+ (char= char #\Tab))
+ char))
+<a name="char-cntrl-p"></a>
+<font color="#008844">;; control characters = code-chars 0-31 and 127</font>
+
+(defun <font color="#0000CC">char:cntrl-p</font> (char)
+ (let ((code (char-code char)))
+ (and (or (<= 0 code 31)
+ (= code 127))
+ char)))
+<a name="char-digit-p"></a>
+<font color="#008844">;; decimal digits = 0-9</font>
+
+(defun <font color="#0000CC">char:digit-p</font> (char)
+ (and (digit-char-p char)
+ char))
+<a name="char-graph-p"></a>
+<font color="#008844">;; graphical characters = alnum + punct</font>
+
+(defun <font color="#0000CC">char:graph-p</font> (char)
+ (and (<= 33 (char-code char) 126)
+ char))
+<a name="char-lower-p"></a>
+<font color="#008844">;; lowercase characters = a-z</font>
+
+(defun <font color="#0000CC">char:lower-p</font> (char)
+ (and (lower-case-p char)
+ char))
+<a name="char-print-p"></a>
+<font color="#008844">;; printable characters = alnum + punct + space</font>
+
+(defun <font color="#0000CC">char:print-p</font> (char)
+ (and (<= 32 (char-code char) 126)
+ char))
+<a name="char-punct-p"></a>
+<font color="#008844">;; punctuation marks</font>
+
+(defun <font color="#0000CC">char:punct-p</font> (char)
+ (let ((code (char-code char)))
+ (and (or (<= 33 code 47) <font color="#008844">; ! " # $ % & ' ( ) * + , - . /</font>
+ (<= 58 code 64) <font color="#008844">; : ; < = > ? @</font>
+ (<= 91 code 96) <font color="#008844">; [ \ ] ^ _ `</font>
+ (<= 123 code 126)) <font color="#008844">; { | } ~</font>
+ char)))
+<a name="char-space-p"></a>
+<font color="#008844">;; characters producing whitespace</font>
+<font color="#008844">;;</font>
+<font color="#008844">;; 9 = horizontal tab 10 = line feed 11 = vertical tab</font>
+<font color="#008844">;; 12 = form feed 13 = carriage return 32 = space</font>
+
+(defun <font color="#0000CC">char:space-p</font> (char)
+ (and (member (char-code char) '(9 10 11 12 13 32))
+ char))
+<a name="char-upper-p"></a>
+<font color="#008844">;; uppercase characters = A-Z</font>
+
+(defun <font color="#0000CC">char:upper-p</font> (char)
+ (and (upper-case-p char)
+ char))
+<a name="char-xdigit-p"></a>
+<font color="#008844">;; hexadecimal digits = 0-9, a-f, A-F</font>
+
+(defun <font color="#0000CC">char:xdigit-p</font> (char)
+ (and (or (digit-char-p char)
+ (let ((code (char-code char)))
+ (or (<= 65 code 70) <font color="#008844">; A-Z</font>
+ (<= 97 code 102)))) <font color="#008844">; a-z</font>
+ char))
+</pre>
+
+<p><b>User Functions</b> for POSIX character classes:</p>
+
+<a name="alnum-character-p"></a>
+
+<pre class="example">
+<font color="#008844">;; alphanumeric characters = a-z, A-z, 0-9</font>
+
+(defun <font color="#0000CC">alnum-character-p</font> (char)
+ (and (characterp char)
+ (char:alnum-p char)))
+<a name="alpha-character-p"></a>
+<font color="#008844">;; alphabetic characters = a-z, A-Z</font>
+
+(defun <font color="#0000CC">alpha-character-p</font> (char)
+ (and (characterp char)
+ (char:alpha-p char)))
+<a name="blank-character-p"></a>
+<font color="#008844">;; blanks = space and horizontal-tab</font>
+
+(defun <font color="#0000CC">blank-character-p</font> (char)
+ (and (characterp char)
+ (char:blank-p char)))
+<a name="cntrl-character-p"></a>
+<font color="#008844">;; control characters = code-chars 0-31 and 127</font>
+
+(defun <font color="#0000CC">cntrl-character-p</font> (char)
+ (and (characterp char)
+ (char:cntrl-p char)))
+<a name="digit-character-p"></a>
+<font color="#008844">;; decimal digits = 0-9</font>
+
+(defun <font color="#0000CC">digit-character-p</font> (char)
+ (and (characterp char)
+ (char:digit-p char)))
+<a name="graph-character-p"></a>
+<font color="#008844">;; graphical characters = alnum + punct</font>
+
+(defun <font color="#0000CC">graph-character-p</font> (char)
+ (and (characterp char)
+ (char:graph-p char)))
+<a name="lower-character-p"></a>
+<font color="#008844">;; lowercase characters = a-z</font>
+
+(defun <font color="#0000CC">lower-character-p</font> (char)
+ (and (characterp char)
+ (char:lower-p char)))
+<a name="print-character-p"></a>
+<font color="#008844">;; printable characters = alnum + punct + space</font>
+
+(defun <font color="#0000CC">print-character-p</font> (char)
+ (and (characterp char)
+ (char:print-p char)))
+<a name="punct-character-p"></a>
+<font color="#008844">;; punctuation marks</font>
+
+(defun <font color="#0000CC">punct-character-p</font> (char)
+ (and (characterp char)
+ (char:punct-p char)))
+<a name="space-character-p"></a>
+<font color="#008844">;; characters producing whitespace</font>
+
+(defun <font color="#0000CC">space-character-p</font> (char)
+ (and (characterp char)
+ (char:space-p char)))
+<a name="upper-character-p"></a>
+<font color="#008844">;; uppercase characters = A-Z</font>
+
+(defun <font color="#0000CC">upper-character-p</font> (char)
+ (and (characterp char)
+ (char:upper-p char)))
+<a name="xdigit-character-p"></a>
+<font color="#008844">;; hexadecimal digits = 0-9, a-f, A-F</font>
+
+(defun <font color="#0000CC">xdigit-character-p</font> (char)
+ (and (characterp char)
+ (char:xdigit-p char)))
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<a name="unicode"></a>
+
+<hr>
+
+<h2>Unicode</h2>
+
+<hr>
+
+<p>The UTF-8 functions may help to write custom <nobr>UTF-8</nobr> string
+access functions like <nobr>UTF-8-SUBSEQ</nobr> or
+<nobr>UTF-8-STRING-SEARCH</nobr> with no need to care about the underlying
+<nobr>low-level</nobr> octal sequences.</p>
+
+
+
+<p>In the list of "string-characters" every ASCII or UTF-8 character
+from 1-byte to 4-byte is represented by its own list element:</p>
+
+<pre class="example">
+(utf-8-string-to-list "hällö") => ("h" "\303\244" "l" "l" "\303\266")
+ h ä l l ö
+</pre>
+
+<p>The list can be manipulated by standard Nyquist list functions and
+then re-converted into a string by UTF-8-LIST-TO-STRING.</p>
+
+Practical examples
+
+<p>In Nyquist code, non-ASCII characters are represented by their
+native bytes sequences, represented by escaped octal numbers:</p>
+
+<pre class="example">
+(print "ä") => "\303\244" <font color="#008844">; on UTF-8 systems</font>
+</pre>
+
+<p>So for example matching the second "ä" from "hällo" in the list
+above, represented by the octal sequence "\303\244":</p>
+
+<pre class="example">
+(let ((string-list (utf-8-string-to-list "hällö")))
+ (string= "ä" (nth 1 string-list))) ; 0 = first, 1 = second element
+=> T ; T = true = identified
+</pre>
+
+<p>Advantage: The number of the element in the list is the same as the
+number of the character in the string, independent from the number of bytes
+in the underlying character encoding.</p>
+
+;; The UTF-8 toolbox is intended to manipulate UTF-8 encoded file-
+;; or directory names, typed in by the user or read from environment
+;; variables, before they are given to SETDIR or OPEN.
+;;
+;; Information from the environment
+;;
+;; Because the encoding of the non-ASCII characters depends on the
+;; underlying operation system [with non-unicode operation systems
+;; there will be no UTF-8 encoding available], it's always better
+;; to refer to strings from environment variables, user input, or
+;; strings returned from the underlying file system, instead of
+;; hand-coded strings in the Nyquist source code, for example:
+;;
+;; GET-ENV - can read strings from environment variables:
+;;
+;; (defun user-home-directory ()
+;; (or (get-env "HOME") ; Unix
+;; (get-env "UserProfile"))) ; Windows
+;;
+;; On Windows, there is no HOME variable defined by Windows itself,
+;; but most programs will respect a HOME variable, if one has been
+;; defined by the user. That's why the HOME variable is read first.
+;;
+;; SETDIR - can test if a directory exists and return its name:
+;;
+;; (defun directory-exists-p (string)
+;; (let ((orig-dir (setdir "."))
+;; (new-dir (setdir string)))
+;; (when (string/= orig-dir new-dir)
+;; (setdir orig-dir)
+;; new-dir)))
+;;
+;; SETDIR always returns abloute direcory names, even if STRING is a
+;; relative direcory name. That's why DIRECTORY-EXISTS-P first stores
+;; the absolute name of the current working directory in the ORIG-DIR
+;; variable and compares it then against the absolute directory name
+;; returned by SETDIR when it tries to change the directory to STRING.
+;;
+;; OPEN - can test if a file exists and return its name:
+;;
+;; (defun file-exists-p (string)
+;; (unless (directory-exists-p string)
+;; (let (file-stream)
+;; (unwind-protect
+;; (setq file-stream (open string))
+;; (when file-stream (close file-stream)))
+;; (when file-stream string))))
+;;
+;; On Unix, a directory is a special kind of file, so the Nyquist/XLISP
+;; OPEN function opens directories, too. That's why FILE-EXISTS-P first
+;; must test and make sure that STRING is not the name of a directory.
+;;
+;;; Known bugs and limitations of the UTF-8 toolbox:
+;;
+;; The UTF-8 toolbox does not provide support for UTF-8 case-detection
+;; or UTF-8 case-conversion. It cannot be detected if a UTF-8 character
+;; is upper- or lowercase, it's also not possible to convert characters
+;; from upper- to lowercase or vice versa.
+;;
+;; The library does not provide functions to compare UTF-8 characters
+;; or to sort UTF-8 characters.
+;;
+;; The XLISP character functions do not work with UTF-8 octal sequences,
+;; so matching must be done via XLISP's STRING= and STRING/= functions.
+;;
+;; The XLISP string comparison functions like STRING<, STRING>, etc.
+;; do not work reliably with multibyte characters.
+;;
+;; The string matching and sorting algorithms of the Unicode Consortium
+;; are too complex to be implemented in XLISP with reasonable speed.
+;;
+;; See: http://www.unicode.org/reports/tr10/ - string comparison
+;;
+;; The library is implemented in interpreted Lisp, so please do not
+;; expect high-speed performance with advanced list manipulations.
+;;
+;; The library still has not been tested with ISO encoded systems.
+;;
+
+<p><b>UTF-8 Encoding</b> - see also http://en.wikipedia.org/wiki/UTF-8</p>
+
+
+<p>In an UTF-8 encoded character the first byte starts with:</p>
+
+<pre class="example">
+;; one-byte 0xxxxxxx -> legal char-codes 0 to 127 [UTF-8/ASCII]
+;; two-byte 110xxxxx -> legal char-codes 194 to 223 [UTF-8]
+;; three-byte 1110xxxx -> legal char-codes 224 to 239 [UTF-8]
+;; four-byte 11110xxx -> legal char-codes 240 to 244 [UTF-8]
+;;
+;; The second, third, and fourth characters start with:
+;;
+;; 10xxxxxx -> legal char-codes 128 to 191 [UTF-8]
+</pre>
+
+
+<p>UTF-8-BYTE-P tests if a XLISP character is a valid UTF-8 byte</p>
+
+<pre class="example">
+(defun utf-8-byte-p (char)
+ (when (characterp char)
+ (let ((code (char-code char)))
+ (when (or (<= 0 code 191)
+ (<= 194 code 244))
+ char))))
+</pre>
+
+<p>UTF-8-BYTES tries to determine from the XLISP character code
+how many bytes the character has in UTF-8 encoding</p>
+
+<pre class="example">
+(defun utf-8-bytes (char)
+ (cond ((not (characterp char))
+ (error "not a character" char))
+ ((not (utf-8-byte-p char))
+ (error "invalid UTF-8 byte" char))
+ (t
+ (let ((code (char-code char)))
+ (cond ((<= 0 code 127) 1) ; one byte [= ASCII]
+ ((<= 194 code 223) 2) ; two bytes
+ ((<= 224 code 239) 3) ; three bytes
+ ((<= 240 code 244) 4) ; four bytes
+ (t (error "utf-8-bytes: not an UTF-8 identifer" char)))))))
+</pre>
+
+<p>UTF-8-STRING-TO-LIST converts a string containing ASCII or UTF-8
+characters from one to four bytes into a list, where:</p>
+
+<ul>
+<li><nobr><b>ASCII</b> - ASCII string</nobr></li>
+<li><nobr><b>UTF-8</b> - string of octal-sequences</nobr></li>
+</ul>
+
+;; Every character (single-byte or multi-byte) is represented
+;; by its own list element:
+;;
+;; (utf-8-string-to-list "hällö") => ("h" "\303\244" "l" "l" "\303\266")
+;; h ä l l ö
+;;
+;; The list can be manipulated by standard XLISP list functions and
+;; then re-converted into a string by UTF-8-LIST-TO-STRING below.
+
+<pre class="example">
+(defun utf-8-string-to-list (string)
+ (cond
+ ((not (stringp string))
+ (error "utf-8-string-to-list: not a string" string))
+ ((string= "" string) nil)
+ (t
+ (let ((end (length string))
+ (list nil))
+ (do ((index 0 (1+ index)))
+ ((>= index end))
+ (let* ((char (char string index))
+ (bytes (1- (utf-8-bytes char)))
+ (utf-8 (string char)))
+ (dotimes (rest-of bytes) ; runs only if bytes > 0
+ (incf index)
+ (if (> index end)
+ (error "utf-8-string-to-list: index out of range" index)
+ (let ((byte (char string index)))
+ (if (not (utf-8-byte-p byte))
+ (error "utf-8-string-to-list: invalid UTF-8 byte" byte)
+ (setq utf-8 (strcat utf-8 (string byte)))))))
+ (push utf-8 list)))
+ (reverse list)))))
+</pre>
+
+;; UTF-8-LIST-TO-STRING re-converts a list containing ASCII and
+;; UTF-8 "string-characters" back to a XLISP string, intended
+;; to be given to SETDIR or OPEN for file or directory operations.
+
+<pre class="example">
+(defun utf-8-list-to-string (list)
+ (cond ((not (listp list))
+ (error "utf-8-list-to-string: not a list" list))
+ ((null list) "")
+ (t
+ (let ((result ""))
+ (dolist (string list)
+ (if (not (stringp string))
+ (error "utf-8-list-to-string: not a string" string)
+ (setq result (strcat result string))))
+ result))))
+</pre>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../manual/contents.htm">Contents</a> |
+<a href="../tutorials/tutorials.htm">Tutorials</a> |
+<a href="examples.htm">Examples</a> |
+<a href="../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/xlisp/ash.htm b/docsrc/xlisp/xlisp-doc/examples/xlisp/ash.htm new file mode 100644 index 0000000..2d17d98 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/xlisp/ash.htm @@ -0,0 +1,130 @@ +<html><head>
+
+<title>ash</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>ash</h1>
+
+<hr>
+
+<p>The 'ash' functio performs an '<nobr>arithmetic shift</nobr>' operation:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>ash</b> <i>integer count</i>)</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>count</i> - an integer expression<br>
+returns - the <i>number</i> shifted by <i>count</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">ash</font> (integer count)
+ (or (integerp integer) (error <font color="#880000">"not an integer"</font> integer))
+ (or (integerp count) (error <font color="#880000">"not an integer"</font> count))
+ (let* ((shift (* integer (expt 2.0 count)))
+ (trunc (truncate shift)))
+ <font color="#008844">;; XLISP implementation of (FLOOR SHIFT)</font>
+ (if (or (plusp shift) (= shift trunc))
+ trunc
+ (1- trunc))))
+</pre>
+
+<p>The 'ash' functio performs an arithmetic shift operation on the binary
+representation of the 'integer' argument, which is treated as if it were
+binary. <nobr>The 'integer'</nobr> argument is shifted arithmetically to the
+left by 'count' bit positions if 'count' is positive, or to the right by
+'count' bit positions if 'count' is negative. <nobr>The shifted</nobr> value
+of the same sign as 'integer' is returned.</p>
+
+<p>The 'ash' function performs the computation:</p>
+
+<pre class="example">
+floor (integer * 2^count)
+</pre>
+
+<p>Logically, the 'ash' function moves all of the bits in integer to the
+left, adding <nobr>zero-bits</nobr> at the right, or moves them to the
+right, discarding bits.</p>
+
+<p>The 'ash' function is defined to behave as if integer were represented in
+two's complement form, regardless of how integers are represented
+internally.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(ash 16 1) => 32
+(ash 16 0) => 16
+(ash 16 -1) => 8
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">debug:ash</font> (integer count)
+ (let ((shifted (ash integer count)))
+ (format t <font color="#880000">"integer: ~a~%"</font> (bin-string integer :all))
+ (format t <font color="#880000">"shifted: ~a~%"</font> (bin-string shifted :all))
+ shifted))
+</pre>
+
+<p>See <nobr><a href="../binary.htm">Binary Integer Numbers</a></nobr> for
+the '<nobr>bin-string</nobr>' function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/xlisp/bsh.htm b/docsrc/xlisp/xlisp-doc/examples/xlisp/bsh.htm new file mode 100644 index 0000000..31c8af6 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/xlisp/bsh.htm @@ -0,0 +1,127 @@ +<html><head>
+
+<title>bsh</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>bsh</h1>
+
+<hr>
+
+<p>The 'bsh' functio performs an '<nobr>binary shift</nobr>' operation:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>bsh</b> <i>integer count</i>)</dt>
+<dd><i>integer</i> - an integer expression<br>
+<i>count</i> - an integer expression<br>
+returns - the <i>number</i> shifted by <i>count</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">bsh</font> (integer count)
+ (or (integerp integer) (error <font color="#880000">"not an integer"</font> integer))
+ (or (integerp count) (error <font color="#880000">"not an integer"</font> count))
+ (if (zerop count)
+ integer
+ (let ((digits (or (dolist (bits '(16 32 64 128) nil)
+ (let ((fixnum (round (expt 2.0 (1- bits)))))
+ (and (plusp (1- fixnum))
+ (minusp fixnum)
+ (return bits))))
+ (error <font color="#880000">"integer limit not found"</font>)))
+ (list nil)
+ (string "#b"))
+ (dotimes (x digits)
+ (let ((digit (logand (round (expt 2.0 x)) integer)))
+ (push (if (zerop digit) "0" "1") list)))
+ (dotimes (x digits)
+ (let ((digit (if (< -1 count digits) (nth count list) "0")))
+ (setq string (strcat string digit))
+ (incf count)))
+ (eval (read (make-string-input-stream string))))))
+</pre>
+
+<p>The 'bsh' function performs a binary shift operation on the 'integer'
+argument. <nobr>The bits</nobr> of the 'integer' argument is shifted to the
+left by 'count' positions if 'count' is positive, or to the right by 'count'
+positions if 'count' is negative. <nobr>The missing</nobr> bits are filled
+with zeros.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(bsh 16 1) =>
+(bsh 16 0) =>
+(bsh 16 -1) =>
+</pre>
+
+<pre class="example">
+(defun <font color="#0000CC">debug:bsh</font> (integer count)
+ (let ((shifted (bsh integer count)))
+ (format t <font color="#880000">"integer: ~a~%"</font> (bin-string integer :all))
+ (format t <font color="#880000">"shifted: ~a~%"</font> (bin-string shifted :all))
+ shifted))
+</pre>
+
+<p>See <nobr><a href="../binary.htm">Binary Integer Numbers</a></nobr> for
+the '<nobr>bin-string</nobr>' function.</p>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/xlisp/ceiling.htm b/docsrc/xlisp/xlisp-doc/examples/xlisp/ceiling.htm new file mode 100644 index 0000000..a005ff1 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/xlisp/ceiling.htm @@ -0,0 +1,103 @@ +<html><head>
+
+<title>ceiling</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>ceiling</h1>
+
+<hr>
+
+<p>The 'ceiling' function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward positive infinity:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>ceiling</b> <i>number</i>)</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> expression<br>
+returns - the integer result of truncating <i>number</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">ceiling</font> (number)
+ (let ((trunc (truncate number)))
+ (if (or (minusp number) (= number trunc))
+ trunc
+ (1+ trunc))))
+</pre>
+
+<p>The 'ceiling' function computes an integer number that has
+been truncated toward positive infinity. <nobr>That is</nobr>, the result
+represents the smallest mathematical integer that is not smaller than the
+number given as argument.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(ceiling 3) => 3 (ceiling -3) => -3
+(ceiling 3.0) => 3 (ceiling -3.0) => -3
+(ceiling 3.1) => 4 (ceiling -3.1) => -3
+(ceiling 3.5) => 4 (ceiling -3.5) => -3
+(ceiling 3.9) => 4 (ceiling -3.9) => -3
+(ceiling 4.0) => 4 (ceiling -4.0) => -4
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/xlisp/floor.htm b/docsrc/xlisp/xlisp-doc/examples/xlisp/floor.htm new file mode 100644 index 0000000..5851166 --- /dev/null +++ b/docsrc/xlisp/xlisp-doc/examples/xlisp/floor.htm @@ -0,0 +1,103 @@ +<html><head>
+
+<title>floor</title>
+
+<style type="text/css">
+.example {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ width:auto;
+}
+.button {
+ color: #000000;
+ background-color: #F5F5F5;
+ padding-top: 1px;
+ padding-bottom: 1px;
+ padding-left: 4px;
+ padding-right: 8px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+ white-space: pre;
+}
+.box {
+ color: #000000;
+ padding-top: 4px;
+ padding-bottom: 4px;
+ padding-left: 16px;
+ padding-right: 16px;
+ border: #808080;
+ border-style: solid;
+ border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>floor</h1>
+
+<hr>
+
+<p>The 'floor' function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward negative infinity:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>floor</b> <i>number</i>)</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> expression<br>
+returns - the integer result of truncating <i>number</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">floor</font> (number)
+ (let ((trunc (truncate number)))
+ (if (or (plusp number) (= number trunc))
+ trunc
+ (1- trunc))))
+</pre>
+
+<p>The 'floor' function computes an integer number that has been truncated
+toward negative infinity. <nobr>That is</nobr>, the result represents the
+largest mathematical integer that is not larger than the number given as
+argument.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(floor 3) => 3 (floor -3) => -3
+(floor 3.0) => 3 (floor -3.0) => -3
+(floor 3.1) => 3 (floor -3.1) => -4
+(floor 3.5) => 3 (floor -3.5) => -4
+(floor 3.9) => 3 (floor -3.9) => -4
+(floor 4.0) => 4 (floor -4.0) => -4
+</pre>
+
+<p><nobr> <a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a> -
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
|