A library for setting up a commandline parser and help generator for an
application. It aims for conciseness, flexibility and composability. It
supports both non-modal and modal (with subcommands -- like darcs, cabal and
the like) applications.

The library supports two main styles of representing flags and
commands. These are called Record and ADT, respectively, by the
library. The Record representation is more straightforward and easier to use
in most instances. The ADT interface is suitable for applications that
require exact correspondence between the commandline and its runtime
representation, or when an existing application is being ported to cmdlib
that is using this style to represent flags.

Using the Record-based interface, a simple Hello World application could
look like this:

News

| Since version 0.3: dispatchR no longer takes a cmd argument, as it was
never used for anything and was simply confusing. A new function,
dispatchOr has been added to allow the program to continue despite
otherwise fatal errors (unknown command, unknown flags). New function,
commandNames, has been added, to go from [CommandWrap] to [String]. The
CommandWrap type is now exported (opaque). The RecordCommand class
now has a mode_help method. RecordMode is no longer exported.

| Since version 0.2: The Positional arguments are no longer required to be
strings. A default (fallback) command may be provided to
dispatch/dispatchR (this has also incompatibly changed their
signature, sorry about that! I have tried to make this extensible
though...). The help command can now be disabled (dispatch [noHelp]
...). Commands can now specify how to process options: permuted,
non-permuted or no options at all. See optionStyle.

Attributes

To each flag, a number of attributes can be attached. Many reasonable
defaults are provided by the library. The attributes are described by the
Attribute type and are attached to flags using %> and the related
operators (all described in this section).

Whether this option is invertible. Only applies to boolean options and
defaults to True. (Invertible means that for --foo, there are --no-foo and
--foo=no alternatives. A non-invertible option will only create --foo.)

When True, this option will contain the list of non-option arguments
passed to the command. Only applicable to [String]-typed options. Options
marked extra will not show up in help and neither will they be recognized
by their name on commandline.

When set, this option will not show up on help and won't create a flag
(similar to Extra), but instead it will contain the n-th non-option
argument. The argument used up by such a positional option will not show
up in the list of non-option arguments.

When this attribute is given, the flag's value will be passed to the
provided IO action (which would presumably record the flag's value in a
global IORef for later use). Like with Default, the attribute is only
effective if the parameter type of the provided function matches the
parameter type of the option to which the attribute is applied.

Whether the option is enabled. Disabled options are not recognized and
are not shown in help (effectively, they do not exist). Used to enable a
subset of all available options for a given command. For Record-based
commands (see RecordCommand), this is handled automatically based on
fields available in the command's constructor. Otherwise, constructs like

Set the group name for this option. The groups are used to section the
help output (the options of a given group are shown together, under the
heading of the group). The ordering of the groups is given by the first
flag of each group. Flags themselves are in the order in which they are
given in the ADT or Record in question.

Attach an attribute to multiple keys: written from right to left,
i.e. Attribute <% Key1 +% Key2. Useful for setting up option groups
(although using group may be more convenient in this case) and option
enablement.

Flags

Flags (commandline options) can be represented in two basic styles,
either as a plain ADT (algebraic data type) or as a record type. These two
styles are implemented using the ADT wrapper for the former and and a
Record wrapper for the latter. You need to make your type an instance of
the Attributes class, which can be used to attach attributes to the
flags.

The ADT wrapper type allows use of classic ADTs (algebraic data types) for
flag representation. The flags are then passed to the command as a list of
values of this type. However, you need to make the type an instance of the
Attributes first (if you do not wish to attach any attributes, you may keep
the instance body empty). E.g.:

This wrapper type allows use of record types (single or multi-constructor)
for handling flags. Each field of the record is made into a single flag of
the corresponding type. The record needs to be made an instance of the
Attributes class. That way, attributes can be attached to the field
selectors, although when used with RecordCommand, its rec_options method
can be used as well and the Attributes instance left empty.

A single value of the Flags type will then be passed to the Command
instances (those that use Record Flags as their second type parameter),
containing the value of the rightmost occurence for each of the flags.

TODO: List-based option types should be accumulated instead of overriden.

A class that describes a single (sub)command. The cmd type parameter is
just for dispatch (and the default command name is derived from this type's
name, but this can be overriden). It could be an empty data decl as far as
this library is concerned, although you may choose to store information in
it.

To parse the commandline for a given command, see execute. The basic usage
can look something like this:

Set this to True if the command is a supercommand (i.e. expects another
subcommand). Defaults to False. Supercommands can come with their own
options, which need to appear between the supercommand and its
subcommand. Any later options go to the subcommand. The run (and
description) method of a supercommand should use dispatch and
helpCommands respectively (on its list of subcommands) itself.

How to process options for this command. NoOptions disables option
processing completely and all arguments are passed in the [String]
parameter to run. Permuted collects everything that looks like an
option (starts with a dash) and processes it. The non-option arguments are
filtered and passed to run like above. Finally, NonPermuted only
processes options until a first non-option argument is encountered. The
remaining arguments are passed unchanged to run.

Given a list of commands (see %:) and a list of commandline arguments,
dispatch on the command name, parse the commandline options (see execute)
and transfer control to the command. This function also implements the
help pseudocommand.

Parse options for and execute a single command (see Command). May be
useful for programs that do not need command-based dispatch, but still
make use of the Command class to describe themselves. Handles --help
internally. You can use this as the entrypoint if your application is
non-modal (i.e. it has no subcommands).

Record-based commands

A bridge that allows multi-constructor record types to be used as a
description of a command set. In such a type, each constructor corresponds
to a single command and its fields to its options. To describe a program
with two commands, foo and bar, each taking a --wibble boolean option
and bar also taking a --text=string option, you can write:

Convenience re-exports

The Data class comprehends a fundamental primitive gfoldl for
folding over constructor applications, say terms. This primitive can
be instantiated in several ways to map over the immediate subterms
of a term; see the gmap combinators later in this class. Indeed, a
generic programmer does not necessarily need to use the ingenious gfoldl
primitive but rather the intuitive gmap combinators. The gfoldl
primitive is completed by means to query top-level constructors, to
turn constructor representations into proper terms, and to list all
possible datatype constructors. This completion allows us to serve
generic programming scenarios like read, show, equality, term generation.

The combinators gmapT, gmapQ, gmapM, etc are all provided with
default definitions in terms of gfoldl, leaving open the opportunity
to provide datatype-specific definitions.
(The inclusion of the gmap combinators as members of class Data
allows the programmer or the compiler to derive specialised, and maybe
more efficient code per datatype. Note: gfoldl is more higher-order
than the gmap combinators. This is subject to ongoing benchmarking
experiments. It might turn out that the gmap combinators will be
moved out of the class Data.)

Conceptually, the definition of the gmap combinators in terms of the
primitive gfoldl requires the identification of the gfoldl function
arguments. Technically, we also need to identify the type constructor
c for the construction of the result type from the folded term type.

In the definition of gmapQx combinators, we use phantom type
constructors for the c in the type of gfoldl because the result type
of a query does not involve the (polymorphic) type of the term argument.
In the definition of gmapQl we simply use the plain constant type
constructor because gfoldl is left-associative anyway and so it is
readily suited to fold a left-associative binary operation over the
immediate subterms. In the definition of gmapQr, extra effort is
needed. We use a higher-order accumulation trick to mediate between
left-associative constructor application vs. right-associative binary
operation (e.g., (:)). When the query is meant to compute a value
of type r, then the result type withing generic folding is r -> r.
So the result of folding is a function to which we finally pass the
right unit.

With the -XDeriveDataTypeable option, GHC can generate instances of the
Data class automatically. For example, given the declaration