Safe Haskell	Safe-Inferred

System.Console.MultiArg.SimpleParser

Contents

Interspersion control
The parser
Parsing multi-mode command lines

Description

Some pre-built command line parsers. One is 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.

Another parser is provided for multi-mode programs that are similar to git or darcs.

Synopsis

Interspersion control

data Intersperse Source

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.

The parser

simple Source

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.

simpleWithHelp Source

Arguments

:: (String -> String)	Help message. Printed as is, so it can be one line or have many lines. It should however have a final end-of-line character. The function is applied to the name of the program (which is retrieved at runtime.)
-> Intersperse	What to do after encountering the first positional argument
-> [OptSpec a]	All possible options. Do not add a `-h` or `--help` option; these are added for you.
-> (String -> a)	How to handle positional arguments. This function is applied to the appropriate string every time the parser encounters a positional argument.
-> IO [a]	If help is requested, the program will print it and exit successfully. If there was an error parsing the command line, the program will print an error message and exit unsuccessfully. Otherwise, the parsed arguments are returned.

Parses a simple command line (that is, one without modes) in the IO monad. Gets the arguments for you using getArgs. In addition to the arguments you provide for simple, you also provide online help. This function adds -h and --help options and shows help if the user entered one of these options anywhere on the command line. If help is shown, the program exits successfully. In addition, it will print a message to standard error if parsing the command line fails and then exit unsuccessfully.

Parsing multi-mode command lines

data Mode result Source

Provides information on each mode that you wish to parse.

Constructors

forall b . Mode

Fields

mName :: String: How the user identifies the mode on the command line. For example, with git this would be commit, pull, etc.
mIntersperse :: Intersperse: Each mode may have options and positional arguments; may these be interspersed?
mOpts :: [OptSpec b]: Options for this mode
mPosArgs :: String -> b: How to parse positional arguments for this mode
mProcess :: [b] -> result: Processes the options after they have been parsed.
mHelp :: String -> String: Help string for this mode. This is used only in modesWithHelp; modes ignores this. This is displayed on screen exactly as is, so be sure to include the necessary trailing newline. The function is applied to the name of the program (which is retrieved at runtime.)

Instances

Functor Mode

modes Source

Arguments

:: [OptSpec a]	Global options. These come after the program name but before the mode name.
-> ([a] -> Either ([String] -> result) [Mode result])	This function will be applied to the result of parsing the global options. The function must return a `Left` if you do not want to parse any modes at all. This can be useful if one of the global options was something like `--help` or `--version` and so you do not need to see any mode. The function returned in the `Left` will be applied to a list of all remaining command-line arguments after the global options.
-> [String]	The command line to parse (presumably from `getArgs`)
-> Exceptional Error result	Returns an Exception if an error was encountered when parsing any part of the command line (either the global options or the mode.) Otherwise, returns the result.

Parses a command line that may feature options followed by a mode followed by more options and then followed by positional arguments.

modesWithHelp Source

Arguments

:: (String -> String)	Global help. This is a function that, when applied to the name of the program (which is retrieved at runtime), returns a help string. This is output exactly as is, so include any necessary trailing newlines.
-> [OptSpec a]	Global options. These come after the program name but before the mode name. Do not add options for `-h` or `--help`; these are added automatically.
-> ([a] -> Either ([String] -> result) [Mode result])	This function will be applied to the result of parsing the global options. The function must return a `Left` if you do not want to parse any modes at all. This can be useful if one of the global options was something like `--version` and so you do not need to see any mode. The function returned in the `Left` will be applied to a list of all remaining command-line arguments after the global options.
-> IO result

Like modes, but runs in the IO monad. Gets the command line arguments for you. This function adds the options -h and --help, both in the global options and in the options for each mode. If -h or --help is entered in the global options, the global help is shown and the program exits successfully; similarly, if help is requested for a particular mode, that mode's help is shown and the program exits successfully.

If an error occurs in the processing of the command line, an error message is printed and the program exits with a failure.