apropos

Description

An apropos facility for CHICKEN Scheme.

Apropos API

Usage

(import apropos-api)

apropos

[procedure] (apropos PATTERN #!key macros? sort case-insensitive? raw? base find internal? imported?)

Displays information about symbols matching PATTERN in the toplevel environment.

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.
MACROS?: Either #t to include macros, or #f to skip them. Default is #f.
CASE-INSENSITIVE?: Either #t to use match case-insensitivity for the PATTERN or #f to be case-sensitive. Default is #f.
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.
FIND: Either #:name for an symbol match, #:module for an module match, or #f for any. Default is #f.
RAW?: Do not strip identifier symbols. The default is #f. Use #:raw? #t when apropos is suspected of hiding information.
BASE: fixnum in 2..16. The default is 10. BASE is used to convert a number to a string PATTERN. Of dubious utility. But can fix the situation of entering a hex number, say #x1c, for the pattern using the REPL and matching against 28!
INTERNAL?: Either #t to include internal "modules", or #f to ignore. The default is #f.
IMPORTED?: Either #t for only imported identifiers, or #f for global symbols. The default is #f.

apropos-list

[procedure] (apropos-list PATTERN #!key macros? case-insensitive? raw? base find internal? imported?) => list

Like apropos but returns an, unsorted, list of matching symbols.

apropos-information-list

[procedure] (apropos-information-list PATTERN #!key macros? sort case-insensitive? raw? find base internal? imported?) => list

Like apropos but returns a list key'ed by (MODULE . NAME).

MODULE is the module symbol or || for the null module.

NAME is the base symbol.

The associated information is either:

'macro
'keyword
'variable
'procedure
'(procedure . <lambda-list-specification>)
'(procedure . <core procedure name>)

apropos-excluded-modules

[parameter] (apropos-excluded-modules [MODS]) -> (list-of string)

Exclude identifiers from modules with a matching prefix. Accepts a symbolic input form but returns the prefix matching canonical form.

MODS: (list-of module-name) ; default ().
module-name: (or string symbol (list-of symbol) (list symbol integer))

apropos-default-base

[parameter] (apropos-default-base [BASE]) -> fixnum

BASE: fixnum ; [2 16], default 10.

apropos-default-options

[parameter] (apropos-default-options [OPTIONS]) -> list

OPTIONS: (list-of keyword * ...) ; key'ed option list.
OPTIONS: false ; '().
OPTIONS: true ; '(#:sort #:module #:find #:name #:macros? #t).

Intially '().

apropos-interning

[parameter] (apropos-interning [FLAG]) -> boolean

Use string->symbol - #t - or string->uninterned-symbol - #f, default #t.

API Examples

YMMV

> (apropos 'print)
flonum-print-precision                     procedure tmp
fprintf                                    procedure (port fstr . args)
max-symbol-printname-length  symbol-utils  procedure (syms)
pretty-print                               procedure (obj . opt)
pretty-print-expand*         expand-full   procedure (form . tmp)
pretty-print-width                         procedure args
print                                      procedure args
print*                                     procedure args
print-call-chain                           procedure tmp
print-error-message                        procedure (ex . args)
printf                                     procedure (fstr . args)
sprintf                                    procedure (fstr . args)
symbol-printname-details     symbol-utils  procedure (sym)
symbol-printname-length      symbol-utils  procedure (sym)
symbol-printname<?           symbol-utils  procedure (x y)
symbol-printname=?           symbol-utils  procedure (x y)
char-set:printing                          variable

> (pp (apropos-list 'print))
((expand-full#pretty-print-expand*
  symbol-utils#max-symbol-printname-length
  symbol-utils#symbol-printname-length
  print-error-message
  print-call-chain
  sprintf
  symbol-utils#symbol-printname-details
  printf
  print*
  char-set:printing
  print
  fprintf
  symbol-utils#symbol-printname=?
  symbol-utils#symbol-printname<?
  pretty-print
  flonum-print-precision
  pretty-print-width))

> (pp (apropos-information-list 'print))
((((||: . flonum-print-precision) procedure . tmp)
 ((||: . fprintf) procedure port fstr . args)
 ((symbol-utils . max-symbol-printname-length) procedure syms)
 ((||: . pretty-print) procedure obj . opt)
 ((expand-full . pretty-print-expand*) procedure form . tmp)
 ((||: . pretty-print-width) procedure . args)
 ((||: . print) procedure . args)
 ((||: . print*) procedure . args)
 ((||: . print-call-chain) procedure . tmp)
 ((||: . print-error-message) procedure ex . args)
 ((||: . printf) procedure fstr . args)
 ((||: . sprintf) procedure fstr . args)
 ((symbol-utils . symbol-printname-details) procedure sym)
 ((symbol-utils . symbol-printname-length) procedure sym)
 ((symbol-utils . symbol-printname<?) procedure x y)
 ((symbol-utils . symbol-printname=?) procedure x y)
 ((||: . char-set:printing) . variable)))

> (apropos 'print)
printer:                                     keyword
flonum-print-precision                       procedure tmp
fprintf                                      procedure (port fstr . args)
max-symbol-printname-length    symbol-utils  procedure (syms)
pretty-print                                 procedure (obj . opt)
pretty-print-expand*           expand-full   procedure (form . tmp)
pretty-print-width                           procedure args
print                                        procedure args
print*                                       procedure args
print-call-chain                             procedure tmp
print-error-message                          procedure (ex . args)
printf                                       procedure (fstr . args)
sprintf                                      procedure (fstr . args)
symbol-printname-details       symbol-utils  procedure (sym)
symbol-printname-length        symbol-utils  procedure (sym)
symbol-printname<?             symbol-utils  procedure (x y)
symbol-printname=?             symbol-utils  procedure (x y)
##sys#print                                  procedure (x readable port)
##sys#print-length-limit                     procedure args
##sys#print-to-string                        procedure (xs)
##sys#really-print-call-chain                procedure (port chain header)
##sys#register-record-printer                procedure (type proc)
##sys#repl-print-hook                        procedure (x port)
##sys#user-print-hook                        procedure (x readable port)
##sys#with-print-length-limit                procedure (limit thunk)
char-set:printing                            variable
##sys#record-printers                        variable
##sys#repl-print-length-limit                variable

Apropos CSI

Usage

(import apropos-csi)

A csi toplevel-command is added when the apropos-csi extension is loaded by the interpreter, a.

,a PATTERN OPTION ...

OPTION is interpreted as:

help: short-circuit long-form help
mac[ros]: #:macros? #t
sort [name|module|type|#f]: #:sort #:name|#:module|#:type|#f ; default is #:type
find [name|module|#f]: #:find #:name|#:module|#f
case-insensitve|ci: #:case-insensitive? #t
base 2..16: #:base 2..16
internal: #:internal #t

CSI Examples

#;1> ,a print macros sort name
char-set:printing                            variable
define-record-printer                        macro
flonum-print-precision                       procedure tmp
fprintf                                      procedure (port fstr . args)
max-symbol-printname-length    symbol-utils  procedure (syms)
pretty-print                                 procedure (obj . opt)
  ...
##sys#register-record-printer                procedure (type proc)
##sys#repl-print-hook                        procedure (x port)
##sys#repl-print-length-limit                variable
##sys#user-print-hook                        procedure (x readable port)
##sys#with-print-length-limit                procedure (limit thunk)

#;1> ,a '"w.*e" macros
when                                         macro
bitwise-and                                  procedure xs
bitwise-ior                                  procedure xs
bitwise-not                                  procedure (x)
bitwise-xor                                  procedure xs
call-with-current-continuation               procedure (proc)
  ...
write-string                                 procedure (s . more)
char-set:lower-case                          variable
char-set:whitespace                          variable

#;1> ,a (: (* any)) macros sort name
*                                                           procedure C_times
  ... 1600 lines + ...
##sys#write-char/port                                       procedure (c port)

Usage

(import apropos)

Exports apropos-api & apropos-csi.

Requirements

srfi-1 srfi-13 check-errors symbol-utils

test test-utils

Bugs and Limitations

Modules imported using rename or prefix will not be matched using the imported name. Apropos does not currently know about renaming imports.
Doesn't show something similar to module or procedure-information for macros. Requires meta-information beyond that supplied by the transformer procedure.
The support for macros is brittle due to subtle details of the core macro machinary assumed by this extension. Submit a bug report if it breaks.

Author

Kon Lovett

Repository

This egg is hosted on the CHICKEN Subversion repository:

https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/apropos

If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.

Version history

4.0.2: Fix R7RS import.
4.0.1: Update csi help, apropos-default-options.
4.0.0: CHICKEN 6 release.

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the Software), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.