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

Last change on this file since 34746 was 34746, checked in by Kon Lovett, 2 years ago

rel 2.3.0

File size: 11.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 a list key'ed by {{(MODULE . NAME)}}. The
45associated information is either {{'macro}}, {{'keyword}}, {{'variable}},
46{{'procedure}}, {{'(procedure . <lambda-list-specification>)}} or
47{{'(procedure . <core procedure name>)}}.
48
49{{MODULE}} is the identifier module symbol or {{||}} for the null module.
50
51{{NAME}} is the identifier name symbol or {{||}} for the null module.
52
53=== Interpreter Usage
54
55A {{csi}} toplevel-command is added when the {{apropos}} extension is loaded: {{,a PATTERN ARGUMENT...}}.
56
57{{ARGUMENT}} is interpreted as:
58
59; {{mac[ros]}} : {{#:macros? #t}}
60; {{qual[ified]}} : {{#:qualified? #t}}
61; {{sort [name|type|#f]}} : {{#:sort #:name|#:type|#f}}
62; {{case-insensitve|ci}} : {{#:case-insensitive? #t}}
63; {{search|mode pre[fix]|suff[ix]|#t}} : {{#:search-mode #:prefix|#:suffix|#t}}
64
65The command is interpreted by the {{apropos}} procedure. Unlike {{apropos}}
66sort by type is the default.
67
68Example:
69
70<enscript language=scheme>
71#;1> ,a print qualified macros sort name
72char-set:printing                         variable
73define-record-printer                     macro
74expand-full#pretty-print-expand*          procedure (form33 . tmp3234)
75flonum-print-precision                    procedure tmp12681269
76  ...
77##sys#repl-print-hook                     procedure (x2228 port2229)
78##sys#repl-print-length-limit             variable
79##sys#user-print-hook                     procedure (x3498 readable3499 port3500)
80##sys#with-print-length-limit             procedure (limit3534 thunk3535)
81</enscript>
82
83<enscript language=scheme>
84#;1> ,a '"w.*e" macros
85eval-when                          macro
86when                               macro
87bitwise-and                        procedure xs3569
88bitwise-ior                        procedure xs3575
89bitwise-not                        procedure (x3587)
90bitwise-xor                        procedure xs3581
91  ...
92write-string                       procedure (s297 . more298)
93char-set:lower-case                variable
94char-set:whitespace                variable
95</enscript>
96
97
98== Usage
99
100<enscript language=scheme>
101(require-extension apropos)
102</enscript>
103
104
105== Examples
106
107* YMMV
108
109<enscript language=scheme>
110> (apropos 'print)
111flonum-print-precision                     procedure tmp13141315
112fprintf                                    procedure (port732 fstr733 . args734)
113max-symbol-printname-length  symbol-utils  procedure (syms273)
114pretty-print                               procedure (obj674 . opt675)
115pretty-print-expand*         expand-full   procedure (form32 . tmp3133)
116pretty-print-width                         procedure args2478
117print                                      procedure args3344
118print*                                     procedure args3377
119print-call-chain                           procedure tmp41484149
120print-error-message                        procedure (ex5148 . args5149)
121printf                                     procedure (fstr736 . args737)
122sprintf                                    procedure (fstr739 . args740)
123symbol-printname-details     symbol-utils  procedure (sym205)
124symbol-printname-length      symbol-utils  procedure (sym270)
125symbol-printname<?           symbol-utils  procedure (x241 y242)
126symbol-printname=?           symbol-utils  procedure (x215 y216)
127char-set:printing                          variable
128</enscript>
129
130<enscript language=scheme>
131> ((pp (apropos-list 'print)))
132((expand-full#pretty-print-expand*
133  symbol-utils#max-symbol-printname-length
134  symbol-utils#symbol-printname-length
135  print-error-message
136  print-call-chain
137  sprintf
138  symbol-utils#symbol-printname-details
139  printf
140  print*
141  char-set:printing
142  print
143  fprintf
144  symbol-utils#symbol-printname=?
145  symbol-utils#symbol-printname<?
146  pretty-print
147  flonum-print-precision
148  pretty-print-width))
149</enscript>
150
151<enscript language=scheme>
152> ((pp (apropos-information-list  'print)))
153((((||: . flonum-print-precision) procedure . tmp13141315)
154 ((||: . fprintf) procedure port732 fstr733 . args734)
155 ((symbol-utils . max-symbol-printname-length) procedure syms273)
156 ((||: . pretty-print) procedure obj674 . opt675)
157 ((expand-full . pretty-print-expand*) procedure form32 . tmp3133)
158 ((||: . pretty-print-width) procedure . args2478)
159 ((||: . print) procedure . args3344)
160 ((||: . print*) procedure . args3377)
161 ((||: . print-call-chain) procedure . tmp41484149)
162 ((||: . print-error-message) procedure ex5148 . args5149)
163 ((||: . printf) procedure fstr736 . args737)
164 ((||: . sprintf) procedure fstr739 . args740)
165 ((symbol-utils . symbol-printname-details) procedure sym205)
166 ((symbol-utils . symbol-printname-length) procedure sym270)
167 ((symbol-utils . symbol-printname<?) procedure x241 y242)
168 ((symbol-utils . symbol-printname=?) procedure x215 y216)
169 ((||: . char-set:printing) . variable)))
170</enscript>
171
172<enscript language=scheme>
173> (apropos 'print #:qualified? #t)
174printer:                                     keyword
175flonum-print-precision                       procedure tmp13141315
176fprintf                                      procedure (port732 fstr733 . args734)
177max-symbol-printname-length    symbol-utils  procedure (syms273)
178pretty-print                                 procedure (obj674 . opt675)
179pretty-print-expand*           expand-full   procedure (form32 . tmp3133)
180pretty-print-width                           procedure args2478
181print                                        procedure args3344
182print*                                       procedure args3377
183print-call-chain                             procedure tmp41484149
184print-error-message                          procedure (ex5148 . args5149)
185printf                                       procedure (fstr736 . args737)
186sprintf                                      procedure (fstr739 . args740)
187symbol-printname-details       symbol-utils  procedure (sym205)
188symbol-printname-length        symbol-utils  procedure (sym270)
189symbol-printname<?             symbol-utils  procedure (x241 y242)
190symbol-printname=?             symbol-utils  procedure (x215 y216)
191##sys#print                                  procedure (x3415 readable3416 port3417)
192##sys#print-length-limit                     procedure args2478
193##sys#print-to-string                        procedure (xs3909)
194##sys#really-print-call-chain                procedure (port4111 chain4112 header4113)
195##sys#register-record-printer                procedure (type3661 proc3662)
196##sys#repl-print-hook                        procedure (x2453 port2454)
197##sys#user-print-hook                        procedure (x3666 readable3667 port3668)
198##sys#with-print-length-limit                procedure (limit3703 thunk3704)
199char-set:printing                            variable
200##sys#record-printers                        variable
201##sys#repl-print-length-limit                variable
202</enscript>
203
204
205== Requirements
206
207[[regex]]
208[[check-errors]]
209[[miscmacros]]
210[[symbol-utils]]
211[[string-utils]]
212
213
214== Bugs and Limitations
215
216* Does not support UTF-8!
217
218* Doesn't show something similar to procedure-information for macros. Requires
219meta-information beyond that supplied by the transformer procedure.
220
221* The support for macros is ''brittle'' due to subtle details of the core
222macro machinary assumed by this extension. Submit a bug report if it breaks.
223
224
225
226== Author
227
228[[/users/kon-lovett|Kon Lovett]]
229
230
231== Version history
232
233; 2.3.0 : Identifiers are now {{(<module> . <name>)}} for the {{information-list}}.
234; 2.2.5 : Re-flow.
235; 2.2.4 : Less C.
236; 2.2.3 : Fix only boolean/char REPL bug, re-flow.
237; 2.2.2 : Fix only number REPL bug, re-flow.
238; 2.2.1 : .
239; 2.2.0 : correct interpretation of unquoted string/symbol as a literal string, fix sorting support for apropos-information-list, add case-insensitive option
240; 2.1.3 : fix for ticket #1211, incorrect load of regex when irregex is actual dependency
241; 2.1.2 : fix for removed core support routine
242; 2.1.1 : Fix for ticket #987
243; 2.1.0 : Added irregex sre & POSIX string patterns.
244; 2.0.0 : Chicken 4.8 only.
245; 1.4.3 : Explicit {{regex}} dependency.
246; 1.4.2 : Using utility libraries, rather than own routines.
247; 1.4.1 : Bugfix for sorting symbols by printname. {{kind:}} is now {{type:}}.
248; 1.4.0 : Macros are back but '''brittle'''
249; 1.3.0 :
250; 1.1.2 :
251; 1.1.1 :
252; 1.1.0 : Needs "check-errors" extension.
253; 1.0.0 : Chicken 4 release.
254
255
256== License
257
258Copyright (C) 2009-2017 Kon Lovett.  All rights reserved.
259
260Permission is hereby granted, free of charge, to any person obtaining a
261copy of this software and associated documentation files (the Software),
262to deal in the Software without restriction, including without limitation
263the rights to use, copy, modify, merge, publish, distribute, sublicense,
264and/or sell copies of the Software, and to permit persons to whom the
265Software is furnished to do so, subject to the following conditions:
266
267The above copyright notice and this permission notice shall be included
268in all copies or substantial portions of the Software.
269
270THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
271IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
272FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
273THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
274OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
275ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
276OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.