args-doc
Note: This is taken from the Chicken Wiki, where a more recent version could be available.
Formatting GNU-style help messages
The args-doc facility is dedicated to format usage messages for GNU Coding Standards-compliant command line interfaces.
The facility aims to complement SRFI 37: a program argument processor.
The functions formatting the usage messages accept the list of
sections, specifying the options and the documentation strings.
Each section is a list of the following structure:
(PRIORITY HEADING
DOC-ENTRY-1...)
Here, PRIORITY is a number. The sections in the resulting message
will be ordered so that the non-negative PRIORITY sections will come
first, in the order of increasing PRIORITY, followed by the negative
PRIORITY sections, in the order of increasing PRIORITY as well.
The rationale for this order is to allow for certain options to be
shown at the end of the message. In particular, `--help',
`--usage' and `--version' options should be put in a section with
a `-1' priority.
A formatted HEADING will be prepended to the list of the options in
the resulting message. If no heading is desired, #f may be
specified.
The main part of the message will consist of the documentation for
the options specified by the DOC-ENTRY-1... lists. Each of the
lists may have one of the following forms.
(OPTION DOC-STRING ARG-STRING)
(OPTION DOC-STRING)
Specifies a normal option. OPTION is an SRFI 37 option. DOC-STRING
is a documentation string, and ARG-STRING is a string to be
formatted as its argument. If and only if option accepts no
argument, ARG-STRING may be omitted, as in the second form.
(OPTION #f)
A hidden option. OPTION is an SRFI 37 option. No text will be made
for this option in the resulting message.
Rationale: certain options may be well described by the ARGS-DOC
argument to `args-doc-help' and `args-doc-usage' below. This
entry is to specify such an option, allowing for it still be
returned by `args-doc-options'.
(NAMES DOC-STRING)
A fake option. NAMES is a list of short (character) and long
(string) option names.
(STRING DOC-STRING)
A documentation option. STRING will be shown in the left column of
the message, where the option names are normally placed, and
DOC-STRING will be formatted like a documentation string for an
option. The documentation options will follow the normal options in
the alphabetical order.
Please note that the specification above assumes that an SRFI 37
option could never be a pair or a string. It's not assumed that
SRFI 37 options will be a data type disjoint from any other types.args-doc:duplicate-arguments? args-doc:duplicate-arguments-note? args-doc:header-indent args-doc:doc-option-indent args-doc:short-option-indent args-doc:long-option-indent args-doc:usage-indent args-doc:documentation-indent args-doc:right-margin The parameters affecting the formatting of the help messages. args-doc:program-short-name The parameter holding the program short name, or #f. In a POSIX environment, should be a value of `argv[0]' with the leading directories removed. If `argv[0]' hold the filename of an interpreter, `args-doc:program-short-name' should be set to the filename of the script being interpreted with the leading directories removed. args-doc:program-version The value of this parameter is either a string to be returned by `args-doc:program-version', or a procedure to be called without arguments for such a string. args-doc:program-bug-address The parameter holding the program bug reporting address, or #f. (args-doc-section PRIORITY HEADER DOC-ENTRY-1...) Return a section, an element of a sections list as specified above. (args-doc-options SECTIONS) Given a list of SECTIONS, return the options list suitable to be passed to `args-fold'. (args-doc-help SECTIONS DOC-STRING ARGS-DOC) Return a GNU-style long usage message. (args-doc-usage SECTIONS ARGS-DOC) Return a GNU-style short usage message. (args-doc-version) Return a GNU-style version message. (args-doc-customize STRING) (args-doc-customize STRING OMIT) Set the message formatting parameters as specified by STRING. The format of STRING is the same as for `ARGP_HELP_FMT' environment variable, as specified by the Argp documentation. Optional OMIT list contains the parameters which will not be set. (with-args-doc-customization STRING THUNK) (with-args-doc-customization STRING THUNK OMIT) Extend the local dynamic environment with bindings of the message formatting parameters as specified by STRING. Evaluate the THUNK in the resulting dynamic environment. Optional OMIT list contains the parameters for which no binding will be created.
The code is intended to be portable to ease the integration into a
wide variety of Scheme implementations. The dependencies of the
code are as follows:
* R5RS; `values' and `call-with-values' in particular;
* SRFIs 1, 13, 14 -- list, string and character set libraries; used
widely in the code;
* SRFI 37 -- args-fold, which the present facility aims to
complement;
* SRFI 39 -- parameter objects, used to allow for user
customization;
* SRFI 95 -- sorting, used mainly to sort options alphabetically.Copyright © 2007 Ivan Shmakov <ivan@theory.asu.ru>
Permission to copy this software, to modify it, to redistribute it, to distribute modified versions, and to use it for any purpose is granted, subject to the following restrictions and understandings.
1. Any copy made of this software must include this copyright notice in full.
2. I have made no warranty or representation that the operation of this software will be error-free, and I am under no obligation to provide any services, by way of maintenance, update, or otherwise.
3. In conjunction with products arising from the use of this material, there shall be no use of my name in any advertising, promotional, or sales literature without prior written consent in each case.