Command lines for options that take multiple arguments

Version on this page:
LTS Haskell 8.2:
Stackage Nightly 2017-02-22:
Latest on Hackage:
BSD3 licensed by Omari Norman
Maintained by

Module documentation for

There are no documented modules for this package.


This is multiarg, a library of combinators to parse command lines.

For "released" code see Hackage:

multiarg is on Github:


If you obtained this code through Hackage, just build it using the ordinary Cabal command:

cabal install

If you obtain this code on Github, you will first need to generate the Cabal file and generate the tests. This will require that you install two libraries:

cabal install cartel quickpull

Then run this script to generate the Cabal file and the tests:

sh generate


multiarg releases are numbered in accordance with the Haskell Package Versioning Policy.

Currently the multiarg library depends only on the "base" package, so multiarg should have wide compatibility with different compilers and sets of libraries. The tests have some additional dependencies.

Build history

If you're having trouble building multiarg, try looking at the travis-ci build history at:

It shows successful builds and the versions of any package dependencies that were installed when that build succeeded, so it might help you diagnose any dependency issues.

Build Status

Similar libraries

Of course there are many command-line parsing modules and libraries out there; here are some comparisons.

optparse-applicative: very featureful with a well thought-out interface. Builds help for you. I often use this if it meets my needs. From what I can tell, though, it strips out information about the relative ordering of the words from the command line; for instance, if the user typed "hello --opt1 --opt2", you cannot tell whether she entered "--opt1" before she entered "--opt2". Also, from what I can tell it cannot easily parse options that take more than one argument.

GetOpt: comes with the base libraries, so you don't have to install anything extra, which gives it a huge advantage. Keeps information about the relative ordering of the words from the command line. Cannot easily parse options that take more than one argument.

cmdargs: after multiple passes through the Haddocks I could never make any sense of this library at all, which must be a reflection of my level of Haskell ignorance.

More comparisons are at the Haskell Wiki.



* Version bump for QuickCheck


* Completely changed the API. This version is much better tested than
previous versions. Instead of using parser combinators as a model,
this version is built on a Mealy finite state machine.

* The tests are particularly exhaustive; there is a module that
produces all possible command-line words that can parse to a
particular option (for instance, the user might enter "-a -b foo" or
"-abfoo" if -b is an option that takes a single option argument.)
Different combinations are tested randomly.


* Renamed everything from System.Console.MultiArg to Multiarg
(shorter; note also case change from MultiArg to Multiarg)

* Removed existentials from Multiarg.CommandLine

Release, February 24, 2014

* Changed lower bound on base down to

Release, February 18, 2014
Changes since release

* Removed upper bounds from build dependencies, and changed the
lower bounds.

Release, September 12, 2013
Changes since release

* Remove OneArgE, TwoArgE, etc. from Combinator module. These data
constructors were renamed OneArg, TwoArg, etc. Having both OneArg
and OneArgE was redundant.

* Improved error messages when the user enters an unrecognized option.
Previously unrecognized options were passed through to client code
as a positional argument; now they will be recognized as bad

Release, August 30, 2013
Changes since release

* Remove explicit-exception; use Either instead.

Release, August 14, 2013
Changes since release

* Rename SimpleParser module to CommandLine

* Made a number of changes to CommandLine to reorganize the data types
and functions responsible for parsing simple and multi-mode command

* Remove GetArgs, as this was for an old library bug which has been
fixed for some time now

Release, May 21, 2013
Changes since release

* Rename OptArgError to InputError

* Change functions in SimpleParser to allow for positional arguments
that might fail to be parsed

Release, April 8, 2013
Changes since release

* Change long options to remove restrictions on what characters can
make up a long option name. Now the only restriction is that long
options cannot be zero length and they may not contain an equal

Release, March 31, 2013
Changes since release

* Reorder NEWS so recent versions are on top

* Fix bug in Prim.stopper that prevented most stoppers from being

Release, March 27, 2013
Changes since release

* Added value constructors to the Combinator module to allow for
easier parsing of option arguments that can fail to parse

* Added automatic "Enter -h for help" to simpleWithHelp and
modesWithHelp functions in SimpleParser

Release, March 7, 2013
Changes since release

* Added the simpleWithHelp and modesWithHelp pre-built parsers to
the SimpleParser module

* Added the mHelp field to the Mode record to allow for the
modesWithHelp pre-built parser

* Changed the modes function in the SimpleParser module. The new
function has a simpler type. It will however break old code.

Release, January 8, 2013
Changes since release

* Added a multi-mode parser to SimpleParser

* All modules (except SampleParser) are now re-exported from
System.Console.MultiArg. Therefore one import will bring in all of
MultiArg. However, this introduced a naming conflict, because
SimpleParser and Prim both had functions named "parse". Therefore I
renamed SimpleParser.parse to "simple".

* Removed the <??> combinator from Prim and replaced it with
<?>. Removed <?> from Combinator. The new <?> behaves as one would
expect from Parsec.

* Simplified errors. There is now just one type of error message, and
that is a string. Reversed error messages when Prim.parse returns
(this way they are in the order the user would expect.)

* Client code written for will probably break with this
release, mostly because of changes to the export lists. Combinator
no longer re-exports from other modules, because now the expectation
is that if you want to import everything you just import
System.Console.MultiArg. So fixing that is just a matter of changing
imports in client code. Other breakage will be limited to error
handling code.

Release, September 28, 2012
Changes since release

* Add Functor instances for OptSpec, ArgSpec

* Add ThreeArg and ChoiceArg ArgSpecs

Release, June 30, 2012
Changes since release

* Code written for version 0.2.* will not work at all with this

* Removed dependency on text library. multiarg now only deals with
plain Strings. The memory usage concerns that originally led me to
use Texts were unfounded.

* Dramatically simplified code for primitive parsers. No more custom
error types, monad transformers, or user states. This sort of
functionality is easily implemented in the parsers that you can
build; baking it into the primitive parsers makes things needlessly

* Reworked included combinators in Combinator module.

Release, April 2, 2012
Changes since release

* Henceforth all public releases will have only even numbers in their
release numbers (e.g.,, etc.) If a release has any
odd numbers in its version, it is a development release.

* QuickCheck tests are removed. Eventually I will reimplement these in
a separate library package.

* Added Feed function to System.Console.MultiArg.Prim; this allows you
to carry out stateful parses without using a user state. Sometimes
this aids in composability--for instance, I use it when combining
parsers from different parts of the same program.
Depends on:
Used by 5 packages:
comments powered byDisqus