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

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

rel 2.2.5

File size: 9.1 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. Requires
169meta-information beyond that supplied by the transformer procedure.
170
171* The support for macros is ''brittle'' due to subtle details of the core
172macro machinary assumed by this extension. Submit a bug report if it breaks.
173
174* Module qualified symbols are displayed whether the module is "imported" or
175not. So the exported, and imported, symbol {{sym}} of module {{mod}} is
176{{mod#sym}} and not {{sym}} when viewed thru the lens of {{apropos}}.
177
178Proposed solution is a "module" column: "*" for toplevel & "mod" for imported.
179Module column would be optional, & '''not''' default.
180
181
182== Author
183
184[[/users/kon-lovett|Kon Lovett]]
185
186
187== Version history
188
189; 2.2.5 : Re-flow.
190; 2.2.4 : Less C.
191; 2.2.3 : Fix only boolean/char REPL bug, re-flow.
192; 2.2.2 : Fix only number REPL bug, re-flow.
193; 2.2.1 : .
194; 2.2.0 : correct interpretation of unquoted string/symbol as a literal string, fix sorting support for apropos-information-list, add case-insensitive option
195; 2.1.3 : fix for ticket #1211, incorrect load of regex when irregex is actual dependency
196; 2.1.2 : fix for removed core support routine
197; 2.1.1 : Fix for ticket #987
198; 2.1.0 : Added irregex sre & POSIX string patterns.
199; 2.0.0 : Chicken 4.8 only.
200; 1.4.3 : Explicit {{regex}} dependency.
201; 1.4.2 : Using utility libraries, rather than own routines.
202; 1.4.1 : Bugfix for sorting symbols by printname. {{kind:}} is now {{type:}}.
203; 1.4.0 : Macros are back but '''brittle'''
204; 1.3.0 :
205; 1.1.2 :
206; 1.1.1 :
207; 1.1.0 : Needs "check-errors" extension.
208; 1.0.0 : Chicken 4 release.
209
210
211== License
212
213Copyright (C) 2009-2017 Kon Lovett.  All rights reserved.
214
215Permission is hereby granted, free of charge, to any person obtaining a
216copy of this software and associated documentation files (the Software),
217to deal in the Software without restriction, including without limitation
218the rights to use, copy, modify, merge, publish, distribute, sublicense,
219and/or sell copies of the Software, and to permit persons to whom the
220Software is furnished to do so, subject to the following conditions:
221
222The above copyright notice and this permission notice shall be included
223in all copies or substantial portions of the Software.
224
225THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
226IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
227FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
228THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
229OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
230ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
231OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.