|
System.Console.CmdArgs.Explicit |
|
|
|
|
Description |
This module constructs command lines. You may either use the helper functions
(flagNone, flagOpt, mode etc.) or construct the type directly. These
types are intended to give all the necessary power to the person constructing
a command line parser.
For people constructing simpler command line parsers, the module
System.Console.CmdArgs.Implicit may be more appropriate.
As an example of a parser:
arguments :: Mode [(String,String)]
arguments = mode "explicit" [] "Explicit sample program" (flagArg (upd "file") "FILE")
[flagOpt "world" ["hello","h"] (upd "world") "WHO" "World argument"
,flagReq ["greeting","g"] (upd "greeting") "MSG" "Greeting to give"
,flagHelpSimple (("help",""):)]
where upd msg x v = Right $ (msg,x):v
And this can be invoked by:
main = do
x <- processArgs arguments
if ("help","") `elem` xs then
print $ helpText def arguments
else
print x
Groups: The Group structure allows flags/modes to be grouped for the purpose of
displaying help. When processing command lines, the group structure is ignored.
Modes: The Explicit module allows multiple mode programs by placing additional modes
in modeGroupModes. Every mode is allowed sub-modes, and thus multiple levels of mode
may be created. Given a mode x with sub-modes xs, if the first argument corresponds
to the name of a sub-mode, then that sub-mode will be applied. If not, then the arguments
will be processed by mode x. Consequently, if you wish to force the user to explicitly
enter a mode, simply give sub-modes, and leave modeArgs as Nothing. Alternatively, if
you want one sub-mode to be selected by default, place all it's flags both in the sub-mode
and the outer mode.
|
|
Synopsis |
|
|
|
|
Running command lines
|
|
|
Process a list of flags (usually obtained from getArgs) with a mode. Returns
Left and an error message if the command line fails to parse, or Right and
the associated value.
|
|
|
Process a list of flags (usually obtained from getArgs) with a mode. Displays
an error and exits with failure if the command line fails to parse, or returns
the associated value. Implemeneted in terms of process.
|
|
|
Process the flags obtained by getArgs with a mode. Displays
an error and exits with failure if the command line fails to parse, or returns
the associated value. Implemented in terms of process.
|
|
Constructing command lines
|
|
|
A name, either the name of a flag (--foo) or the name of a mode.
|
|
|
A help message that goes with either a flag or a mode.
|
|
|
The type of a flag, i.e. --foo=TYPE.
|
|
|
Parse a boolean, accepts as True: true yes on enabled 1.
|
|
|
A group of items (modes or flags). The items are treated as a list, but the
group structure is used when displaying the help message.
| Constructors | Group | | groupUnnamed :: [a] | Normal items.
| groupHidden :: [a] | Items that are hidden (not displayed in the help message).
| groupNamed :: [(Help, [a])] | Items that have been grouped, along with a description of each group.
|
|
| Instances | |
|
|
|
Convert a group into a list.
|
|
|
Convert a list into a group, placing all fields in groupUnnamed.
|
|
|
A mode. Each mode has three main features:
| Constructors | Mode | | modeGroupModes :: Group (Mode a) | The available sub-modes
| modeNames :: [Name] | The names assigned to this mode (for the root mode, this name is used as the program name)
| modeValue :: a | Value to start with
| modeCheck :: a -> Either String a | Check the value reprsented by a mode is correct, after applying all flags
| modeReform :: a -> Maybe [String] | Given a value, try to generate the input arguments.
| modeHelp :: Help | Help text
| modeHelpSuffix :: [String] | A longer help suffix displayed after a mode
| modeArgs :: Maybe (Arg a) | An unnamed argument
| modeGroupFlags :: Group (Flag a) | Groups of flags
|
|
| Instances | |
|
|
|
Extract the modes from a Mode
|
|
|
Extract the flags from a Mode
|
|
|
The FlagInfo type has the following meaning:
FlagReq FlagOpt FlagOptRare/FlagNone
-xfoo -x=foo -x=foo -x= -foo
-x foo -x=foo -x foo -x= foo
-x=foo -x=foo -x=foo -x=foo
--xx foo --xx=foo --xx foo --xx foo
--xx=foo --xx=foo --xx=foo --xx=foo
| Constructors | FlagReq | Required argument
| FlagOpt String | Optional argument
| FlagOptRare String | Optional argument that requires an = before the value
| FlagNone | No argument
|
| Instances | |
|
|
|
Extract the value from inside a FlagOpt or FlagOptRare, or raises an error.
|
|
|
A function to take a string, and a value, and either produce an error message
(Left), or a modified value (Right).
|
|
|
A flag, consisting of a list of flag names and other information.
| Constructors | Flag | | flagNames :: [Name] | The names for the flag.
| flagInfo :: FlagInfo | Information about a flag's arguments.
| flagValue :: Update a | The way of processing a flag.
| flagType :: FlagHelp | The type of data for the flag argument, i.e. FILE/DIR/EXT
| flagHelp :: Help | The help message associated with this flag.
|
|
| Instances | |
|
|
|
An unnamed argument. Anything not starting with - is considered an argument,
apart from "-" which is considered to be the argument "-", and any arguments
following "--". For example:
programname arg1 -j - --foo arg3 -- -arg4 --arg5=1 arg6
Would have the arguments:
["arg1","-","arg3","-arg4","--arg5=1","arg6"]
| Constructors | Arg | | argValue :: Update a | A way of processing the argument.
| argType :: FlagHelp | The type of data for the argument, i.e. FILE/DIR/EXT
|
|
| Instances | |
|
|
|
Check that a mode is well formed.
|
|
|
| Methods | | :: a -> b | Embed a value
| -> b -> (a, a -> b) | Extract the mode and give a way of re-embedding
| -> m a | | -> m b | |
|
| | Instances | |
|
|
remap2 :: Remap m => (a -> b) -> (b -> a) -> m a -> m b | Source |
|
|
|
Create an empty mode specifying only modeValue. All other fields will usually be populated
using record updates.
|
|
|
Create a mode with a name, an initial value, some help text, a way of processing arguments
and a list of flags.
|
|
|
Create a list of modes, with a program name, an initial value, some help text and the child modes.
|
|
|
Create a flag taking no argument value, with a list of flag names, an update function
and some help text.
|
|
|
Create a flag taking an optional argument value, with an optional value, a list of flag names,
an update function, the type of the argument and some help text.
|
|
|
Create a flag taking a required argument value, with a list of flag names,
an update function, the type of the argument and some help text.
|
|
|
Create an argument flag, with an update function and the type of the argument.
|
|
|
Create a boolean flag, with a list of flag names, an update function and some help text.
|
|
|
Create a help flag triggered by -?/--help.
|
|
|
Create a help flag triggered by -?/--help. The user
may optionally modify help by specifying the format, such as:
--help=all - help for all modes
--help=html - help in HTML format
--help=100 - wrap the text at 100 characters
--help=100,one - full text wrapped at 100 characters
|
|
|
Create a version flag triggered by -V/--version.
|
|
|
Create verbosity flags triggered by -v/--verbose and
-q/--quiet
|
|
Displaying help
|
|
|
Specify the format to output the help.
| Constructors | HelpFormatDefault | Equivalent to HelpFormatAll if there is not too much text, otherwise HelpFormatOne.
| HelpFormatOne | Display only the first mode.
| HelpFormatAll | Display all modes.
|
| Instances | |
|
|
|
Generate a help message from a mode.
|
|
Produced by Haddock version 2.6.1 |