Running a parser

Command line arguments to parse. Presumably you got these from
getArgs. If there is any chance that you will be parsing
Unicode strings, see the documentation in
System.Console.MultiArg.GetArgs before you use
getArgs.

Higher-level parser combinators

Runs the first parser. If it fails without consuming any input,
then runs the second parser. If the first parser succeeds, then
returns the result of the first parser. If the first parser fails
and consumes input, then returns the result of the first
parser. This provides the implementation for
<|> in Alternative.

Combines two parsers into a single parser. The second parser can
optionally depend upon the result from the first parser.

This applies the first parser. If the first parser succeeds,
combine then takes the result from the first parser, applies the
function given to the result from the first parser, and then
applies the resulting parser.

If the first parser fails, combine will not apply the second
function but instead will bypass the second parser.

lookAhead p runs parser p. If p succeeds, lookAhead p succeeds
without consuming any input. If p fails without consuming any
input, so does lookAhead. If p fails and consumes input, lookAhead
also fails and consumes input. If this is undesirable, combine with
try.

Running parsers multiple times

Runs a parser zero or more times. If the last run of the parser
fails without consuming any input, this parser succeeds without
consuming any input. If the last run of the parser fails while
consuming input, this parser fails while consuming input. This
provides the implementation for many in Control.Applicative.

manyTill p end runs parser p zero or more times until parser
end succeeds. If end succeeds and consumes input, that input is
also consumed. in the result of manyTill. If that is a problem,
wrap it in lookAhead. Also, if end fails and consumes input,
manyTill fails and consumes input. If that is a problem, wrap
end in try.

Parsers

Short options and arguments

Parses only pending short options. Fails without consuming any
input if there has already been a stopper or if there are no
pending short options. Fails without consuming any input if there
is a pending short option, but it does not match the short option
given. Succeeds and consumes a pending short option if it matches
the short option given.

Parses only pending short option arguments. For example, for the
tail command, if you enter the option -c25, then after parsing
the -c option the 25 becomes a pending short option argument
because it was in the same command line argument as the -c.

Fails without consuming any input if:

a stopper has already been parsed

there are no pending short option arguments

On success, returns the String of the pending short option argument
(this String will never be empty).

Long options and arguments

Parses an exact long option. That is, the text of the
command-line option must exactly match the text of the
option. Returns any argument that is attached to
the same word of the option with an equal sign (for example,
--follow=/dev/random will return Just "/dev/random" for the
argument.) If there is no equal sign, returns Nothing for the
argument. If there is an equal sign but there is nothing after it,
returns Just "" for the argument.

If you do not want your long option to have equal signs and
GNU-style option arguments, wrap this parser in something that will
fail if there is an option argument.

Fails without consuming any input if:

there are pending short options

a stopper has been parsed

there are no arguments left on the command line

the next argument on the command line does not begin with
two dashes

the next argument on the command line is -- (a stopper)

the next argument on the command line does begin with two
dashes but its text does not match the argument we're looking for

Examines the next word. If it matches a LongOpt in the set
unambiguously, returns a tuple of the word actually found and the
matching word in the set and the accompanying text after the equal
sign (if any). If the Set is empty, this parser will always fail.

Positional (non-option) arguments

Returns the next string on the command line as long as there are
no pendings. Succeeds even if a stopper is present. Be careful -
this will return the next string even if it looks like an option
(that is, it starts with a dash.) Consider whether you should be
using nonOptionPosArg instead. However this can be useful when
parsing command line options after a stopper.

Parses the next word on the command line, but only if it exactly
matches the word given. Otherwise, fails without consuming any
input. Also fails without consuming any input if there are pending
short options or if a stopper has already been parsed. Does not pay
any attention to whether a stopper is present.

If there are pending short options, fails without consuming any input.

Otherwise, if a stopper has NOT already been parsed, then returns
the next word if it is either a single dash or any other word that
does not begin with a dash. If the next word does not meet these
criteria, fails without consuming any input.

Otherwise, if a stopper has already been parsed, then returns the
next word, regardless of whether it begins with a dash or not.

Examines the possible words in Set. If there are no pendings,
then get the next word and see if it matches one of the words in
Set. If so, returns the word actually parsed and the matching word
from Set. If there is no match, fails without consuming any
input. Pays no attention to whether a stopper has been seen.