System.Console.MultiArg.SimpleParser

A simple command line parser that can parse options that take an optional argument, one or two arguments, or a variable number of arguments. For sample code that uses this parser, see System.Console.MultiArg.SampleParser.

Interspersion control

data Intersperse

What to do after encountering the first non-option, non-option-argument word on the command line? In either case, no more options are parsed after a stopper.

Constructors

Intersperse

Additional options are allowed on the command line after encountering the first positional argument. For example, if a and b are options, in the command line -a posarg -b, b will be parsed as an option. If b is not an option and the same command line is entered, then -b will result in an error because -b starts with a hyphen and therefore "looks like" an option.

StopOptions

No additional options will be parsed after encountering the first positional argument. For example, if a and b are options, in the command line -a posarg -b, b will be parsed as a positional argument rather than as an option.

Option specifications

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.

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.

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.

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.

Exceptions

data Exceptional e a

Like Either, but explicitly intended for handling of exceptional results. In contrast to Either we do not support fail. Calling fail in the Exceptional monad is an error. This way, we do not require that an exception can be derived from a String, yet, we require no constraint on the exception type at all.

Constructors

Success a

Exception e

Instances

Monad (Exceptional e)

Functor (Exceptional e)

MonadFix (Exceptional e)

Applicative (Exceptional e)

(Eq e, Eq a) => Eq (Exceptional e a)

(Show e, Show a) => Show (Exceptional e a)

data Error

An Error contains a list of Messages and a String indicating where the error happened.

Constructors

Error [Message] Location

Instances

Show Error

data Message

Error messages.

Constructors

Expected String

The parser expected to see one thing, but it actually saw something else. The string indicates what was expected.

StrMsg String

The fromString function was applied.

Replaced String

A previous list of error messages was replaced with this error message.

UnknownError

Any other error; used by genericThrow.

Instances

Show Message

Get command line arguments

getArgs :: IO [String]

Gets the command-line arguments supplied by the program's user. If the base package is older than version 4.4, then this function assumes the command line is encoded in UTF-8, which is true for many newer Unix systems; however, many older systems may use single-byte encodings like ISO-8859. In such cases, this function will give erroneous results.

If the base package is version 4.4.0 or newer, this function simply uses the getArgs that comes with base. That getArgs detects the system's default encoding and uses that, so it should give accurate results on most systems.

The parser

parse

Arguments

:: Intersperse

What to do after encountering the first positional argument

-> [OptSpec a]

All possible options

-> (String -> a)

How to handle positional arguments. This function is applied to the appropriate string every time the parser encounters a positional argument.

-> [String]

The command line to parse. This function correctly handles Unicode strings; however, because getArgs does not always correctly handle Unicode strings, consult the documentation in GetArgs and consider using the functions in there if there is any chance that you will be parsing command lines that have non-ASCII strings.

-> Exceptional Error [a]

Parse a command line.