content: {-|
      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
  