chickadee » imperative-command-line-a

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

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 frameworks.

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, you use groups. When the command-line is processed, commands from different command groups are first parsed into separate lists. Then the commands in these lists are called, in the order of their respective command groups in the (groups) parameter. 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 one pre-made command-group, special-options, which defines the commands "help" and "version". These command line options are automatically available in your program, unless you override them (for which see groups below). The output of these commands is configured in part by the parameters help-heading and help-minimum-intercolumn-space.

Each defined command-line option takes a certain number of positional parameters. Your commands are not limited to a single parameter, but variable numbers of parameters are not yet 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

Any program that uses imperative-command-line-a will define at least one command group. Typically, you will use define-command-group to do this.

(define-command-group name command-def ...)syntax
(define-command-group name #:title title command-def ...)syntax
(define-command-group* name command-def ...)syntax
(define-command-group* name #:title title command-def ...)syntax

define-command-group is the typical way to define a command group. It defines the symbol name as a command group constructed according to the rest of the arguments. It adds the new group to (groups).

The starred form, define-command-group*, is the same, except that it does not automatically add the new group to (groups).

When no title is given, make-title is used to generate one automatically based on name. The title is used in the -help display.

Each command-def looks like ((name . args) . body) or ((name . args) #:doc doc . body). The #:doc keyword may be used to store a short docstring for the command, which will be printed in the -help display.

make-command-group title commandsprocedure

You will not normally use this procedure directly. It is part of the expansion of define-command-group and define-command-group*.

make-titleparameter

Value is a procedure that converts a symbol to a string, suitable for use in -help titling. The default upcases the string and replaces hyphen with spacen.

abort-parseprocedure

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.

parse inputprocedure

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.

groupsparameter

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 define-command-group adds to this list. To remove the provided special-options group, call (group '()) to initialize the list before defining any other command groups.

help-headingparameter

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.

help-minimum-intercolumn-spaceparameter

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.

Commands API

You will generally not need to use this part of the API, unless you write introspective commands, like your own -help.

make-command name args doc bodyprocedure
command-name cmdprocedure
command-args cmdprocedure
command-doc cmdprocedure
command-body cmdprocedure
command-name-string cmdprocedure

Examples

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

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

(icla:define-command-group general-options
 ((foo)
  doc: "print foo"
  (print "foo"))
 ((bar baz)
  (print baz)))

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

License

BSD

Version History

Contents »