System.Console.MultiArg.Combinator

Combinators that are useful for building command-line parsers. These build off the functions in System.Console.MultiArg.Prim. Unlike those functions, these functions have no access to the internals of the parser.

Parser combinators

notFollowedBy :: Parser a -> Parser ()

notFollowedBy p succeeds only if parser p fails. If p fails, notFollowedBy succeeds without consuming any input. If p succeeds and consumes input, notFollowedBy fails and consumes input. If p succeeds and does not consume any input, notFollowedBy fails and does not consume any input.

Combined long and short option parser

data OptSpec a

Specifies options for the parseOption function. Each OptSpec represents one command-line option.

Constructors

OptSpec

Fields

longOpts :: [String]

Each String is a single long option, such as version. When the user specifies long options on the command line, she must type two dashes; however, do not include the dashes when you specify the long option here. Strings you specify as long options cannot include a dash as either the first or the second character, and they cannot include an equal sign anywhere. If your long option does not meet these conditions, a runtime error will occur.

shortOpts :: [Char]

Each Char is a single short option, such as v. The character cannot be a dash; if it is, a runtime error will occur.

argSpec :: ArgSpec a

What to do each time one of the given long options or short options appears on the command line.

Instances

Functor OptSpec

data InputError

Indicates errors when parsing options to arguments.

Constructors

NoMsg

No error message accompanies this failure. multiarg will create a generic error message for you.

ErrorMsg String

Parsing the argument failed with this error message. An example might be option argument is not an integer or option argument is too large. The text of the options the user provided is automatically prepended to the error message, so do not replicate this in your message.

Instances

Eq InputError

Show InputError

reader :: Read a => String -> Either InputError a

Reads in values that are members of Read. Provides a generic error message if the read fails.

optReader :: Read a => Maybe String -> Either InputError (Maybe a)

Reads in values that are members of Read, but the value does not have to appear on the command line. Provides a generic error message if the read fails. If the argument is Nothing, returns Nothing.

data ArgSpec a

Specifies how many arguments each option takes. As with ArgDescr, there are (at least) two ways to use this type. You can simply represent each possible option using different data constructors in an algebraic data type. Or you can have each ArgSpec yield a function that transforms a record. For an example that uses an algebraic data type, see System.Console.MultiArg.SampleParser.

Most of these value constructors take as an argument a function that returns an Either. The function should return a Left InputError if the parsing of the arguments failed--if, for example, the user needs to enter an integer but she instead input a letter. The functions should return a Right if parsing of the arguments was successful.

Constructors

NoArg a

This option takes no arguments

OptionalArg (Maybe String -> Either InputError a)

This option takes an optional argument. As noted in "The Tao of Option Parsing", optional arguments can result in some ambiguity. (Read it here: http://optik.sourceforge.net/doc/1.5/tao.html) If option a takes an optional argument, and b is also an option, what does -ab mean? SimpleParser resolves this ambiguity by assuming that b is an argument to a. If the user does not like this, she can specify -a -b (in such an instance -b is not parsed as an option to -a, because -b begins with a hyphen and therefore "looks like" an option.) Certainly though, optional arguments lead to ambiguity, so if you don't like it, don't use them :)

OneArg (String -> Either InputError a)

This option takes one argument. Here, if option a takes one argument, -a -b will be parsed with -b being an argument to option a, even though -b starts with a hyphen and therefore "looks like" an option.

TwoArg (String -> String -> Either InputError a)

This option takes two arguments. Parsed similarly to OneArg.

ThreeArg (String -> String -> String -> Either InputError a)

This option takes three arguments. Parsed similarly to OneArg.

VariableArg ([String] -> Either InputError a)

This option takes a variable number of arguments--zero or more. Option arguments continue until the command line contains a word that begins with a hyphen. For example, if option a takes a variable number of arguments, then -a one two three -b will be parsed as a taking three arguments, and -a -b will be parsed as a taking no arguments. If the user enters -a as the last option on the command line, then the only way to indicate the end of arguments for a and the beginning of positional argments is with a stopper.

ChoiceArg [(String, a)]

This option takes a single argument, which must match one of the strings given in the list. The user may supply the shortest unambiguous string. If the argument list to ChoiceArg has duplicate strings, only the first string is used. For instance, ChoiceArg could be useful if you were parsing the --color option to GNU grep, which requires the user to supply one of three arguments: always, never, or auto.

Instances

Functor ArgSpec

parseOption :: [OptSpec a] -> Parser a

Parses a single command line option. Examines all the options specified using multiple OptSpec and parses one option on the command line accordingly. Fails without consuming any input if the next word on the command line is not a recognized option. Allows the user to specify the shortest unambiguous match for long options; for example, the user could type --verb for --verbose and --vers for --version.

This function is applied to a list of OptSpec, rather than to a single OptSpec, because in order to correctly handle the parsing of shortened long options (e.g. --verb rather than --verbose) it is necessary for one function to have access to all of the OptSpec. Applying this function multiple times to different lists of OptSpec and then using the | function to combine them will break the proper parsing of shortened long options.

For an example that uses this function, see System.Console.MultiArg.SimpleParser.

Formatting errors

formatError

Arguments

:: String

Pass the name of your program here. Displayed at the beginning of the error message.

-> Error

-> String

Formats error messages for nice display. Returns a multi-line string (there is no need to append a newline to the end of the string returned).