You are looking at historical revision 19978 of this page. It may differ significantly from its current revision.

chicken-doc

chicken-doc is a tool for exploring Chicken documentation.

Overview

chicken-doc provides facilities to explore Chicken documentation from the command-line and from the REPL. It also provides an API to access this documentation from your own programs.

You need to obtain Chicken documentation separately. To generate a documentation database from a copy of the wiki, see the chicken-doc-admin egg. You can also use a pre-built documentation package, described below.

Documentation repository

The documentation database is located, by default, under (chicken-home) in the chicken-doc/ directory. If you have installed it in a different location, set the CHICKEN_DOC_REPOSITORY enviroment variable:

export CHICKEN_DOC_REPOSITORY=/path/to/repository

Pre-built packages

Documentation tarballs are provided in gzip, bzip2 and zip format at http://3e8.org/pub/chicken-doc/. They are updated daily from the latest wiki documentation.

Download your preferred format and extract it into the default location (chicken-home) or into some other writable directory of your choice. For example, on UNIX:

$ cd `csi -p '(chicken-home)'`
$ curl http://3e8.org/pub/chicken-doc/chicken-doc-repo.tgz | sudo tar zx

The tarball will be extracted into the directory chicken-doc/. If you installed into a non-default location, CHICKEN_DOC_REPOSITORY must include this entire path.

Cleaning up old repository crust

Occasionally, or when the repository format changes significantly, you should wipe out your repository before extracting a new one, to get rid of dead wood. Simply delete the directory shown by the following command:

$ csi -R chicken-doc -p "(locate-repository)"
/usr/local/share/chicken/chicken-doc

If you have chicken-doc-admin installed, just do instead:

$ chicken-doc-admin -D

Structure

The documentation is arranged in a tree structure, where each node may contain descriptive text, a signature, and other nodes. Nodes may be searched for by name or specified by an absolute path through the tree, and you may request the text, signature or table of contents (children) for any node.

With the standard documentation install, each unit (posix, lolevel) and egg (9p, base64) is assigned a toplevel node whose text contains that unit or egg's full documentation. The identifiers in each become these nodes' children, and contain the signature and descriptive text just for that identifier. Core bindings in the chicken module are similar, but because they are divided into several manual pages, each page is placed in a separate node under the toplevel node chicken.

So in general, if you know the full path of an identifier, you can pull it into your program with (use NODE) or (import NODE) where NODE is the name of the toplevel node. For example,

 and-let* -> (chicken macros and-let*) -> (import chicken)
 find-files -> (posix find-files) -> (use posix)

Here's an abbreviated example of the tree structure:

|- 9p +- alloc-handle
|     |- call-with-input-file
|     |- call-with-output-file
|
|- base64 +- base64-decode
|         |- base64-encode
|
|- chicken +- macros +- and-let*
|          |         |- assert
|          |
|          |- parameters -- make-parameter
|
|- posix +- find-files
|        |- glob
|        |- open/rdonly
|

From the command-line

 
chicken-doc -s|-c|-i path
chicken-doc -f node
chicken-doc node | path

-s path        Show signature
-c path        Show table of contents (children)
-i path        Show documentation
-f node        Show all matching paths for node

where NODE is a single identifier and PATH is one or more node names comprising a path from the documentation root, separated by spaces.

-m re          Show all matching paths for RE

where RE is a POSIX regular expression. Similar to -f.

When no option is given, guess the user's intent. With a single node name, find the node (as with -f) and show its documentation (as with -i) or show all matching paths if multiple matches exist. If more than one node is provided, show documentation on the path (as if called with -i).

Pager

When output is sent to a terminal, chicken-doc pipes its output to the pager of your choice. It looks for a pager in the following places:

If an environment variable is set but empty, for example:

export CHICKEN_DOC_PAGER=

then the output is not paginated. Windows does not distinguish between an empty and unset variable, so you can use the special value cat instead:

set CHICKEN_DOC_PAGER=cat

Text wrapping

chicken-doc will wrap its output text nicely if it can determine how wide your terminal is. If it can't (e.g. on Windows) it will wrap at 76 columns. If you wish to fix the wrap column to, say, 120:

export CHICKEN_DOC_WRAP=120

or to disable wrapping, which won't look very good:

export CHICKEN_DOC_WRAP=0

Examples

Show matches for identifier file-open, which occurs in Unit posix and in the 9p egg:

$ chicken-doc -f file-open
(9p file-open)        (file-open connection path mode)
(posix file-open)     (file-open FILENAME FLAGS [MODE])

Show signature of open/rdonly in Unit posix:

