Safe Haskell	Safe-Inferred

System.Console.MultiArg.Combinator

Contents

Parser combinators
Combined long and short option parser
Formatting errors

Description

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.

Synopsis

Parser combinators

notFollowedBy :: Parser a -> Parser ()Source

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 Source

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 Source

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 -> Exceptional InputError aSource

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

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

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 Source

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.

Some of these value constructors have names ending in E. Use these constructors when you want to parse option arguments that may fail to parse--for example, you want to parse an Int. The function passed as an argument to the value constructor indicates failure by returing an Exception.

Constructors

NoArg a	This option takes no arguments
OptionalArg (Maybe String -> 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 -> 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 -> a)	This option takes two arguments. Parsed similarly to `OneArg`.
ThreeArg (String -> String -> String -> a)	This option takes three arguments. Parsed similarly to `OneArg`.
VariableArg ([String] -> 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`.
OptionalArgE (Maybe String -> Exceptional InputError a)	This option takes an optional argument, like `OptionalArg`. Parsing of the optional argument might fail.
OneArgE (String -> Exceptional InputError a)	This option takes a single argument, like `OneArg`. Parsing of the argument might fail.
TwoArgE (String -> String -> Exceptional InputError a)	This option takes two arguments, like `TwoArg`. Parsing of the arguments might fail.
ThreeArgE (String -> String -> String -> Exceptional InputError a)	This option takes three arguments, like `ThreeArg`. Parsing of the arguments might fail.
VariableArgE ([String] -> Exceptional InputError a)	This option takes a variable number of arguments, like `VariableArg`. Parsing of the arguments might fail.

Instances

Functor ArgSpec

parseOption :: [OptSpec a] -> Parser aSource

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 Source

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