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

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

rel 3.1.1

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