$ chicken-doc -s posix open/rdonly
(posix open/rdonly)     open/rdonly

Show documentation for file-open in the 9p egg:

$ chicken-doc -i 9p open/rdonly
procedure: (file-open connection path mode)

Opens the file indicated by `path` on the `connection` with the given
`mode` and returns an opaque handle object which you can use for the [...]

Show table of contents (identifiers) in Unit posix:

$ chicken-doc -c posix
 [...]
get-host-name        (get-host-name)
glob                 (glob PATTERN1 ...)
group-information    (group-information GROUP)
 [...]

Show identifiers containing call-:

$ chicken-doc -m call-
(scheme call-with-values)      (call-with-values producer consumer)
(xml-rpc call-xml-rpc-proc)    (call-xml-rpc-proc call-sxml procedures)
(library get-call-chain)       (get-call-chain [START [THREAD]])
[...]

Show identifiers ending in -file:

$ chicken-doc -m -file$
(spiffy access-file)           (access-file [string])
(scheme call-with-input-file)  (call-with-input-file string proc)
(scheme call-with-output-file) (call-with-output-file string proc)
[...]

Show `with-...-port` identifiers:

$ chicken-doc -m with-.+-port
(ports with-error-output-to-port)  (with-error-output-to-port PORT THUNK)
(ports with-input-from-port)       (with-input-from-port PORT THUNK)
(ports with-output-to-port)        (with-output-to-port PORT THUNK)

Show documentation for use in chicken core:

$ chicken-doc use
path: (chicken macros use)
macro: (use ID ...)

`use` is just a shorter alias for `require-extension`.

Show full documentation for Unit posix:

$ chicken-doc posix

Show matches for open/rdonly, as with -f:

$ chicken-doc open/rdonly

Show documentation for open/rdonly in Unit posix:

$ chicken-doc posix open/rdonly

From the REPL

To load chicken-doc for REPL use:

(require-library chicken-doc)

The following csi commands then become available:

,doc node
,doc (node ...)

Show documentation for the identifier node or the absolute path (node ...). If a single node is given, a search is performed across all identifiers, and documentation will be shown if the node is unique --- otherwise, the matches are listed.

,toc node
,toc (node ...)

Show a table of contents for the identifier node or the path (node ...). As with ,doc, a search will be performed if a single node is given.

,wtf regex

The "where to find" command. Search identifiers using POSIX regular expression regex (like the -m command-line option) and display the matches.

Examples

Search for identifier define-foreign-type and display its documentation.

#;> ,doc define-foreign-type
path: (foreign access define-foreign-type)
macro: (define-foreign-type NAME TYPE [ARGCONVERT [RETCONVERT]])

Defines an alias for `TYPE` with the name `NAME` (a symbol).
`TYPE` may be a type-specifier or a string naming a C type. The
[...]

Search for identifier file-open and (as multiple matches occur) display the matches:

#;> ,doc file-open
Found 2 matches:
(9p file-open)        (file-open connection path mode)
(posix file-open)     (file-open FILENAME FLAGS [MODE])

Display TOC for absolute path (chicken macros). This should list all the core chicken macros from Non-standard macros and special forms.

#;> ,toc (chicken macros)
and-let*              (and-let* (BINDING ...) EXP1 EXP2 ...)
assert                (assert EXP [STRING ARG ...])
begin-for-syntax      (begin-for-syntax EXP ...)
[...]

Emacs

This elisp snippet will look up the word at point and display its documentation (or matches) in your *scheme* window.

(defun chicken-doc ()
  (interactive)
  (let ((func (current-word)))
    (if func
        (process-send-string "*scheme*"
         (concat "(require-library chicken-doc) ,doc " func "\n")))))

(eval-after-load 'scheme
 '(define-key scheme-mode-map "\C-cd" 'chicken-doc))

Additionally, because multiple matches may be listed, this snippet will allow you to place your cursor at the beginning of the match s-expression and get the actual documentation:

(defun chicken-doc-sexp ()
  (interactive)
  (let ((func (sexp-at-point)))
    (if func
        (process-send-string "*scheme*"
         (format "(require-library chicken-doc) ,doc %S\n" func)))))

(eval-after-load 'cmuscheme
 '(define-key inferior-scheme-mode-map "\C-cd" 'chicken-doc-sexp))

API

To be documented.

[parameter] wrap-column [default: 76]

Wrap column for text output. 0 or #f for no wrapping.

Author

Jim Ursetto

Version history
0.4.0
Repository version 3
0.3.2
POSIX regular expression search
0.3.0
SXML database, formatting improvements
0.2.0
Pagination
0.1.1
Initial release

License

BSD