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

Description

This is the command-line parser from Mowedline, now an independent project. It is a simple imperative-style command-line parser, and the "-a" suffix on its name is there to suggest that this module represents only one of many possible imperative-style command-line syntaxes.

An "imperative" command-line style is one in which the command-line arguments represent procedures and parameters, to be called in left-to-right order, a kind of DSL, or mini-language. Contrast this style with other command-line styles where the options represent simple flags, and order is not significant. In an imperative-style command-line, the options represent actions to take in the order given.

There are times though, when strict left-to-right order is not desired, and to support these situations, imperative-command-line-a supports command groups. If you want to take certain options out of the overall ordering, use groups. When the command-line is parsed, commands from different command groups will be parsed into separate lists. Order within groups is preserved. Command groups are notably used to support "-help" and "-version" options which may appear anywhere in the command-line (barring positional errors). A command group could also be used to support order-independent flag options that need to run before the imperative "actions".

Imperative-command-line-a provides a pre-made command-group, "SPECIAL OPTIONS" which defines "help" and "version" commands, which your program gets automatically. The output of these commands is configured in part by the parameters help-heading and help-minimum-intercolumn-space. If you don't want these predefined options, they can be overridden.

Each defined command-line option takes a certain number of positional parameters. Variable numbers of parameters are not currently supported. Since the distinction between command and parameter is purely positional, the conventional leading hyphens on option names are purely stylistic and may be omitted.

This module has room to grow. The initial set of features are those that meet the requirements of Mowedline, but now that this is a separate project, new uses and needs will undoubtedly arise, and future versions of this egg will be more powerful, flexible, and easier to use.

Authors

Requirements

API

[procedure] (make-command name args doc body)
[procedure] (command-name cmd)
[procedure] (command-args cmd)
[procedure] (command-doc cmd)
[procedure] (command-body cmd)
[procedure] (command-name-string cmd)
[syntax] (make-command-group title . command-defs)
[syntax] (add-command-group title . command-defs)
[procedure] (parse-abort)

Helper procedure for use in command bodies to stop calling of commands, and inform the calling program that it should exit. This is used by the built-in special commands -help and -version to ensure that only one command is called.

[procedure] (parse input)

Parse the list of command-line arguments, input into commands and call them. Returns #t on successful completion of calling commands, #f if parsing was aborted.

[parameter] groups

The groups parameter holds the list of command-groups that parse draws from. By default, it starts with a single group, Special Options, which contains the commands -help and -version. The syntax form add-command-group adds to this list. To remove the provided special-options group, call (group '()) to initialize the list before adding any other command groups.

[parameter] help-heading

The string value of help-heading is printed out by the provided -version command, and as the first line of the provided -help command. Be sure to set this.

[parameter] help-minimum-intercolumn-space

The provided -help command prints command call forms and docstrings in two columns. The help-minimum-intercolumn-space parameter gives the minimum number of spaces by which to separate the two columns, defaulting to 3.

Examples

 
(use srfi-1
     (prefix imperative-command-line-a icla:))

(icla:help-heading
 "icla-example version 1.0, by Harry S Beethoven")

(icla:add-command-group
 "GENERAL OPTIONS"
 ((foo)
  doc: "print foo"
  (print "foo"))
 ((bar)
  (print "bar")))

(icla:parse (command-line-arguments))

License

BSD

Version History