Multiarg

Parse command lines with options that might take multiple option arguments.

I built this library could not find anything that would readily parse command lines where the options took more than one option argument. For example, for the tail command on GNU systems, the --lines option takes one option argument to specify how many lines you want to see. Well, what if you want to build a program with an option that takes two option arguments, like --foo bar baz? I found no such library so I built this one.

Please consult the Multiarg.Vocabulary module to learn common vocabulary used throughout Multiarg and its documentation. Words that appear in italics are defined in Multiarg.Vocabulary.

Use this module to build parsers for simple commands. The parseCommandLine function runs in the IO monad and will cause your program to exit unsuccessfully if there are any errors in the command line, printing an error message in the process. If you want more control over error handling, use the Multiarg.Internal module.

To write parsers for commands with multiple modes (for instance, ghc-pkg has multiple modes, such as ghc-pkg list and ghc-pkg check) use the Multiarg.Mode module.

You will find examples in Multiarg.Examples.Telly for non-mode parsers, and in Multiarg.Examples.Grover for mode parsers.

Documentation

data ArgSpec a

Specifies how many option arguments an option takes.

Constructors

ZeroArg a

This option takes no option arguments

OneArg (String -> a)

This option takes one option argument

TwoArg (String -> String -> a)

This option takes two option arguments

ThreeArg (String -> String -> String -> a)

This option takes three option arguments

Instances

Functor ArgSpec

Show (ArgSpec a)

data OptSpec a

Specifies an option. Typically you will use optSpec to create an OptSpec rather than using the constructor directly. Each OptSpec may contain mulitple short option names and long option names; but each OptSpec contains only one ArgSpec. Therefore, all short option names and long option names specified in a single OptSpec are synonymous.

Instances

Functor OptSpec

Show (OptSpec a)

optSpec

Arguments

:: [Char]

There is one character for each desired short option name. Each of these characters may not be a hyphen; otherwise, optSpec will apply error.

-> [String]

There is one string for each desired long option name. Each string:

• cannot be empty;
• must not begin with a hyphen; and
• must not contain an equal sign.

Otherwise, optSpec will apply error.

-> ArgSpec a

How many option arguments this option takes. This also specifies what is returned when the option is parsed on the command line.

-> OptSpec a

Creates an OptSpec.

parseCommandLine

Arguments

:: (String -> String)

Returns help for your command. This function is applied to the name of the program being run, which is obtained from getProgName. The function should return a string that gives help for how to use your command; this string is printed as-is.

-> [OptSpec a]

All program options. An option for -h and for --help is added for you, using the help function given above. If the user asks for help, then it is printed and the program exits successfully. If the user gives a command line with one or more errors in it, an error message is printed, along with something like Enter program-name --help for help.

-> (String -> a)

Processes positional arguments.

-> IO [a]

Fetches the words from the command line arguments using getArgs and parses them. If there is an error, prints an error message and exits unsuccessfully. Otherwise, returns the parsed result, where each item in the list corresponds to a parsed option or positional argument in the order in which it appeared on the command line.

Parses a command line. Runs in the IO monad so that it can do some tedious things for you:

• fetches the words on command line using getArgs and the name of the program with getProgName
• prints help, if the user requested help, and exits successfully
• prints an error message and exits unsuccessfully, if the user entered a bad command line (such as an unknown option)

If you don't want this degree of automation or if you want a pure function, see the parseCommandLinePure function in the Multiarg.Internal module.