source: project/wiki/eggref/4/apropos @ 35438

Last change on this file since 35438 was 35438, checked in by Kon Lovett, 17 months ago

rel 2.7.2

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