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

Last change on this file since 35055 was 35055, checked in by Kon Lovett, 3 years ago

rel 2.6.4

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