Debian Codegraph @

docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-values.htm

raw
1 <html><head>
2
3 <title>Multiple Values</title>
4
5 <style type="text/css">
6 .example {
7 color: #000000;
8 background-color: #F5F5F5;
9 padding: 8px;
10 border: #808080;
11 border-style: solid;
12 border-width: 1px;
13 width:auto;
14 }
15 .button {
16 color: #000000;
17 background-color: #F5F5F5;
18 padding-top: 1px;
19 padding-bottom: 1px;
20 padding-left: 4px;
21 padding-right: 8px;
22 border: #808080;
23 border-style: solid;
24 border-width: 1px;
25 white-space: pre;
26 }
27 .box {
28 color: #000000;
29 padding-top: 4px;
30 padding-bottom: 4px;
31 padding-left: 16px;
32 padding-right: 16px;
33 border: #808080;
34 border-style: solid;
35 border-width: 1px;
36 }
37 </style>
38
39 </head>
40
41 <body>
42
43 <a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
44 <a href="../../manual/contents.htm">Contents</a> |
45 <a href="../../tutorials/tutorials.htm">Tutorials</a> |
46 <a href="../examples.htm">Examples</a> |
47 <a href="../../reference/reference-index.htm">Reference</a>
48
49 <hr>
50
51 <h1>Multiple Values</h1>
52
53 <hr>
54
55 <ol>
56 <li><nobr><a href="#multiple-values">Multiple Values</a></nobr></li>
57 <ul>
58 <li><nobr>Nyquist/XLISP helpers</nobr></li>
59 <ul>
60 <li><nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a> - [Variable] - signals if a function has returned multiple values</nobr></li>
61 <li><nobr><a href="debug-mv.htm">cl:debug:mv</a> - [Function] - debug multiple values</nobr></li>
62 </ul>
63 <li><nobr>Returning Multiple Values</nobr></li>
64 <ul>
65 <li><nobr><a href="values.htm">cl:values</a> - [Function] - return multiple values</nobr></li>
66 <li><nobr><a href="values-list.htm">cl:values-list</a> - [Function] - return multiple values from a list</nobr></li>
67 </ul>
68 <li><nobr>Working with Multiple Values</nobr></li>
69 <ul>
70 <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>
71 <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>
72 <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>
73 <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>
74 <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>
75 </ul>
76 </ul>
77 </ol>
78
79 <a name="multiple-values"></a>
80
81 <hr>
82
83 <h2>Multiple Values</h2>
84
85 <hr>
86
87 <p>This is a port of the Common List framework for passing multiple values
88 from one place to another. <nobr>It is</nobr> most often used to return
89 multiple values from a function with
90 <a href="values.htm">cl:values</a> or to bind multiple values to multiple
91 variables with
92 <nobr><a href="multiple-value-bind.htm">cl:multiple-value-bind</a></nobr> or
93 <nobr><a href="multiple-value-setq.htm">cl:multiple-value-setq</a></nobr>.</p>
94
95 <p>The multiple value functions and macros use the
96 <nobr>Nyquist/XLISP</nobr>
97 <a href="../../reference/global-rslt.htm">*rslt*</a> variable to store the
98 values as a list, while the
99 <nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
100 variable is used as a flag to indicate if a function has returned multiple
101 values.</p>
102
103 <p><b>What happens if a normal Lisp function are given multiple
104 values?</b></p>
105
106 <p>A normal Lisp function only sees the 'primary' return value, as returned
107 by every Lisp function. <nobr>The additional</nobr> return values
108 [including the primary return value] are stored in the
109 <a href="../../reference/global-rslt.htm">*rslt*</a> variable and are only read
110 by the multiple value functions. This also means that with multiple values,
111 the most important value should always be returned as the first value,
112 because only the first value can be seen by a normal Lisp function.
113 <nobr>See <a href="values.htm">cl:values</a></nobr> for examples.</p>
114
115 <p><b>What happens if a function expecting multiple values is given a normal
116 Lisp return value?</b></p>
117
118 <p>The first symbol will be set to the function's return value, while all
119 other symbol will be set to <a href="../../reference/nil.htm">NIL</a>.
120 <nobr>No symbol</nobr> will be left unset. <nobr>All functions</nobr>
121 expecting multiple values are protected against a wrong number of values.
122 <nobr>If there</nobr> are more symbols than values, then the extra symbols
123 are set to <a href="../../reference/nil.htm">NIL</a>, if there are more
124 values than symbols, the extra values will be ignored.</p>
125
126 <p><div class="box">
127
128 <p><b>Known Limitations</b></p>
129
130 <p><b>1.</b> In Nyquist/XLISP, <a href="values.htm">cl:values</a> cannot be
131 used as argument to <a href="../../reference/setf.htm">setf</a>. <nobr>But
132 this</nobr> is not a real problem, because the values are stored as a
133 simple list in the <a href="../../reference/global-rslt.htm">*rslt*</a>
134 variable, where they can be manipulated with any arbitrary Lisp
135 functions, not only <nobr>with
136 <a href="../../reference/setf.htm">setf</a></nobr>.</p>
137
138 <p><b>2.</b> In <nobr>Common Lisp</nobr> there exists the option to return
139 <nobr>'no value</nobr>' by calling the 'values' function with no arguments.
140 <nobr>In Nyquist/XLISP</nobr> there is no <nobr>built-in</nobr> way to
141 return '<nobr>no value</nobr>' from a function. <nobr>The symbol</nobr>
142 <a href="../../reference/global-unbound.htm">*unbound*</a> cannot be used for
143 this because in <nobr>Common Lisp</nobr>, if '<nobr>no value</nobr>' is
144 assigned to a symbol as variable value, the new value will be
145 <a href="../../reference/nil.htm">NIL</a> and not
146 <a href="../../reference/global-unbound.htm">*unbound*</a>.</p>
147
148 <p>In Nyquist/XLISP, the <a href="values.htm">cl:values</a> function, if
149 called with no arguments, always returns
150 <a href="../../reference/nil.htm">NIL</a>, and the
151 <a href="../../reference/global-rslt.htm">*rslt*</a> variable will be
152 set <nobr>to <a href="../../reference/nil.htm">NIL</a>, too:</nobr></p>
153
154 <pre class="example">
155 (cl:values) =&gt; NIL <font color="#008844">; *rslt* = NIL</font>
156 (cl:values nil) =&gt; NIL <font color="#008844">; *rslt* = (NIL)</font>
157 </pre>
158
159 <p>Maybe this observation helps to write a '<nobr>no values</nobr>' test if
160 anybody really <nobr>needs it</nobr>.</p>
161
162 <p><b>3.</b> Neither in <nobr>Common Lisp</nobr> nor in Nyquist/XLISP is it
163 possibe to return nested multiple values:</p>
164
165 <pre class="example">
166 (cl:values (1 (cl:values 2 3) 4) =&gt; 1 <font color="#008844">; *rslt* = (1 2 4)</font>
167 </pre>
168
169 </div></p>
170
171 <p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
172
173 <hr>
174
175 <a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
176 <a href="../../manual/contents.htm">Contents</a> |
177 <a href="../../tutorials/tutorials.htm">Tutorials</a> |
178 <a href="../examples.htm">Examples</a> |
179 <a href="../../reference/reference-index.htm">Reference</a>
180
181 </body></html>