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

Last change on this file since 36213 was 36213, checked in by kon, 3 months ago

rm dep

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