| |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Description | |||||||||||||||||||||||||||||||||||||||
This module provides simple command line argument processing. The main function of interest is cmdArgs. A simple example is: data Sample = Sample {hello :: String} deriving (Show, Data, Typeable) sample = Sample{hello = def &= help "World argument" &= opt "world"} &= summary "Sample v1" main = print =<< cmdArgs sample Attributes are used to control a number of behaviours:
Supported Types: Each field in the record must be one of the supported atomic types (String, Int, Integer, Float, Double, Bool, an enumeration, a tuple of atomic types) or a list ([]) or Maybe wrapping at atomic type. Missing Fields: If a field is shared by multiple modes, it may be omitted in subsequent modes, and will default to the previous value. Purity: Values created with annotations are not pure - the first time they are computed they will include the annotations, but subsequently they will not. If you wish to run the above example in a more robust way: sample = cmdArgsMode $ Sample{hello = ... -- as before main = print =<< cmdArgsRun sample Even using this scheme, sometimes GHC's optimisations may share values who have the same annotation. To disable sharing you may need to specify {-# OPTIONS_GHC -fno-cse #-} in the module you define the flags. | |||||||||||||||||||||||||||||||||||||||
Synopsis | |||||||||||||||||||||||||||||||||||||||
Running command lines | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Take impurely annotated records and run the corresponding command line. Shortcut for cmdArgsRun . cmdArgsMode. | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Take impurely annotated records and turn them in to a Mode value, that can make use of the System.Console.CmdArgs.Explicit functions (i.e. process). Annotated records are impure, and will only contain annotations on their first use. The result of this function is pure, and can be reused. | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Run a Mode structure. This function reads the command line arguments and then performs as follows:
| |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Take purely annotated records and run the corresponding command line. Shortcut for cmdArgsRun . cmdArgsMode_. | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Take purely annotated records and turn them in to a Mode value, that can make use of the System.Console.CmdArgs.Explicit functions (i.e. process). | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Perform the necessary actions dictated by a CmdArgs structure.
| |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Constructing command lines | |||||||||||||||||||||||||||||||||||||||
Attributes can work on a flag (inside a field), on a mode (outside the record), or on all modes (outside the modes call). | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Flag: "I want users to be able to omit the value for this flag." Make the value of a flag optional. If --flag is given, it will be treated as --flag=this_argument. {hello = def &= opt "foo"} -h --hello[=VALUE] (default=foo) | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Flag: "For this flag, users need to give something of type ..." The the type of a flag's value, usually upper case. Only used for the help message. Commonly the type will be FILE (typFile) or DIR (typDir). {hello = def &= typ "MESSAGE"} -h --hello=MESSAGE | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Flag: "Users must give a file for this flag's value." | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Flag: "Users must give a directory for this flag's value." | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Flag/Mode: "The help message is ..." Descriptive text used in the help output. {hello = def &= help "Help message"} -h --hello=VALUE Help message | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Flag: "Use this flag name for this field." Add flags which trigger this option. {hello = def &= name "foo"} -h --hello --foo=VALUE | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Flag: "Put non-flag arguments here." {hello = def &= args} | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Flag: "Put the nth non-flag argument here." This field should be used to store a particular argument position (0-based). {hello = def &= argPos 0} | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Flag/Mode: "Give these flags/modes a group name in the help output." This mode will be used for all following modes/flags, until the next groupname. {hello = def &= groupname "Welcomes"} Welcomes -h --hello=VALUE | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Mode: "A longer description of this mode is ..." Suffix to be added to the help message. Sample{..} &= details ["More details on the website www.example.org"] | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Modes: "My program name/version/copyright is ..." One line summary of the entire program, the first line of --help and the only line of --version. Sample{..} &= summary "CmdArgs v0.0, (C) Neil Mitchell 1981" | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Mode: "If the user doesn't give a mode, use this one." This mode is the default. If no mode is specified and a mode has this attribute then that mode is selected, otherwise an error is raised. modes [Mode1{..}, Mode2{..} &= auto, Mode3{..}] | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Modes: "My program executable is named ..." This is the name of the program executable. Only used in the help message. Defaults to the type of the mode. Sample{..} &= program "sample" | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Flag: "Don't guess any names for this field." A field should not have any flag names guessed for it. All flag names must be specified by flag. {hello = def &= explicit &= name "foo"} --foo=VALUE | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Flag/Mode: "Ignore this field, don't let the user set it." A mode or field is not dealt with by CmdArgs. {hello = def, extra = def &= ignore} --hello=VALUE | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Modes: "My program needs verbosity flags." Add --verbose and --quiet flags. | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Modes: "Customise the help argument." Add extra options to a help argument, such as help, name, ignore or explicit. Sample{..} &= helpArg [explicit, name "h"] | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Modes: "Customise the version argument." Add extra options to a version argument, such as help, name, ignore or explicit. Sample{..} &= versionArg [ignore] | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Modes: "Customise the verbosity arguments." Add extra options to a verbosity arguments (--verbose and --quiet), such as help, name, ignore or explicit. The verbose options come first, followed by the quiet options. Sample{..} &= verbosityArgs [ignore] [name "silent", explicit] | |||||||||||||||||||||||||||||||||||||||
Impure | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Add an annotation to a value. Note that if the value is evaluated more than once the annotation will only be available the first time. | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Modes: "I want a program with multiple modes, like darcs or cabal." Takes a list of modes, and creates a mode which includes them all. If you want one of the modes to be chosen by default, see auto. data Modes = Mode1 | Mode2 | Mode3 deriving Data cmdArgs $ modes [Mode1,Mode2,Mode3] | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Flag: "I want several different flags to set this one field to different values." This annotation takes a type which is an enumeration, and provides multiple separate flags to set the field to each value. data State = On | Off deriving Data data Mode = Mode {state :: State} cmdArgs $ Mode {state = enum [On &= help "Turn on",Off &= help "Turn off"]} --on Turn on --off Turn off | |||||||||||||||||||||||||||||||||||||||
Pure | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Add an annotation to a value. | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Create a constructor/record. The first argument should be the type of field, the second should be a list of fields constructed originally defined by := or :=+. This operation is not type safe, and may raise an exception at runtime if any field has the wrong type or label. | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Lift a pure value to an annotation. | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Re-exported for convenience | |||||||||||||||||||||||||||||||||||||||
Provides a few opaque types (for writing type signatures), verbosity control, default values with def and the Data/Typeable type classes. | |||||||||||||||||||||||||||||||||||||||
module System.Console.CmdArgs.Verbosity | |||||||||||||||||||||||||||||||||||||||
module System.Console.CmdArgs.Default | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Produced by Haddock version 2.6.0 |