UI.hs

{-|
    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}
-}
module System.Console.CmdArgs.Implicit.UI where

import System.Console.CmdArgs.Implicit.Ann
import Data.Typeable


-- | 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"}
opt :: (Show a, Typeable a) => a -> Ann
opt x = FlagOptional $ case cast x of
    Just y -> y
    _ -> show x

-- | 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
typ :: String -> Ann
typ = FlagType

-- | Flag: \"Users must give a file for this flag's value.\"
--
--   Alias for @'typ' "FILE"@.
typFile :: Ann
typFile = typ "FILE"

-- | Flag: \"Users must give a directory for this flag's value.\"
--
--   Alias for @'typ' "DIR"@.
typDir :: Ann
typDir = typ "DIR"


-- | Flag/Mode: \"The help message is ...\"
--
--   Descriptive text used in the help output.
--
-- > {hello = def &= help "Help message"}
-- >   -h --hello=VALUE      Help message
help :: String -> Ann
help = Help

{-
-- | Flag: Specify group membership for this flag
--
-- > {str = def &= group "Repository Management"
-- >   ---- Repository Management ----
-- >   -s --str=VALUE
group :: String -> Ann
group = FldGroup
-}

-- | Flag: \"Use this flag name for this field.\"
--
--   Add flags which trigger this option.
--
-- > {hello = def &= name "foo"}
-- >   -h --hello --foo=VALUE
name :: String -> Ann
name = Name

-- | Flag: \"Put non-flag arguments here.\"
--
--   All argument flags not captured by 'argPos' are returned by 'args'.
--
-- > {hello = def &= args}
args :: Ann
args = FlagArgs

-- | 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}
argPos :: Int -> Ann
argPos = FlagArgPos


-- | 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
groupname :: String -> Ann
groupname = GroupName


-- | 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"]
details :: [String] -> Ann
details = ModeHelpSuffix

-- | 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@. If the string contains a
--   version number component will also provide @--numeric-version@.
--
-- > Sample{..} &= summary "CmdArgs v0.0, (C) Neil Mitchell 1981"
summary :: String -> Ann
summary = ProgSummary


-- | 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{..}]
auto :: Ann
auto = ModeDefault


-- | 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"
program :: String -> Ann
program = ProgProgram


-- | 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
explicit :: Ann
explicit = Explicit


-- | 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
ignore :: Ann
ignore = Ignore


-- | Modes: \"My program needs verbosity flags.\"
--
--   Add @--verbose@ and @--quiet@ flags.
verbosity :: Ann
verbosity = ProgVerbosity


-- | Modes: \"Customise the help argument.\"
--
--   Add extra options to a help argument, such as 'help', 'name', 'ignore' or 'explicit'.
--
-- > Sample{..} &= helpArg [explicit, name "h"]
helpArg :: [Ann] -> Ann
helpArg = ProgHelpArg


-- | Modes: \"Customise the version argument.\"
--
--   Add extra options to a version argument, such as 'help', 'name', 'ignore', 'summary' or 'explicit'.
--
-- > Sample{..} &= versionArg [ignore]
versionArg :: [Ann] -> Ann
versionArg = ProgVersionArg

-- | 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]
verbosityArgs :: [Ann] -> [Ann] -> Ann
verbosityArgs = ProgVerbosityArgs


-- | Program: \"Turn off \@ expansion.\"
--
--   Usually arguments starting with \@ are treated as a file containing
--   a set of arguments. This annotation turns off that behaviour.
--
-- > Sample{..} &= noAtExpand
noAtExpand :: Ann
noAtExpand = ProgNoAtExpand