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

Last change on this file since 37051 was 37051, checked in by kon, 4 months ago

rel 3.2.3

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