Building

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

Versioning

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.

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.

Changes

* 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.

Release 0.28.0.0

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

* 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 options.

Release 0.20.0.0, August 30, 2013Changes since release 0.18.0.0:

* Remove explicit-exception; use Either instead.

Release 0.18.0.0, August 14, 2013Changes since release 0.16.0.0:

* 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 lines

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

Release 0.16.0.0, May 21, 2013Changes since release 0.14.0.0:

* Rename OptArgError to InputError

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

Release 0.14.0.0, April 8, 2013Changes since release 0.12.0.2:

* 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 sign.

Release 0.12.0.2, March 31, 2013Changes since release 0.12.0.0:

* Reorder NEWS so recent versions are on top

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

Release 0.12.0.0, March 27, 2013Changes since release 0.10.0.0:

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

* 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 0.8.0.0, January 8, 2013Changes since release 0.6.0.0:

* 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 0.6.0.0 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 0.6.0.0, September 28, 2012Changes since release 0.4.0.0:

* Add Functor instances for OptSpec, ArgSpec

* Add ThreeArg and ChoiceArg ArgSpecs

Release 0.4.0.0, June 30, 2012Changes since release 0.2.0.0:

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

* 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 complicated.

* Reworked included combinators in Combinator module.

Release 0.2.0.0, April 2, 2012Changes since release 0.1.0.0:

* Henceforth all public releases will have only even numbers in their release numbers (e.g. 0.2.0.0, 0.2.0.2, 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.