multiarg- Combinators to build command line parsers

Safe HaskellSafe-Inferred




A simple command line parser that can parse options that take an optional argument, one or two arguments, or a variable number of arguments. For sample code that uses this parser, see System.Console.MultiArg.SampleParser.


Interspersion control

data Intersperse Source

What to do after encountering the first non-option, non-option-argument word on the command line? In either case, no more options are parsed after a stopper.



Additional options are allowed on the command line after encountering the first positional argument. For example, if a and b are options, in the command line -a posarg -b, b will be parsed as an option. If b is not an option and the same command line is entered, then -b will result in an error because -b starts with a hyphen and therefore "looks like" an option.


No additional options will be parsed after encountering the first positional argument. For example, if a and b are options, in the command line -a posarg -b, b will be parsed as a positional argument rather than as an option.

The parser



:: Intersperse

What to do after encountering the first positional argument

-> [OptSpec a]

All possible options

-> (String -> a)

How to handle positional arguments. This function is applied to the appropriate string every time the parser encounters a positional argument.

-> [String]

The command line to parse. This function correctly handles Unicode strings; however, because getArgs does not always correctly handle Unicode strings, consult the documentation in GetArgs and consider using the functions in there if there is any chance that you will be parsing command lines that have non-ASCII strings.

-> Exceptional Error [a] 

Parse a command line.

Parsing multi-mode command lines

data Mode result Source

Provides information on each mode that you wish to parse.


forall b . Mode 


mName :: String

How the user identifies the mode on the command line. For example, with git this would be commit, pull, etc.

mIntersperse :: Intersperse

Each mode may have options and positional arguments; may these be interspersed?

mOpts :: [OptSpec b]

Options for this mode

mPosArgs :: String -> b

How to parse positional arguments for this mode

mProcess :: [b] -> result

Processes the options after they have been parsed.




:: [OptSpec a]

Global options. These come after the program name but before the mode name.

-> ([a] -> Exceptional String b)

This function is applied to all the global options after they are parsed. To indicate a failure, return an Exception String; otherwise, return a successful value. This allows you to process the global options before the mode is parsed. (If you don't need to do any preprocessing, pass return here.) If you indicate a failure here, parsing of the command line will stop and this error message will be returned.

-> (b -> Either (String -> c) [Mode result])

This function determines whether modes will be parsed and, if so, which ones. The function is applied to the result of the pre-processing of the global options, so which modes are parsed and the behavior of those modes can vary depending on the global options. Return a Left to indicate that you do not want to parse modes at all. For instance, if the user passed a --help option, you may not want to look for a mode after that. Otherwise, to parse modes, return a Right with a list of the modes.

-> [String]

The command line to parse (presumably from getArgs)

-> Exceptional Error (b, Either [c] result)

Returns an Exception if an error was encountered when parsing the command line (including if the global options procesor returned an Exception.) Otherwise, returns a pair. The first element of the pair is the result of the global options processor. The second element of the pair is an Either. It is Left if no modes were parsed, with a list of the positional arguments. It is a Right if modes were parsed, with the result of parsing the arguments to the mode.

Parses a command line that may feature options followed by a mode followed by more options and then followed by positional arguments.