source: project/wiki/eggref/5/apropos @ 36033

Last change on this file since 36033 was 36033, checked in by Kon Lovett, 2 years ago

rel 3.1.0

File size: 13.1 KB
Line 
1[[tags: egg]]
2
3== apropos
4
5[[toc:]]
6
7
8== Documentation
9
10An ''apropos'' facility for Chicken Scheme.
11
12=== Apropos API
13
14== Usage
15
16<enscript language=scheme>
17(import apropos-api)
18</enscript>
19
20==== apropos
21
22<procedure>(apropos PATTERN #!key macros? qualified? sort case-insensitive? raw? base split)</procedure>
23
24Displays information about symbols matching {{PATTERN}} in the toplevel
25environment.
26
27; {{PATTERN}} : A {{symbol}}, {{string}}, {{irregex}}, {{irregex-sre}}, {{(quote symbol)}}, {{(quote string)}}. When unquoted symbol or string substring matching is performed. When quoted the string value is taken as an irregex regular expression string for use with search. Should {{PATTERN}} be a namespace qualified symbol the namespace will be dropped before conversion to a regular-expression.
28; {{MACROS?}} : Either {{#t}} to include macros, or {{#f}} to skip them. Default is {{#f}}.
29; {{QUALIFIED?}} : Either {{#t}} to include qualified symbols or {{#f}} to skip them. Default is {{#f}}.
30; {{CASE-INSENSITIVE?}} : Either {{#t}} to use match case-insensitivity for the {{PATTERN}} or {{#f}} to be case-sensitive. Default is {{#f}}.
31; {{SORT}} : Either {{#:name}} for an symbol sort, {{#:module}} for an module symbol sort, or {{#:type}} for a type+indentifier sort, or {{#f}} for unsorted. Default is {{#:type}}.
32; {{SPLIT}} : Either {{#:name}} for an symbol match, {{#:module}} for an module match, or {{#f}} for any. Default is {{#f}}.
33; {{RAW}} : Do not strip identifier symbols. The default is {{#f}}. Use {{#:raw? #t}} when ''apropos'' is suspected of hiding information.
34; {{BASE}} : {{fixnum}} in {{2..16}}. The default is {{10}}. {{BASE}} is used to convert a {{number}} to a string {{PATTERN}}. Of dubious utility. But can ''fix'' the situation of entering a hex number, say {{#x1c}}, for the pattern using the REPL and matching against {{28}}!
35
36==== apropos-list
37
38<procedure>(apropos-list PATTERN #!key macros? qualified? case-insensitive? raw? base) => list</procedure>
39
40Like {{apropos}} but returns an, unsorted, list of matching symbols.
41
42==== apropos-information-list
43
44<procedure>(apropos-information-list PATTERN #!key macros? qualified? sort case-insensitive? raw? base) => list</procedure>
45
46Like {{apropos}} but returns a list key'ed by {{(MODULE . NAME)}}.
47
48{{MODULE}} is the module symbol or {{||}} for the null module.
49
50{{NAME}} is the base symbol.
51
52The associated information is either:
53; {{'macro}} :
54; {{'keyword}} :
55; {{'variable}} :
56; {{'procedure}} :
57; {{'(procedure . <lambda-list-specification>)}} :
58; {{'(procedure . <core procedure name>)}} :
59
60==== apropos-default-base
61
62<parameter>(apropos-default-base [BASE]) -> fixnum</parameter>
63
64{{BASE}} is a {{fixnum}} in {{[2 16]}}, default {{10}}.
65
66==== apropos-default-options
67
68<parameter>(apropos-default-options [OPTIONS]) -> list</parameter>
69
70{{OPTIONS}} is an {{apropos}} #!key argument list, default {{'()}}.
71
72==== apropos-interning
73
74<parameter>(apropos-interning [FLAG]) -> boolean</parameter>
75
76Use {{string->symbol}} - {{#t}} - or {{string->uninterned-symbol}} - {{#f}},
77default {{#t}}.
78
79
80== Examples
81
82* YMMV
83
84<enscript language=scheme>
85> (apropos 'print)
86flonum-print-precision                     procedure tmp
87fprintf                                    procedure (port fstr . args)
88max-symbol-printname-length  symbol-utils  procedure (syms)
89pretty-print                               procedure (obj . opt)
90pretty-print-expand*         expand-full   procedure (form . tmp)
91pretty-print-width                         procedure args
92print                                      procedure args
93print*                                     procedure args
94print-call-chain                           procedure tmp
95print-error-message                        procedure (ex . args)
96printf                                     procedure (fstr . args)
97sprintf                                    procedure (fstr . args)
98symbol-printname-details     symbol-utils  procedure (sym)
99symbol-printname-length      symbol-utils  procedure (sym)
100symbol-printname<?           symbol-utils  procedure (x y)
101symbol-printname=?           symbol-utils  procedure (x y)
102char-set:printing                          variable
103</enscript>
104
105<enscript language=scheme>
106> (pp (apropos-list 'print))
107((expand-full#pretty-print-expand*
108  symbol-utils#max-symbol-printname-length
109  symbol-utils#symbol-printname-length
110  print-error-message
111  print-call-chain
112  sprintf
113  symbol-utils#symbol-printname-details
114  printf
115  print*
116  char-set:printing
117  print
118  fprintf
119  symbol-utils#symbol-printname=?
120  symbol-utils#symbol-printname<?
121  pretty-print
122  flonum-print-precision
123  pretty-print-width))
124</enscript>
125
126<enscript language=scheme>
127> (pp (apropos-information-list 'print))
128((((||: . flonum-print-precision) procedure . tmp)
129 ((||: . fprintf) procedure port fstr . args)
130 ((symbol-utils . max-symbol-printname-length) procedure syms)
131 ((||: . pretty-print) procedure obj . opt)
132 ((expand-full . pretty-print-expand*) procedure form . tmp)
133 ((||: . pretty-print-width) procedure . args)
134 ((||: . print) procedure . args)
135 ((||: . print*) procedure . args)
136 ((||: . print-call-chain) procedure . tmp)
137 ((||: . print-error-message) procedure ex . args)
138 ((||: . printf) procedure fstr . args)
139 ((||: . sprintf) procedure fstr . args)
140 ((symbol-utils . symbol-printname-details) procedure sym)
141 ((symbol-utils . symbol-printname-length) procedure sym)
142 ((symbol-utils . symbol-printname<?) procedure x y)
143 ((symbol-utils . symbol-printname=?) procedure x y)
144 ((||: . char-set:printing) . variable)))
145</enscript>
146
147<enscript language=scheme>
148> (apropos 'print #:qualified? #t)
149printer:                                     keyword
150flonum-print-precision                       procedure tmp
151fprintf                                      procedure (port fstr . args)
152max-symbol-printname-length    symbol-utils  procedure (syms)
153pretty-print                                 procedure (obj . opt)
154pretty-print-expand*           expand-full   procedure (form . tmp)
155pretty-print-width                           procedure args
156print                                        procedure args
157print*                                       procedure args
158print-call-chain                             procedure tmp
159print-error-message                          procedure (ex . args)
160printf                                       procedure (fstr . args)
161sprintf                                      procedure (fstr . args)
162symbol-printname-details       symbol-utils  procedure (sym)
163symbol-printname-length        symbol-utils  procedure (sym)
164symbol-printname<?             symbol-utils  procedure (x y)
165symbol-printname=?             symbol-utils  procedure (x y)
166##sys#print                                  procedure (x readable port)
167##sys#print-length-limit                     procedure args
168##sys#print-to-string                        procedure (xs)
169##sys#really-print-call-chain                procedure (port chain header)
170##sys#register-record-printer                procedure (type proc)
171##sys#repl-print-hook                        procedure (x port)
172##sys#user-print-hook                        procedure (x readable port)
173##sys#with-print-length-limit                procedure (limit thunk)
174char-set:printing                            variable
175##sys#record-printers                        variable
176##sys#repl-print-length-limit                variable
177</enscript>
178
179=== Apropos CSI
180
181== Usage
182
183<enscript language=scheme>
184(import apropos-csi)
185</enscript>
186
187A {{csi}} toplevel-command is added when the {{apropos-csi}} extension is
188loaded by the interpreter, {{a}}.
189
190{{,a PATTERN ARGUMENT ...}}
191
192{{ARGUMENT}} is interpreted as:
193
194; {{mac[ros]}} : {{#:macros? #t}}
195; {{qual[ified]}} : {{#:qualified? #t}}
196; {{sort [name|module|type|#f]}} : {{#:sort #:name|#:module|#:type|#f}}
197; {{split [name|module|#f]}} : {{#:split #:name|#:module|#f}}
198; {{case-insensitve|ci}} : {{#:case-insensitive? #t}}
199; {{base 2..16}} : {{#:base 2..16}}
200
201The command is interpreted by the {{apropos}} procedure, but sort by type is
202the default.
203
204Example:
205
206<enscript language=scheme>
207#;1> ,a print qualified macros sort name
208char-set:printing                            variable
209define-record-printer                        macro
210flonum-print-precision                       procedure tmp
211fprintf                                      procedure (port fstr . args)
212max-symbol-printname-length    symbol-utils  procedure (syms)
213pretty-print                                 procedure (obj . opt)
214  ...
215##sys#register-record-printer                procedure (type proc)
216##sys#repl-print-hook                        procedure (x port)
217##sys#repl-print-length-limit                variable
218##sys#user-print-hook                        procedure (x readable port)
219##sys#with-print-length-limit                procedure (limit thunk)
220</enscript>
221
222<enscript language=scheme>
223#;1> ,a '"w.*e" macros
224eval-when                                    macro
225when                                         macro
226bitwise-and                                  procedure xs
227bitwise-ior                                  procedure xs
228bitwise-not                                  procedure (x)
229bitwise-xor                                  procedure xs
230call-with-current-continuation               procedure (proc)
231  ...
232write-string                                 procedure (s . more)
233char-set:lower-case                          variable
234char-set:whitespace                          variable
235</enscript>
236
237<enscript language=scheme>
238#;1> ,a '(: (* any)) qualified macros sort name
239*                                                           procedure C_times
240  ... 1600 lines + ...
241##sys#write-char/port                                       procedure (c port)
242</enscript>
243
244
245== Usage
246
247<enscript language=scheme>
248(import apropos)
249</enscript>
250
251* Exports {{apropos-api}} & {{apropos-csi}}.
252
253
254== Requirements
255
256[[check-errors]]
257[[miscmacros]]
258[[symbol-utils]]
259[[string-utils]]
260
261
262== Notes
263
264* Use {{"?"}} as the {{PATT}} to list symbols containing a {{#\?}}.
265
266<enscript language=scheme>
267#;1> ,a "?"
268abandoned-mutex-exception?                            procedure (x)
269                                ...
270zero?                                                 procedure (n)
271</enscript>
272
273
274== Bugs and Limitations
275
276* Doesn't show something similar to procedure-information for macros. Requires
277meta-information beyond that supplied by the transformer procedure.
278
279* The support for macros is ''brittle'' due to subtle details of the core
280macro machinary assumed by this extension. Submit a bug report if it breaks.
281
282
283== Author
284
285[[/users/kon-lovett|Kon Lovett]]
286
287
288== Version history
289
290; 3.1.0 : Add {{apropos-api}} & {{apropos-csi}}. Add {{apropos-default-base}}, {{check-apropos-number-base}}, {{apropos-sort-key?}}, {{check-apropos-sort-key}}, & {{error-apropos-sort-key}}.
291; 3.0.0 : CHICKEN 5 release.
292; 2.7.2 : Expanded help text.
293; 2.7.1 : Fix {{apropos-list}} unrecognized {{#:sort}}.
294; 2.7.0 : Add {{apropos-default-options}}. Add {{#:split}} option.
295; 2.6.5 : Fix identifier sorting.
296; 2.6.4 : Cosmetic.
297; 2.6.3 : '''CSI:Help'''.
298; 2.6.2 : Better (some?) support for identifiers with #s.
299; 2.6.1 : Added ''Notes''
300; 2.6.0 : check {{,?}}.
301; 2.5.2 : Fix doc.
302; 2.5.1 : Add {{apropos-interning}}.
303; 2.5.0 : Strip {{gensym}} contribution to identifiers (EXPERIMENTAL).
304; 2.4.0 : Add {{base}}.
305; 2.3.0 : Identifiers are now {{(<module> . <name>)}} for the {{information-list}}.
306; 2.2.5 : Re-flow.
307; 2.2.4 : Less C.
308; 2.2.3 : Fix only boolean/char REPL bug, re-flow.
309; 2.2.2 : Fix only number REPL bug, re-flow.
310; 2.2.1 : .
311; 2.2.0 : correct interpretation of unquoted string/symbol as a literal string, fix sorting support for apropos-information-list, add case-insensitive option
312; 2.1.3 : fix for ticket #1211, incorrect load of regex when irregex is actual dependency
313; 2.1.2 : fix for removed core support routine
314; 2.1.1 : Fix for ticket #987
315; 2.1.0 : Added irregex sre & POSIX string patterns.
316; 2.0.0 : Chicken 4.8 only.
317; 1.4.3 : Explicit {{regex}} dependency.
318; 1.4.2 : Using utility libraries, rather than own routines.
319; 1.4.1 : Bugfix for sorting symbols by printname. {{kind:}} is now {{type:}}.
320; 1.4.0 : Macros are back but '''brittle'''
321; 1.3.0 :
322; 1.1.2 :
323; 1.1.1 :
324; 1.1.0 : Needs "check-errors" extension.
325; 1.0.0 : Chicken 4 release.
326
327
328== License
329
330Copyright (C) 2009-2018 Kon Lovett.  All rights reserved.
331
332Permission is hereby granted, free of charge, to any person obtaining a
333copy of this software and associated documentation files (the Software),
334to deal in the Software without restriction, including without limitation
335the rights to use, copy, modify, merge, publish, distribute, sublicense,
336and/or sell copies of the Software, and to permit persons to whom the
337Software is furnished to do so, subject to the following conditions:
338
339The above copyright notice and this permission notice shall be included
340in all copies or substantial portions of the Software.
341
342THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
343IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
344FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
345THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
346OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
347ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
348OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.