The parser is built using applicative style starting from a set of basic
combinators. In this example, hello is defined as an option with a
String argument, while quiet is a boolean flag (called switch).

The greet function is the entry point of the program, while opts is a
complete description of the program, used when generating a help text. The
helper combinator takes any parser, and adds a help option to it (which
always fails).

The hello option in this example is mandatory (since it doesn't have a
default value), so running the program without any argument will display a
help text:

hello - a test for optparse-applicative
Usage: hello --hello TARGET [--quiet]
Print a greeting for TARGET
Available options:
-h,--help Show this help text
--hello TARGET Target for the greeting
--quiet Whether to be quiet

containing a short usage summary, and a detailed list of options with
descriptions.

The parser is built using applicative style starting from a set
of basic combinators. In this example, hello is defined as an option with a
String argument, while quiet is a boolean flag (called switch).

The greet function is the entry point of the program, while opts is a
complete description of the program, used when generating a help text. The
helper combinator takes any parser, and adds a help option to it.

The hello option in this example is mandatory (since it doesn't have a
default value), so running the program without any argument will display a
short option summary:

Usage: hello --hello TARGET [--quiet]

Running the program with the --help option will display the full help text:

hello - a test for optparse-applicative
Usage: hello --hello TARGET [--quiet]
Print a greeting for TARGET
Available options:
-h,--help Show this help text
--hello TARGET Target for the greeting
--quiet Whether to be quiet

containing a detailed list of options with descriptions.

Parsers are instances of both Applicative and Alternative, and work with
any generic combinator, like many and some. For example, to make a option
return Nothing instead of failing when it's not supplied, you can use the
optional combinator in Control.Applicative:

Supported options

Regular options

A regular option is an option which takes a single argument, parses it, and
returns a value.

A regular option can have a default value, which is used as the result if the
option is not found in the command line. An option without a default value is
considered mandatory, and produces an error when not found.

Regular options can have long names, or short (one-character) names,
which determine when the option matches and how the argument is extracted.

An option with a long name (say "output") is specified on the command line as

--output filename.txt

or

--output=filename.txt

while a short name option (say "o") can be specified with

-o filename.txt

or

-ofilename.txt

Options can have more than one name, usually one long and one short, although
you are free to create options with an arbitrary combination of long and short
names.

Regular options returning strings are the most common, and they can be created
using the strOption builder. For example,

creates a regular option with a string argument (which can be referred to as
FILE in the help text and documentation), a long name "output" and a short
name "o". See below for more information on the builder syntax and modifiers.

A regular option can return an object of any type, provided you specify a
reader for it. A common reader is auto, used by the option builder,
which assumes a Read instance for the return type and uses it to parse its
argument. For example:

specifies a regular option with an Int argument. We added an explicit type
annotation here, since without it the parser would have been polymorphic in the
output type. There's usually no need to add type annotations, however, because
the type will be normally inferred from the context in which the parser is
used.

You can also create a custom reader without using the Read typeclass, and set
it as the reader for an option using the reader modifier and the nullOption
builder:

Arguments

The argument builder takes a reader parameter, and creates a parser which
will return the parsed value every time it is passed a command line argument
for which the reader succeeds. For example

argument str (metavar "FILE")

creates an argument accepting any string. To accept an arbitrary number of
arguments, combine the argument builder with either the many or some
combinator:

some (argument str (metavar "FILES..."))

Arguments are only displayed in the brief help text, so there's no need to
attach a description to them. They should be manually documented in the program
description.

Note that arguments starting with - are considered options by default, and
will not be considered by an argument parser.

However, parsers always accept a special argument: --. When a -- is found on
the command line, all the following words are considered by argument parsers,
regardless of whether they start with - or not.

Commands

A command can be used to specify a sub-parser to be used when a certain
string is encountered in the command line.

Commands are useful to implement command line programs with multiple functions,
each with its own set of options, and possibly some global options that apply
to all of them. Typical examples are version control systems like git, or
build tools like cabal.

A command can be created using the subparser builder, and commands can be
added with the command modifier. For example

Each command takes a full ParserInfo structure, which will be used to extract
a description for this command when generating a help text.

Note that all the parsers appearing in a command need to have the same type.
For this reason, it is often best to use a sum type which has the same
structure as the command itself. For example, for the parser above, you would
define a type like:

Option builders

Builders allow you to define parsers using a convenient combinator-based
syntax. Each builder takes a modifier as parameter, and returns a parser.

A modifier is a composition of functions which act on the option, setting
values for properties or adding features, and is used to build the option from
scratch and finally lift it to a single-option parser, which can then be
combined with other parsers using normal Applicative combinators.

Modifiers are instances of the Monoid typeclass, so they can be combined
using the composition function mappend (or simply (<>)).

See the haddock documentation for Options.Applicative.Builder for a full list
of builders and modifiers.