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

- opt :: (Show a, Typeable a) => a -> Ann
- typ :: String -> Ann
- typFile :: Ann
- typDir :: Ann
- help :: String -> Ann
- name :: String -> Ann
- args :: Ann
- argPos :: Int -> Ann
- groupname :: String -> Ann
- details :: [String] -> Ann
- summary :: String -> Ann
- auto :: Ann
- program :: String -> Ann
- explicit :: Ann
- ignore :: Ann
- verbosity :: Ann
- helpArg :: [Ann] -> Ann
- versionArg :: [Ann] -> Ann
- verbosityArgs :: [Ann] -> [Ann] -> Ann

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