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

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

rel 2.2.0

File size: 8.5 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?])</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, or {{#:type}} for a type+indentifier sort, or {{#f}} for unsorted. The default is {{#:type}}.
29
30Should {{PATTERN}} be a namespace qualified symbol the namespace will be
31dropped before conversion to a regular-expression.
32
33==== apropos-list
34
35<procedure>(apropos-list PATTERN [#:macros? MACROS?] [#:qualified? QUALIFIED?] [#:case-insensitive? CASE-INSENSITIVE?]) => {{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 [#:macros? MACROS?] [#:qualified? QUALIFIED?] [#:sort SORT] [#:case-insensitive? CASE-INSENSITIVE?]) => {{list}}</procedure>
42
43Like {{apropos}} but returns an association list keyed by symbol. The
44associated information is either {{'macro}}, {{'keyword}}, {{'variable}},
45{{'procedure}}, {{'(procedure . <lambda-list-specification>)}} or {{'(procedure
46. <core procedure name>)}}.
47
48=== Interpreter Usage
49
50A {{csi}} toplevel-command is added when the {{apropos}} extension is loaded: {{,a PATTERN ARGUMENT...}}.
51
52{{ARGUMENT}} is interpreted as:
53
54; {{macros|mac}} : {{#:macros? #t}}
55; {{qualified|qual}} : {{#:qualified? #t}}
56; {{sort [name|type|#f]}} : {{#:sort #:name|#:type|#f}}
57; {{case-insensitve|ci}} : {{#:case-insensitive? #t}}
58
59The command is interpreted by the {{apropos}} procedure. Unlike {{apropos}}
60sort by type is the default.
61
62Example:
63
64<enscript language=scheme>
65#;1> ,a print qualified macros sort name
66char-set:printing                         variable
67define-record-printer                     macro
68expand-full#pretty-print-expand*          procedure (form33 . tmp3234)
69flonum-print-precision                    procedure tmp12681269
70  ...
71##sys#repl-print-hook                     procedure (x2228 port2229)
72##sys#repl-print-length-limit             variable
73##sys#user-print-hook                     procedure (x3498 readable3499 port3500)
74##sys#with-print-length-limit             procedure (limit3534 thunk3535)
75</enscript>
76
77<enscript language=scheme>
78#;1> ,a '"w.*e" macros
79eval-when                          macro
80when                               macro
81bitwise-and                        procedure xs3569
82bitwise-ior                        procedure xs3575
83bitwise-not                        procedure (x3587)
84bitwise-xor                        procedure xs3581
85  ...
86write-string                       procedure (s297 . more298)
87char-set:lower-case                variable
88char-set:whitespace                variable
89</enscript>
90
91
92== Usage
93
94<enscript language=scheme>
95(require-extension apropos)
96</enscript>
97
98
99== Examples
100
101* YMMV
102
103<enscript language=scheme>
104> (apropos 'print)
105expand-full#pretty-print-expand*  procedure (form32 . tmp3133)
106flonum-print-precision            procedure tmp11801181
107fprintf                           procedure (port742 fstr743 . args744)
108pretty-print                      procedure (obj681 . opt682)
109pretty-print-width                procedure arg2051
110print                             procedure args2753
111print*                            procedure args2782
112print-call-chain                  procedure tmp34643465
113print-error-message               procedure (ex4314 . args4315)
114printf                            procedure (fstr746 . args747)
115sprintf                           procedure (fstr749 . args750)
116char-set:printing                 variable
117</enscript>
118
119<enscript language=scheme>
120(apropos-list 'print)
121(char-set:printing print flonum-print-precision pretty-print pretty-print-width sprintf printf print* print-error-message expand-full#pretty-print-expand* print-call-chain fprintf)
122</enscript>
123
124<enscript language=scheme>
125> (apropos 'print #:qualified? #t)
126printer:                          keyword
127expand-full#pretty-print-expand*  procedure (form32 . tmp3133)
128flonum-print-precision            procedure tmp11801181
129fprintf                           procedure (port742 fstr743 . args744)
130pretty-print                      procedure (obj681 . opt682)
131pretty-print-width                procedure arg2051
132print                             procedure args2753
133print*                            procedure args2782
134print-call-chain                  procedure tmp34643465
135print-error-message               procedure (ex4314 . args4315)
136printf                            procedure (fstr746 . args747)
137sprintf                           procedure (fstr749 . args750)
138##csi#print-banner                procedure
139##csi#print-usage                 procedure
140##sys#print                       procedure (x2819 readable2820 port2821)
141##sys#print-to-string             procedure (xs3218)
142##sys#really-print-call-chain     procedure (port3428 chain3429 header3430)
143##sys#register-record-printer     procedure (type3024 proc3025)
144##sys#repl-print-hook             procedure (x2218 port2219)
145##sys#user-print-hook             procedure (x3029 readable3030 port3031)
146##sys#with-print-length-limit     procedure (limit3063 thunk3064)
147char-set:printing                 variable
148##sys#record-printers             variable
149##sys#repl-print-length-limit     variable
150</enscript>
151
152
153== Requirements
154
155[[regex]]
156[[check-errors]]
157[[miscmacros]]
158[[symbol-utils]]
159[[string-utils]]
160
161
162== Bugs and Limitations
163
164* Does not support UTF-8!
165
166* Doesn't show something similar to procedure-information for macros.
167
168Requires meta-information beyond that supplied by the transformer procedure.
169
170* The support for macros is '''brittle''' due to subtle details of the core
171macro machinary assumed by this extension. Submit a bug report if it breaks.
172
173* Module qualified symbols are displayed whether the module is "imported" or
174not. So the exported, and imported, symbol {{sym}} of module {{mod}} is
175{{mod#sym}} and not {{sym}} when viewed thru the lens of {{apropos}}.
176
177
178== Author
179
180[[/users/kon-lovett|Kon Lovett]]
181
182
183== Version history
184
185; 2.2.0 : correct interpretation of unquoted string/symbol as a literal string, fix sorting support for apropos-information-list, add case-insensitive option
186; 2.1.3 : fix for ticket #1211, incorrect load of regex when irregex is actual dependency
187; 2.1.2 : fix for removed core support routine
188; 2.1.1 : Fix for ticket #987
189; 2.1.0 : Added irregex sre & POSIX string patterns.
190; 2.0.0 : Chicken 4.8 only.
191; 1.4.3 : Explicit {{regex}} dependency.
192; 1.4.2 : Using utility libraries, rather than own routines.
193; 1.4.1 : Bugfix for sorting symbols by printname. {{kind:}} is now {{type:}}.
194; 1.4.0 : Macros are back but '''brittle'''
195; 1.3.0 :
196; 1.1.2 :
197; 1.1.1 :
198; 1.1.0 : Needs "check-errors" extension.
199; 1.0.0 : Chicken 4 release.
200
201
202== License
203
204Copyright (C) 2009-2015 Kon Lovett.  All rights reserved.
205
206Permission is hereby granted, free of charge, to any person obtaining a
207copy of this software and associated documentation files (the Software),
208to deal in the Software without restriction, including without limitation
209the rights to use, copy, modify, merge, publish, distribute, sublicense,
210and/or sell copies of the Software, and to permit persons to whom the
211Software is furnished to do so, subject to the following conditions:
212
213The above copyright notice and this permission notice shall be included
214in all copies or substantial portions of the Software.
215
216THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
217IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
218FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
219THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
220OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
221ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
222OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.