Safe Haskell | Safe-Infered |
---|
System.Console.CmdArgs.Explicit
Contents
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 xs <-processArgs
arguments if ("help","") `elem` xs then print $helpText
[]HelpFormatDefault
arguments else print xs
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.
Parsing rules: Command lines are parsed as per most GNU programs. Short arguments single
letter flags start with -
, longer flags start with --
, and everything else is considered
an argument. Anything after --
alone is considered to be an argument. For example:
-f --flag argument1 -- --argument2
This command line passes one single letter flag (f
), one longer flag (flag
) and two arguments
(argument1
and --argument2
).
- process :: Mode a -> [String] -> Either String a
- processArgs :: Mode a -> IO a
- processValue :: Mode a -> [String] -> a
- module System.Console.CmdArgs.Explicit.Type
- flagHelpSimple :: (a -> a) -> Flag a
- flagHelpFormat :: (HelpFormat -> TextFormat -> a -> a) -> Flag a
- flagVersion :: (a -> a) -> Flag a
- flagsVerbosity :: (Verbosity -> a -> a) -> [Flag a]
- module System.Console.CmdArgs.Explicit.Help
- module System.Console.CmdArgs.Explicit.ExpandArgsAt
- module System.Console.CmdArgs.Explicit.SplitJoin
- data Complete
- complete :: Mode a -> [String] -> (Int, Int) -> [Complete]
Running command lines
process :: Mode a -> [String] -> Either String a
Process a list of flags (usually obtained from getArgs
/expandArgsAt
) with a mode. Returns
Left
and an error message if the command line fails to parse, or Right
and
the associated value.
processArgs :: Mode a -> IO a
Process the flags obtained by
and 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 expandArgsAt
process
. This function makes
use of the following environment variables:
-
$CMDARGS_COMPLETE
- causes the program to produce completions usingcomplete
, then exit. Completions are based on the result ofgetArgs
, the index of the current argument is taken from$CMDARGS_COMPLETE
(set it to-
to complete the last argument), and the index within that argument is taken from$CMDARGS_COMPLETE_POS
(if set). -
$CMDARGS_HELPER
/$CMDARGS_HELPER_PROG
- uses the helper mechanism for entering command line programs as described in System.Console.CmdArgs.Helper.
processValue :: Mode a -> [String] -> a
Process a list of flags (usually obtained from
and 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 expandArgsAt
process
. This function
does not take account of any environment variables that may be set
(see processArgs
).
Constructing command lines
flagHelpSimple :: (a -> a) -> Flag a
Create a help flag triggered by -?
/--help
.
flagHelpFormat :: (HelpFormat -> TextFormat -> a -> a) -> Flag a
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
flagVersion :: (a -> a) -> Flag a
Create a version flag triggered by -V
/--version
.
flagsVerbosity :: (Verbosity -> a -> a) -> [Flag a]
Create verbosity flags triggered by -v
/--verbose
and
-q
/--quiet
Displaying help
Utilities for working with command lines
data Complete
How to complete a command line option.
The Show
instance is suitable for parsing from shell scripts.
Constructors
CompleteValue String | Complete to a particular value |
CompleteFile String FilePath | Complete to a prefix, and a file |
CompleteDir String FilePath | Complete to a prefix, and a directory |
Arguments
:: Mode a | Mode specifying which arguments are allowed |
-> [String] | Arguments the user has already typed |
-> (Int, Int) | 0-based index of the argument they are currently on, and the position in that argument |
-> [Complete] |
Given a current state, return the set of commands you could type now, in preference order.