cmdargs

System.Console.CmdArgs.Implicit.UI

Description

This module describes the attributes that can be specified on flags and modes.

Many attributes have examples specified on the following data type:

 data Sample = Sample {hello :: String}

Synopsis

Documentation

opt :: (Show a, Typeable a) => a -> Ann

Flag: "I want users to be able to omit the value associated with 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)

Note that all flags in CmdArgs are optional, and if omitted will use their default value. Those annotated with opt also allow the flag to be present without an associated value. As an example:

 {hello = "DEFAULT" &= opt "OPTIONAL"}
 $ main
 {hello = "DEFAULT"}
 $ main --hello
 {hello = "OPTIONAL"}
 $ main --hello=VALUE
 {hello = "VALUE"}

typ :: String -> Ann

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

typFile :: Ann

Flag: "Users must give a file for this flag's value."

Alias for typ FILE.

typDir :: Ann

Flag: "Users must give a directory for this flag's value."

Alias for typ DIR.

help :: String -> Ann

Flag/Mode: "The help message is ..."

Descriptive text used in the help output.

 {hello = def &= help "Help message"}
   -h --hello=VALUE      Help message

name :: String -> Ann

Flag: "Use this flag name for this field."

Add flags which trigger this option.

 {hello = def &= name "foo"}
   -h --hello --foo=VALUE

args :: Ann

Flag: "Put non-flag arguments here."

 {hello = def &= args}

argPos :: Int -> Ann

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}

groupname :: String -> Ann

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

details :: [String] -> Ann

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"]

summary :: String -> Ann

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"

auto :: Ann

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{..}]

program :: String -> Ann

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"

explicit :: Ann

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

ignore :: Ann

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

verbosity :: Ann

Modes: "My program needs verbosity flags."

Add --verbose and --quiet flags.

helpArg :: [Ann] -> Ann

Modes: "Customise the help argument."

Add extra options to a help argument, such as help, name, ignore or explicit.

 Sample{..} &= helpArg [explicit, name "h"]

versionArg :: [Ann] -> Ann

Modes: "Customise the version argument."

Add extra options to a version argument, such as help, name, ignore, summary or explicit.

 Sample{..} &= versionArg [ignore]

verbosityArgs :: [Ann] -> [Ann] -> Ann

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]