Debian Codegraph @

docsrc/xlisp/xlisp-doc/examples/apropos.htm

raw
1 <html><head>
2
3 <title>apropos</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>apropos</h1>
52
53 <hr>
54
55
56
57 <p><div class="box">
58
59 <dl>
60
61 <dt><p><nobr>(<b>apropos</b> &amp;optional <i>pattern type</i>)</nobr></p></dt>
62
63 <dd><p>The 'apropos' function searches the Nyquist/XLISP *obarray* for
64 matching symbol names containing 'pattern' and being of 'type'. <nobr>It
65 prints</nobr> a list of the results in alphabetical order.</p>
66
67 <p>'pattern and 'type' can be given as symbols or strings. <nobr>If
68 no</nobr> 'pattern' is given, all symbol names are considered as matching.
69 <nobr>If no</nobr> 'type' is given, all symbol types are considered as
70 matching. With 'type', only the first letter is important. <nobr>A
71 type</nobr> of 'f' searches for symbols with a valid function value, while a
72 type of 'v' searches for symbols with a valid variable value.</p></dd>
73
74 </dd>
75
76 </dl>
77
78 </div></p>
79
80 <p>Examples:</p>
81
82 <p><table cellpadding="0" cellspacing="0"><tbody>
83 <tr>
84 <td><nobr><code>&nbsp;&nbsp;</code></nobr></td>
85 <td valign="top">
86 <table cellpadding="0" cellspacing="0" width="100%"><tbody>
87 <tr valign="top">
88 <td class="button"><nobr><code>(apropos)</code></nobr></td>
89 </tr>
90 </tbody></table>
91 </td>
92 <td valign="top"><nobr>&nbsp;&nbsp;-&nbsp;</nobr></td>
93 <td width="100%"><nobr>all symbols known by Nyquist</nobr></td>
94 </tr>
95 <tr>
96 <td height="2px"></td>
97 </tr>
98 <tr>
99 <td><nobr><code>&nbsp;&nbsp;</code></nobr></td>
100 <td valign="top">
101 <table cellpadding="0" cellspacing="0" width="100%"><tbody>
102 <tr valign="top">
103 <td class="button"><nobr><code>(apropos nil 'f)</code></nobr></td>
104 </tr>
105 </tbody></table>
106 </td>
107 <td valign="top"><nobr>&nbsp;&nbsp;-&nbsp;</nobr></td>
108 <td width="100%"><nobr>all bound functions known by Nyquist</nobr></td>
109 </tr>
110 <tr>
111 <td height="2px"></td>
112 </tr>
113 <tr>
114 <td><nobr><code>&nbsp;&nbsp;</code></nobr></td>
115 <td valign="top">
116 <table cellpadding="0" cellspacing="0" width="100%"><tbody>
117 <tr valign="top">
118 <td class="button"><nobr><code>(apropos nil 'v)</code></nobr></td>
119 </tr>
120 </tbody></table>
121 </td>
122 <td valign="top"><nobr>&nbsp;&nbsp;-&nbsp;</nobr></td>
123 <td width="100%"><nobr>all bound variables known by Nyquist</nobr></td>
124 </tr>
125 <tr>
126 <td height="2px"></td>
127 </tr>
128 <tr>
129 <td><nobr><code>&nbsp;&nbsp;</code></nobr></td>
130 <td valign="top">
131 <table cellpadding="0" cellspacing="0" width="100%"><tbody>
132 <tr valign="top">
133 <td class="button"><nobr><code>(apropos 'snd 'f)</code></nobr></td>
134 </tr>
135 </tbody></table>
136 </td>
137 <td valign="top"><nobr>&nbsp;&nbsp;-&nbsp;</nobr></td>
138 <td width="100%"><nobr>all function names containing 'snd'</nobr></td>
139 </tr>
140 </tbody></table></p>
141
142 <p>A method to introspect classes and objects:</p>
143
144 <pre class="example">
145 (setq instance-var '*wrong-variable*) ; value outside the object
146
147 (setq my-class (send class :new '(instance-var))) ; class with instance variable
148 (send my-class :answer :isnew '() '((setq instance-var '*OK*))) ; value inside an object
149 (send my-class :answer :eval '(list) '((eval list))) ; evaluation method
150
151 (setq my-object (send my-class :new)) ; instance of my-class
152 (send my-object :eval 'instance-var) =&gt; <font color="#008844">*OK*</font>
153 (send my-object :eval '(apropos 'instance-var 'v t)) =&gt; <font color="#AA0000">*WRONG-VARIABLE*</font>
154 </pre>
155
156 <p>The first version works because the call to 'eval' happens inside the
157 object:</p>
158
159 <pre class="example">
160 (send my-class :answer :eval '(list) '((eval list))) =&gt; <font color="#008844">*OK*</font>
161 </pre>
162
163 <p>The second version doesn't work because the call to 'eval' happens
164 outside the object:</p>
165
166 <pre class="example">
167 (defun <font color="#0000CC">external-function</font> (list)
168 (eval list))
169
170 (send my-class :answer :eval '(list) '((external-function list))) =&gt; <font color="#AA0000">*WRONG-VARIABLE*</font>
171 </pre>
172
173 <p>The call to 'apropos' doesn't work because 'apropos' is executed outside
174 the object:</p>
175
176 <pre class="example">
177 (send my-object :eval '(apropos)) =&gt; <font color="#AA0000">*WRONG-VARIABLE*</font>
178 </pre>
179
180 <p>The trick is to pass the Lisp code of 'apropos' as a list into the inside
181 of the object and 'apply' it there to the arguments:</p>
182
183 <pre class="example">
184 (send my-class :answer :apropos '(args)
185 '((apply (get-lambda-expression #'apropos) args)))
186
187 (send my-object :apropos '(instance-var v t)) =&gt; <font color="#008844">*OK*</font>
188 </pre>
189
190 <p>But this only works if all function that need access to internal instance
191 or class variables are executed inside the object. For example, if 'apropos'
192 calls a function that needs access to an internal instance variable, I
193 would get a 'unbound variable' error.</p>
194
195 <p>Here is the code of the 'apropos' function:</p>
196
197 <pre class="example">
198 (defun <font color="#0000CC">apropos</font> (&amp;optional pattern type)
199 (let (result-list (<font color="#AA5500">*gc-flag*</font> nil))
200 <font color="#008844">;; make sure 'pattern' is a string, either empty or upper-case</font>
201 (if pattern
202 (setf pattern (string-upcase (string pattern)))
203 (setf pattern <font color="#880000">""</font>))
204 <font color="#008844">;; take only the first letter of 'type' and make it an upper-case string</font>
205 (if type (setf type (string-upcase (subseq (string type) 0 1))))
206 <font color="#008844">;; go through all entries in the *obarray* symbol hash table</font>
207 (dotimes (i (length <font color="#AA5500">*obarray*</font>))
208 (let ((entry (aref <font color="#AA5500">*obarray*</font> i))) <font color="#008844">; *obarray* is an array of lists</font>
209 <font color="#008844">;; if the *obarray* entry is not an empty list</font>
210 (if entry
211 <font color="#008844">;; go through all elements of the *obarray* entry list</font>
212 <font color="#008844">;; do not use 'dolist' because *obarray* contains *unbound*</font>
213 (dotimes (j (length entry))
214 <font color="#008844">;; convert the symbol to a string to enable pattern matching</font>
215 (let ((string (string (nth j entry))))
216 <font color="#008844">;; if the symbol string matches the search pattern</font>
217 (if (string-search pattern string)
218 <font color="#008844">;; if a special symbol type to search for was given</font>
219 (if type
220 <font color="#008844">;; if a 'type' search was initiated and the current</font>
221 <font color="#008844">;; symbol has no 'type' value bound to it, do nothing</font>
222 <font color="#008844">;; and return from 'cond' without adding the symbol</font>
223 <font color="#008844">;; string to the result list</font>
224 (cond ((and (string= type <font color="#880000">"F"</font>) <font color="#008844">; bound functions only</font>
225 (not (fboundp (nth j entry))))
226 nil)
227 ((and (string= type <font color="#880000">"V"</font>) <font color="#008844">; bound variables only</font>
228 (not (boundp (nth j entry))))
229 nil)
230 <font color="#008844">;; if the symbol has passed all tests,</font>
231 <font color="#008844">;; add the symbol string to the result list</font>
232 (t (setf result-list (cons string result-list))))
233 <font color="#008844">;; if no special symbol type to search for had been given,</font>
234 <font color="#008844">;; but the symbol string had matched the search pattern,</font>
235 <font color="#008844">;; add the symbol string to the result list</font>
236 (setf result-list (cons string result-list)))))))))
237 <font color="#008844">;; if the result list contains more than one element</font>
238 <font color="#008844">;; make it become an alphabetically sorted list</font>
239 (if (> (length result-list) 1)
240 (setf result-list (sort result-list 'string&lt;)))
241 <font color="#008844">;; print a message according to the search type and pattern</font>
242 (cond ((and type (string= type <font color="#880000">"F"</font>)) (setf type <font color="#880000">"function"</font>))
243 ((and type (string= type <font color="#880000">"V"</font>)) (setf type <font color="#880000">"variable"</font>))
244 (t (setf type <font color="#880000">"symbol"</font>)))
245 (if (string= pattern <font color="#880000">""</font>)
246 (format t <font color="#880000">"All ~a names known by Nyquist:~%"</font> type)
247 (format t <font color="#880000">"All ~a names containing pattern ~a:~%"</font> type pattern))
248 <font color="#008844">;; print the search results</font>
249 (cond (result-list
250 (let ((list-length (length result-list)))
251 (format t <font color="#880000">";; number of symbols: ~a~%"</font> list-length)
252 (dolist (i result-list) (format t <font color="#880000">"~a~%"</font> i))
253 (if (> list-length 20)
254 (format t <font color="#880000">";; number of symbols: ~a~%"</font> list-length))))
255 (t (format t <font color="#880000">"No matches found."</font>)))))
256 </pre>
257
258 <p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
259
260 <hr>
261
262 <a href="../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
263 <a href="../manual/contents.htm">Contents</a> |
264 <a href="../tutorials/tutorials.htm">Tutorials</a> |
265 <a href="examples.htm">Examples</a> |
266 <a href="../reference/reference-index.htm">Reference</a>
267
268 </body></html>