Safe Haskell	Safe-Inferred

System.Console.MultiArg.CommandLine

Contents

Interspersion control
Types
Simple parsers
Mode parsers
Helpers to create various options and modes

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.

Previously there was a bug in System.Environment.getArgs that would not properly encode Unicode command line arguments. multiarg used to provide its own GetArgs module to deal with this. This bug was in base 4.3.1.0, which was bundled with ghc 7.0.4. This bug was fixed in base 4.4.0.0, which came with ghc 7.2. Since this bug has been fixed for awhile, multiarg no longer has its own GetArgs module.

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.

Types

type ProgName = String Source

The name of the program that was entered on the command line, obtained from System.Environment.getProgName.

data Opts s a Source

Specifies a set of options.

Constructors

Opts

Fields

oOptions :: [OptSpec a]: If the user does not specify any shortcut options, she may specify any number of these options.
oShortcuts :: [OptSpec s]: Shortcut options are commonly options such as --help or --version. Such options must be specified alone on the command line. The parser looks for one of these options first. If it finds one and it is the only option on the command line, only this option is processed and returned. If the option is not alone on the command line, an error occurs. If no shortcut option is found, the parser processes non-shortcut options instead.

Instances

MapShortcuts Opts
Functor (Opts s)

class MapShortcuts f whereSource

Things that contain shortcut options that can be changed.

Methods

smap :: (a -> b) -> f a o -> f b oSource

Instances

MapShortcuts Mode
MapShortcuts OptsWithPosArgs
MapShortcuts Opts

data OptsWithPosArgs s a Source

Specification for both options and positional arguments.

Constructors

OptsWithPosArgs
Fields opOpts :: Opts s a opIntersperse :: Intersperse opPosArg :: String -> Either InputError a

Instances

MapShortcuts OptsWithPosArgs
Functor (OptsWithPosArgs s)

data Mode s r Source

Specifies a mode.

Constructors

forall a . Mode

Fields

mModeName :: String: How the user specifies the mode on the command line. For git for example this might be commit or log.
mGetResult :: [a] -> r: This function is applied to a list of the results of parsing the options that are specific to this mode. The function returns a type of your choosing (though all modes in the same parser will have to return the same type.)
mOpts :: OptsWithPosArgs s a: Options and positional arguments that are specific to this mode. For example, in the command line git commit -a -m 'this is a log message', commit is the mode name and everything after that is specified here as an option or positional argument that is specific to this mode.

Instances

MapShortcuts Mode
Functor (Mode s)

Simple parsers

simplePure Source

Arguments

:: OptsWithPosArgs s a	Specifies allowed regular options, allowed shortcut options, and how to parse positional arguments. Also specifies whether the user may intersperse options with positional arguments.
-> [String]	The command line arguments to parse
-> Either Error (Either s [a])	Returns an error if the command line arguments could not be parsed. If the parse was successful, returns an Either. A Left indicates that the user selected a shortcut option. A Right indicates that the user did not specify a shortcut option, and will contain a list of the options and positional arguments.

A pure (non-IO) parser for simple command lines--that is, command lines that do not have modes.

simpleIO Source

Arguments

:: [OptSpec a]	Options to parse
-> Intersperse	Allow interspersion of options and arguments?
-> (String -> Either InputError a)	How to parse positional arguments
-> IO [a]	If there is an error parsing the command line, the program will exit with an error message. If successful the results are returned here.

A parser for simple command lines that do not contain modes. Runs in the IO monad.

simpleHelp Source

Arguments

:: (ProgName -> String)	Indicate the help here. This function, when applied to the name of the program, returns help. simpleHelp automatically adds options for `--help` and `-h` for you.
-> [OptSpec a]	Options to parse
-> Intersperse	Allow interspersion of options and positional arguments?
-> (String -> Either InputError a)	How to parse positional arguments
-> IO [a]	If the parser fails, the program will exit with an error. If the user requested help, it will be displayed and the program exits successfully. Otherwise, the options and positional arguments are returned here.

A parser for simple command lines. Adds a --help option for you.

simpleHelpVersion Source

Arguments

:: (ProgName -> String)	Indicate the help here. This function, when applied to the name of the program, returns help. simpleHelpVersion automatically adds options for `--help` and `-h` for you.
-> (ProgName -> String)	Indicate the version here. This function, when applied to the name of the program, returns a version string. simpleHelpVersion automatically adds an option for `--version` for you.
-> [OptSpec a]	Options to parse
-> Intersperse	Allow interspersion of options and positional arguments?
-> (String -> Either InputError a)	How to parse positional arguments
-> IO [a]	If the parser fails, the program will exit with an error. If the user requested help or version information, it will be displayed and the program exits successfully. Otherwise, the options and positional arguments are returned here.

A parser for simple command lines without modes. Adds options for --help and --version for you.

Mode parsers

modesPure Source

Arguments

:: Opts s g	Global options. These are specified before any mode. For instance, in the command `git --no-pager commit -a`, the option `--no-pager` is a global option. Global options can contain shortcut options. For instance, `git --help` contains a single shortcut option.
-> ([g] -> Either String (Either r [Mode s r]))	This function processes the global options. If there are no shortcut options specified in the global options, it is applied to the result of processing the global options. This function may return an Exception if there is something wrong with the global options (a nonsensical combination, perhaps.) Otherwise, it returns an Either. Return a Left if there is no need to process any modes at all after seeing the global options. Otherwise, return a Right with a list of modes.
-> [String]	Command line arguments to parse
-> Either Error (Either s r)	If the command line arguments fail to parse, this will be an Exception with the error. If the parser is successful, this returns an Either. A Left indicates that the user entered a shortcut option, either in the global options or in one of the mode-specific options. A Right indicates that the user selected a mode.

A pure (non-IO) parser for command lines that contain modes.

modesIO Source

Arguments

:: Opts s g	Specifies global options and global shortcut options
-> ([g] -> Either String (Either r [Mode s r]))	This function processes the global options. If there are no shortcut options specified in the global options, it is applied to the result of processing the global options. This function may return an Exception if there is something wrong with the global options (a nonsensical combination, perhaps.) Otherwise, it returns an Either. Return a Left if there is no need to process any modes at all after seeing the global options. Otherwise, return a Right with a list of modes.
-> IO (Either s r)	If parsing fails, the program will exit with a failure. If successful, the result is returned here. A Left indicates a shortcut option, either from the global options or from the mode-specific options; a Right indicates the mode a user selected.

A command line parser for multi-mode command lines. Runs in the IO monad.

Helpers to create various options and modes

optsHelp Source

Arguments

:: h	Whatever type you wish to use for help
-> [OptSpec a]
-> Opts h a

Creates an Opts with a help shortcut option.

optsHelpVersion Source

Arguments

:: h	What you wish to use for help
-> h	What you wish to use for version
-> [OptSpec a]
-> Opts h a

Creates an Opts with help and version shortcut options.

modeHelp Source

Arguments

:: String	Mode name
-> h	Whatever you want to use for the help (perhaps a string, or a function, or an IO action). Its type will have to match up with the type of the global shortcut options and with the shortcut type of the other modes.
-> ([a] -> r)	When applied to the the mode options, returns the result.
-> [OptSpec a]	Options for this mode
-> Intersperse	Allow interspersion of mode options and positional arguments?
-> (String -> Either InputError a)	Parses positional arguments
-> Mode h r

Creates a Mode with a help option (help specific to the mode.)