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

Last change on this file since 34864 was 34864, checked in by Kon Lovett, 4 years ago

rel 2.5.0

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