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

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

rel 2.5.1

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