-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | This library provides an easy way to define command line parsers. Most
--   users will want to use the <a>System.Console.CmdArgs.Implicit</a>
--   module, whose documentation contains an example.
--   
--   <ul>
--   <li><a>System.Console.CmdArgs.Explicit</a> provides a way to write
--   command line parsers for both single mode programs (most programs) and
--   multiple mode programs (e.g. darcs or cabal). Parsers are defined by
--   constructing a data structure.</li>
--   <li><a>System.Console.CmdArgs.Implicit</a> provides a way to concisely
--   define command line parsers, up to three times shorter than getopt.
--   These parsers are translated into the Explicit data type.</li>
--   <li><a>System.Console.CmdArgs.GetOpt</a> provides a wrapper allowing
--   compatiblity with existing getopt parsers, mapping to the Explicit
--   data type.</li>
--   </ul>
--   
--   For a general reference on what command line flags are commonly used,
--   see <a>http://www.faqs.org/docs/artu/ch10s05.html</a>.
@package cmdargs
@version 0.10.22


-- | This module captures annotations on a value, and builds a
--   <a>Capture</a> value. This module has two ways of writing annotations:
--   
--   <i>Impure</i>: The impure method of writing annotations is susceptible
--   to over-optimisation by GHC - sometimes <tt>{-# OPTIONS_GHC -fno-cse
--   #-}</tt> will be required.
--   
--   <i>Pure</i>: The pure method is more verbose, and lacks some type
--   safety.
--   
--   As an example of the two styles:
--   
--   <pre>
--   data Foo = Foo {foo :: Int, bar :: Int}
--   </pre>
--   
--   <pre>
--   impure = <a>capture</a> $ Foo {foo = 12, bar = <a>many</a> [1 <a>&amp;=</a> "inner", 2]} <a>&amp;=</a> "top"
--   </pre>
--   
--   <pre>
--   pure = <a>capture_</a> $ <a>record</a> Foo{} [foo := 12, bar :=+ [<a>atom</a> 1 <a>+=</a> "inner", <a>atom</a> 2]] <a>+=</a> "top"
--   </pre>
--   
--   Both evaluate to:
--   
--   <pre>
--   Capture (Ann "top") (Ctor (Foo 12 1) [Value 12, Many [Ann "inner" (Value 1), Value 2]]
--   </pre>
module System.Console.CmdArgs.Annotate

-- | The result of capturing some annotations.
data Capture ann

-- | Many values collapsed (<a>many</a> or <a>many_</a>)
Many :: [Capture ann] -> Capture ann

-- | An annotation attached to a value (<a>&amp;=</a> or <a>+=</a>)
Ann :: ann -> Capture ann -> Capture ann

-- | A value (just a value, or <a>atom</a>)
Value :: Any -> Capture ann

-- | A missing field (a <a>RecConError</a> exception, or missing from
--   <a>record</a>)
Missing :: Any -> Capture ann

-- | A constructor (a constructor, or <a>record</a>)
Ctor :: Any -> [Capture ann] -> Capture ann

-- | Any value, with a Data dictionary.
data Any
Any :: a -> Any

-- | Return the value inside a capture.
fromCapture :: Capture ann -> Any

-- | Remove all Missing values by using any previous instances as default
--   values
defaultMissing :: Capture ann -> Capture ann

-- | Capture a value. Note that if the value is evaluated more than once
--   the result may be different, i.e.
--   
--   <pre>
--   capture x /= capture x
--   </pre>
capture :: (Data val, Data ann) => val -> Capture ann

-- | Collapse multiple values in to one.
many :: Data val => [val] -> val

-- | Add an annotation to a value.
--   
--   It is recommended that anyone making use of this function redefine it
--   with a more restrictive type signature to control the type of the
--   annotation (the second argument). Any redefinitions of this function
--   should add an INLINE pragma, to reduce the chance of incorrect
--   optimisations.
(&=) :: (Data val, Data ann) => val -> ann -> val
infixl 2 &=

-- | Capture the annotations from an annotated value.
capture_ :: Show a => Annotate a -> Capture a

-- | Collapse many annotated values in to one.
many_ :: [Annotate a] -> Annotate a

-- | Add an annotation to a value.
(+=) :: Annotate ann -> ann -> Annotate ann
infixl 2 +=

-- | Lift a pure value to an annotation.
atom :: Data val => val -> Annotate ann

-- | 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 <tt>:=</tt> or <tt>:=+</tt>.
--   
--   This operation is not type safe, and may raise an exception at runtime
--   if any field has the wrong type or label.
record :: Data a => a -> [Annotate ann] -> Annotate ann

-- | This type represents an annotated value. The type of the underlying
--   value is not specified.
data Annotate ann

-- | Construct a field, <tt>fieldname := value</tt>.
(:=) :: (c -> f) -> f -> Annotate ann

-- | Add annotations to a field.
(:=+) :: (c -> f) -> [Annotate ann] -> Annotate ann
infix 3 :=
instance GHC.Internal.Exception.Type.Exception System.Console.CmdArgs.Annotate.ExceptionInt
instance GHC.Internal.Base.Functor System.Console.CmdArgs.Annotate.Capture
instance GHC.Internal.Show.Show ann => GHC.Internal.Show.Show (System.Console.CmdArgs.Annotate.Capture ann)
instance GHC.Internal.Show.Show System.Console.CmdArgs.Annotate.ExceptionInt


-- | This module provides default values for many types. To use the default
--   value simply write <a>def</a>.
module System.Console.CmdArgs.Default

-- | Class for default values.
class Default a

-- | Provide a default value, such as <tt>()</tt>, <tt>False</tt>,
--   <tt>0</tt>, <tt>[]</tt>, <tt>Nothing</tt>.
def :: Default a => a
instance System.Console.CmdArgs.Default.Default GHC.Types.Bool
instance System.Console.CmdArgs.Default.Default GHC.Types.Double
instance System.Console.CmdArgs.Default.Default GHC.Types.Float
instance System.Console.CmdArgs.Default.Default GHC.Types.Int
instance System.Console.CmdArgs.Default.Default GHC.Internal.Int.Int16
instance System.Console.CmdArgs.Default.Default GHC.Internal.Int.Int32
instance System.Console.CmdArgs.Default.Default GHC.Internal.Int.Int64
instance System.Console.CmdArgs.Default.Default GHC.Internal.Int.Int8
instance System.Console.CmdArgs.Default.Default GHC.Num.Integer.Integer
instance System.Console.CmdArgs.Default.Default [a]
instance System.Console.CmdArgs.Default.Default (GHC.Internal.Maybe.Maybe a)
instance (System.Console.CmdArgs.Default.Default a1, System.Console.CmdArgs.Default.Default a2, System.Console.CmdArgs.Default.Default a3, System.Console.CmdArgs.Default.Default a4, System.Console.CmdArgs.Default.Default a5, System.Console.CmdArgs.Default.Default a6, System.Console.CmdArgs.Default.Default a7, System.Console.CmdArgs.Default.Default a8, System.Console.CmdArgs.Default.Default a9, System.Console.CmdArgs.Default.Default a10) => System.Console.CmdArgs.Default.Default (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10)
instance (System.Console.CmdArgs.Default.Default a1, System.Console.CmdArgs.Default.Default a2) => System.Console.CmdArgs.Default.Default (a1, a2)
instance (System.Console.CmdArgs.Default.Default a1, System.Console.CmdArgs.Default.Default a2, System.Console.CmdArgs.Default.Default a3) => System.Console.CmdArgs.Default.Default (a1, a2, a3)
instance (System.Console.CmdArgs.Default.Default a1, System.Console.CmdArgs.Default.Default a2, System.Console.CmdArgs.Default.Default a3, System.Console.CmdArgs.Default.Default a4) => System.Console.CmdArgs.Default.Default (a1, a2, a3, a4)
instance (System.Console.CmdArgs.Default.Default a1, System.Console.CmdArgs.Default.Default a2, System.Console.CmdArgs.Default.Default a3, System.Console.CmdArgs.Default.Default a4, System.Console.CmdArgs.Default.Default a5) => System.Console.CmdArgs.Default.Default (a1, a2, a3, a4, a5)
instance (System.Console.CmdArgs.Default.Default a1, System.Console.CmdArgs.Default.Default a2, System.Console.CmdArgs.Default.Default a3, System.Console.CmdArgs.Default.Default a4, System.Console.CmdArgs.Default.Default a5, System.Console.CmdArgs.Default.Default a6) => System.Console.CmdArgs.Default.Default (a1, a2, a3, a4, a5, a6)
instance (System.Console.CmdArgs.Default.Default a1, System.Console.CmdArgs.Default.Default a2, System.Console.CmdArgs.Default.Default a3, System.Console.CmdArgs.Default.Default a4, System.Console.CmdArgs.Default.Default a5, System.Console.CmdArgs.Default.Default a6, System.Console.CmdArgs.Default.Default a7) => System.Console.CmdArgs.Default.Default (a1, a2, a3, a4, a5, a6, a7)
instance (System.Console.CmdArgs.Default.Default a1, System.Console.CmdArgs.Default.Default a2, System.Console.CmdArgs.Default.Default a3, System.Console.CmdArgs.Default.Default a4, System.Console.CmdArgs.Default.Default a5, System.Console.CmdArgs.Default.Default a6, System.Console.CmdArgs.Default.Default a7, System.Console.CmdArgs.Default.Default a8) => System.Console.CmdArgs.Default.Default (a1, a2, a3, a4, a5, a6, a7, a8)
instance (System.Console.CmdArgs.Default.Default a1, System.Console.CmdArgs.Default.Default a2, System.Console.CmdArgs.Default.Default a3, System.Console.CmdArgs.Default.Default a4, System.Console.CmdArgs.Default.Default a5, System.Console.CmdArgs.Default.Default a6, System.Console.CmdArgs.Default.Default a7, System.Console.CmdArgs.Default.Default a8, System.Console.CmdArgs.Default.Default a9) => System.Console.CmdArgs.Default.Default (a1, a2, a3, a4, a5, a6, a7, a8, a9)
instance System.Console.CmdArgs.Default.Default ()
instance System.Console.CmdArgs.Default.Default GHC.Types.Word
instance System.Console.CmdArgs.Default.Default GHC.Internal.Word.Word16
instance System.Console.CmdArgs.Default.Default GHC.Internal.Word.Word32
instance System.Console.CmdArgs.Default.Default GHC.Internal.Word.Word64
instance System.Console.CmdArgs.Default.Default GHC.Internal.Word.Word8


-- | Module for implementing CmdArgs helpers. A CmdArgs helper is an
--   external program, that helps a user construct the command line
--   arguments. To use a helper set the environment variable
--   <tt>$CMDARGS_HELPER</tt> (or
--   <tt>$CMDARGS_HELPER_<i>YOURPROGRAM</i></tt>) to one of:
--   
--   <ul>
--   <li><tt>echo <i>foo</i></tt> will cause <tt><i>foo</i></tt> to be used
--   as the command arguments.</li>
--   <li><tt>cmdargs-browser</tt> will cause a web browser to appear to
--   help entering the arguments. For this command to work, you will need
--   to install the <tt>cmdargs-browser</tt> package:
--   <a>http://hackage.haskell.org/package/cmdargs-browser</a></li>
--   </ul>
module System.Console.CmdArgs.Helper

-- | Run a remote command line entry.
execute :: String -> Mode a -> [String] -> IO (Either String [String])

-- | Unknown value, representing the values stored within the <a>Mode</a>
--   structure. While the values are not observable, they behave
--   identically to the original values.
data Unknown

-- | Receive information about the mode to display.
receive :: IO (Mode Unknown)

-- | Send a reply with either an error, or a list of flags to use. This
--   function exits the helper program.
reply :: Either String [String] -> IO ()

-- | Send a comment which will be displayed on the calling console, mainly
--   useful for debugging.
comment :: String -> IO ()
instance System.Console.CmdArgs.Helper.Packer a => System.Console.CmdArgs.Helper.Packer (System.Console.CmdArgs.Explicit.Type.Arg a)
instance System.Console.CmdArgs.Helper.Packer GHC.Types.Bool
instance System.Console.CmdArgs.Helper.Packer GHC.Types.Char
instance (System.Console.CmdArgs.Helper.Packer a, System.Console.CmdArgs.Helper.Packer b) => System.Console.CmdArgs.Helper.Packer (GHC.Internal.Data.Either.Either a b)
instance (System.Console.CmdArgs.Helper.Packer a, System.Console.CmdArgs.Helper.Packer b) => System.Console.CmdArgs.Helper.Packer (a -> b)
instance System.Console.CmdArgs.Helper.Packer a => System.Console.CmdArgs.Helper.Packer (System.Console.CmdArgs.Explicit.Type.Flag a)
instance System.Console.CmdArgs.Helper.Packer System.Console.CmdArgs.Explicit.Type.FlagInfo
instance System.Console.CmdArgs.Helper.Packer a => System.Console.CmdArgs.Helper.Packer (System.Console.CmdArgs.Explicit.Type.Group a)
instance System.Console.CmdArgs.Helper.Packer GHC.Types.Int
instance System.Console.CmdArgs.Helper.Packer a => System.Console.CmdArgs.Helper.Packer [a]
instance System.Console.CmdArgs.Helper.Packer a => System.Console.CmdArgs.Helper.Packer (GHC.Internal.Maybe.Maybe a)
instance System.Console.CmdArgs.Helper.Packer a => System.Console.CmdArgs.Helper.Packer (System.Console.CmdArgs.Explicit.Type.Mode a)
instance (System.Console.CmdArgs.Helper.Packer a, System.Console.CmdArgs.Helper.Packer b) => System.Console.CmdArgs.Helper.Packer (a, b)
instance System.Console.CmdArgs.Helper.Packer System.Console.CmdArgs.Helper.Value
instance GHC.Internal.Read.Read (System.Console.CmdArgs.Helper.NoShow a)
instance GHC.Internal.Read.Read System.Console.CmdArgs.Helper.Pack
instance GHC.Internal.Show.Show (System.Console.CmdArgs.Helper.NoShow a)
instance GHC.Internal.Show.Show System.Console.CmdArgs.Helper.Pack


-- | A module to represent text with very basic formatting. Values are of
--   type [<a>Text</a>] and shown with <a>showText</a>.
--   
--   As an example of the formatting:
--   
--   <pre>
--   [Line "Cooking for hungry people."
--   ,Line "Welcome to my cookery recipe program, I sure hope you enjoy using it!"
--   ,Line ""
--   ,Cols ["Omlette","  A tasty eggy treat."]
--   ,Cols ["  -m"," --mushrooms","  Some mushrooms, or in fact any other ingredients you have in the cupboards"]
--   ,Cols ["  -e"," --eggs", "  But always you need eggs"]
--   ,Line ""
--   ,Cols ["Spagetti Bolognaise", "  An Italian delight."]
--   ,Cols ["  -s"," --spagetti","  The first word in the name"]
--   ,Cols ["  -b"," --bolognaise","  The second word in the name"]
--   ,Cols ["  -d"," --dolmio","  The magic ingredient!"]
--   ,Line ""
--   ,Line "    The author of this program explicitly disclaims any liability for poisoning people who get their recipes off the internet."]
--   </pre>
--   
--   With <tt>putStrLn (<a>showText</a> (<a>Wrap</a> 50) demo)</tt> gives:
--   
--   <pre>
--   Cooking for hungry people.
--   Welcome to my cookery recipe program, I sure hope
--   you enjoy using it!
--   
--   Omlette              A tasty eggy treat.
--     -m --mushrooms   Some mushrooms, or in fact
--                      any other ingredients you have
--                      in the cupboards
--     -e --eggs        But always you need eggs
--   
--   Spagetti Bolognaise  An Italian delight.
--     -s --spagetti    The first word in the name
--     -b --bolognaise  The second word in the name
--     -d --dolmio      The magic ingredient!
--   
--       The author of this program explicitly
--       disclaims any liability for poisoning people
--       who get their recipes off the internet.
--   </pre>
module System.Console.CmdArgs.Text

-- | How to output the text.
data TextFormat

-- | Display as HTML.
HTML :: TextFormat

-- | Display as text wrapped at a certain width (see <a>defaultWrap</a>).
Wrap :: Int -> TextFormat

-- | Wrap with the default width of 80 characters.
defaultWrap :: TextFormat

-- | The data type representing some text, typically used as
--   <tt>[Text]</tt>. The formatting is described by:
--   
--   <ul>
--   <li><a>Line</a> values represent a paragraph of text, and may be
--   wrapped depending on the <a>TextFormat</a>. If a <a>Line</a> value is
--   wrapped then all leading space will be treated as an indent.</li>
--   <li><a>Cols</a> values represent columns of text. Within any
--   <tt>[Text]</tt> all columns of the same length are grouped in tabs,
--   with the final column being wrapped if necessary. All columns are
--   placed adjacent with no space between them - for this reason most
--   columns will start with a space.</li>
--   </ul>
data Text
Line :: String -> Text
Cols :: [String] -> Text

-- | Show some text using the given formatting.
showText :: TextFormat -> [Text] -> String
instance System.Console.CmdArgs.Default.Default System.Console.CmdArgs.Text.TextFormat
instance GHC.Classes.Eq System.Console.CmdArgs.Text.TextFormat
instance GHC.Classes.Ord System.Console.CmdArgs.Text.TextFormat
instance GHC.Internal.Read.Read System.Console.CmdArgs.Text.TextFormat
instance GHC.Internal.Show.Show System.Console.CmdArgs.Text.Text
instance GHC.Internal.Show.Show System.Console.CmdArgs.Text.TextFormat


-- | A module to deal with verbosity, how 'chatty' a program should be.
--   This module defines the <a>Verbosity</a> data type, along with
--   functions for manipulating a global verbosity value.
module System.Console.CmdArgs.Verbosity

-- | The verbosity data type
data Verbosity

-- | Only output essential messages (typically errors)
Quiet :: Verbosity

-- | Output normal messages (typically errors and warnings)
Normal :: Verbosity

-- | Output lots of messages (typically errors, warnings and status
--   updates)
Loud :: Verbosity

-- | Set the global verbosity.
setVerbosity :: Verbosity -> IO ()

-- | Get the global verbosity. Initially <tt>Normal</tt> before any calls
--   to <a>setVerbosity</a>.
getVerbosity :: IO Verbosity

-- | Used to test if warnings should be output to the user. <tt>True</tt>
--   if the verbosity is set to <a>Normal</a> or <a>Loud</a> (when
--   <tt>--quiet</tt> is <i>not</i> specified).
isNormal :: IO Bool

-- | Used to test if status updates should be output to the user.
--   <tt>True</tt> if the verbosity is set to <a>Loud</a> (when
--   <tt>--verbose</tt> is specified).
isLoud :: IO Bool

-- | An action to perform if the verbosity is normal or higher, based on
--   <a>isNormal</a>.
whenNormal :: IO () -> IO ()

-- | An action to perform if the verbosity is loud, based on <a>isLoud</a>.
whenLoud :: IO () -> IO ()
instance GHC.Internal.Enum.Bounded System.Console.CmdArgs.Verbosity.Verbosity
instance GHC.Internal.Data.Data.Data System.Console.CmdArgs.Verbosity.Verbosity
instance GHC.Internal.Enum.Enum System.Console.CmdArgs.Verbosity.Verbosity
instance GHC.Classes.Eq System.Console.CmdArgs.Verbosity.Verbosity
instance GHC.Classes.Ord System.Console.CmdArgs.Verbosity.Verbosity
instance GHC.Internal.Read.Read System.Console.CmdArgs.Verbosity.Verbosity
instance GHC.Internal.Show.Show System.Console.CmdArgs.Verbosity.Verbosity


-- | This module constructs command lines. You may either use the helper
--   functions (<a>flagNone</a>, <a>flagOpt</a>, <a>mode</a> etc.) or
--   construct the type directly. These types are intended to give all the
--   necessary power to the person constructing a command line parser.
--   
--   For people constructing simpler command line parsers, the module
--   <a>System.Console.CmdArgs.Implicit</a> may be more appropriate.
--   
--   As an example of a parser:
--   
--   <pre>
--   arguments :: <a>Mode</a> [(String,String)]
--   arguments = <a>mode</a> "explicit" [] "Explicit sample program" (<a>flagArg</a> (upd "file") "FILE")
--       [<a>flagOpt</a> "world" ["hello","h"] (upd "world") "WHO" "World argument"
--       ,<a>flagReq</a> ["greeting","g"] (upd "greeting") "MSG" "Greeting to give"
--       ,<a>flagHelpSimple</a> (("help",""):)]
--       where upd msg x v = Right $ (msg,x):v
--   
--   </pre>
--   
--   And this can be invoked by:
--   
--   <pre>
--   main = do
--       xs &lt;- <a>processArgs</a> arguments
--       if ("help","") `elem` xs then
--           print $ <a>helpText</a> [] <a>HelpFormatDefault</a> arguments
--        else
--           print xs
--   
--   </pre>
--   
--   <i>Groups</i>: The <a>Group</a> structure allows flags/modes to be
--   grouped for the purpose of displaying help. When processing command
--   lines, the group structure is ignored.
--   
--   <i>Modes</i>: The Explicit module allows multiple mode programs by
--   placing additional modes in <a>modeGroupModes</a>. Every mode is
--   allowed sub-modes, and thus multiple levels of mode may be created.
--   Given a mode <tt>x</tt> with sub-modes <tt>xs</tt>, if the first
--   argument corresponds to the name of a sub-mode, then that sub-mode
--   will be applied. If not, then the arguments will be processed by mode
--   <tt>x</tt>. Consequently, if you wish to force the user to explicitly
--   enter a mode, simply give sub-modes, and leave <a>modeArgs</a> as
--   <tt>Nothing</tt>. Alternatively, if you want one sub-mode to be
--   selected by default, place all it's flags both in the sub-mode and the
--   outer mode.
--   
--   <i>Parsing rules</i>: Command lines are parsed as per most GNU
--   programs. Short arguments single letter flags start with <tt>-</tt>,
--   longer flags start with <tt>--</tt>, and everything else is considered
--   an argument. Anything after <tt>--</tt> alone is considered to be an
--   argument. For example:
--   
--   <pre>
--   -f --flag argument1 -- --argument2
--   </pre>
--   
--   This command line passes one single letter flag (<tt>f</tt>), one
--   longer flag (<tt>flag</tt>) and two arguments (<tt>argument1</tt> and
--   <tt>--argument2</tt>).
module System.Console.CmdArgs.Explicit

-- | Process a list of flags (usually obtained from
--   <tt>getArgs</tt>/<tt>expandArgsAt</tt>) with a mode. Returns
--   <tt>Left</tt> and an error message if the command line fails to parse,
--   or <tt>Right</tt> and the associated value.
process :: Mode a -> [String] -> Either String a

-- | Process the flags obtained by <tt><a>getArgs</a></tt> and
--   <tt><a>expandArgsAt</a></tt> with a mode. Displays an error and exits
--   with failure if the command line fails to parse, or returns the
--   associated value. Implemented in terms of <a>process</a>. This
--   function makes use of the following environment variables:
--   
--   <ul>
--   <li><tt>$CMDARGS_COMPLETE</tt> - causes the program to produce
--   completions using <a>complete</a>, then exit. Completions are based on
--   the result of <a>getArgs</a>, the index of the current argument is
--   taken from <tt>$CMDARGS_COMPLETE</tt> (set it to <tt>-</tt> to
--   complete the last argument), and the index within that argument is
--   taken from <tt>$CMDARGS_COMPLETE_POS</tt> (if set).</li>
--   <li><tt>$CMDARGS_HELPER</tt>/<tt>$CMDARGS_HELPER_<i>PROG</i></tt> -
--   uses the helper mechanism for entering command line programs as
--   described in <a>System.Console.CmdArgs.Helper</a>.</li>
--   </ul>
processArgs :: Mode a -> IO a

-- | Process a list of flags (usually obtained from <tt><a>getArgs</a></tt>
--   and <tt><a>expandArgsAt</a></tt>) with a mode. Throws an error if the
--   command line fails to parse, or returns the associated value.
--   Implemeneted in terms of <a>process</a>. This function does not take
--   account of any environment variables that may be set (see
--   <a>processArgs</a>).
--   
--   If you are in <a>IO</a> you will probably get a better user experience
--   by calling <a>processValueIO</a>.
processValue :: Mode a -> [String] -> a

-- | Like <a>processValue</a> but on failure prints to stderr and exits the
--   program.
processValueIO :: Mode a -> [String] -> IO a

-- | Check that a mode is well formed.
checkMode :: Mode a -> Maybe String

-- | Create an argument flag, with an update function and the type of the
--   argument.
flagArg :: Update a -> FlagHelp -> Arg a

-- | Create a boolean flag, with a list of flag names, an update function
--   and some help text.
flagBool :: [Name] -> (Bool -> a -> a) -> Help -> Flag a

-- | Create a flag taking no argument value, with a list of flag names, an
--   update function and some help text.
flagNone :: [Name] -> (a -> a) -> Help -> Flag a

-- | Create a flag taking an optional argument value, with an optional
--   value, a list of flag names, an update function, the type of the
--   argument and some help text.
flagOpt :: String -> [Name] -> Update a -> FlagHelp -> Help -> Flag a

-- | Create a flag taking a required argument value, with a list of flag
--   names, an update function, the type of the argument and some help
--   text.
flagReq :: [Name] -> Update a -> FlagHelp -> Help -> Flag a

-- | Extract the value from inside a <a>FlagOpt</a> or <a>FlagOptRare</a>,
--   or raises an error.
fromFlagOpt :: FlagInfo -> String

-- | Convert a group into a list.
fromGroup :: Group a -> [a]

-- | Create a mode with a name, an initial value, some help text, a way of
--   processing arguments and a list of flags.
mode :: Name -> a -> Help -> Arg a -> [Flag a] -> Mode a

-- | Create an empty mode specifying only <a>modeValue</a>. All other
--   fields will usually be populated using record updates.
modeEmpty :: a -> Mode a

-- | Extract the flags from a <a>Mode</a>
modeFlags :: Mode a -> [Flag a]

-- | Extract the modes from a <a>Mode</a>
modeModes :: Mode a -> [Mode a]

-- | Create a list of modes, with a program name, an initial value, some
--   help text and the child modes.
modes :: String -> a -> Help -> [Mode a] -> Mode a

-- | Parse a boolean, accepts as True: true yes on enabled 1.
parseBool :: String -> Maybe Bool

-- | Restricted version of <a>remap</a> where the values are isomorphic.
remap2 :: Remap m => (a -> b) -> (b -> a) -> m a -> m b

-- | Version of <a>remap</a> for the <a>Update</a> type alias.
remapUpdate :: (a -> b) -> (b -> (a, a -> b)) -> Update a -> Update b

-- | Convert a list into a group, placing all fields in
--   <a>groupUnnamed</a>.
toGroup :: [a] -> Group a

-- | An unnamed argument. Anything not starting with <tt>-</tt> is
--   considered an argument, apart from <tt>"-"</tt> which is considered to
--   be the argument <tt>"-"</tt>, and any arguments following
--   <tt>"--"</tt>. For example:
--   
--   <pre>
--   programname arg1 -j - --foo arg3 -- -arg4 --arg5=1 arg6
--   </pre>
--   
--   Would have the arguments:
--   
--   <pre>
--   ["arg1","-","arg3","-arg4","--arg5=1","arg6"]
--   </pre>
data Arg a
Arg :: Update a -> FlagHelp -> Bool -> Arg a

-- | A way of processing the argument.
[argValue] :: Arg a -> Update a

-- | The type of data for the argument, i.e. FILE/DIR/EXT
[argType] :: Arg a -> FlagHelp

-- | Is at least one of these arguments required, the command line will
--   fail if none are set
[argRequire] :: Arg a -> Bool

-- | A flag, consisting of a list of flag names and other information.
data Flag a
Flag :: [Name] -> FlagInfo -> Update a -> FlagHelp -> Help -> Flag a

-- | The names for the flag.
[flagNames] :: Flag a -> [Name]

-- | Information about a flag's arguments.
[flagInfo] :: Flag a -> FlagInfo

-- | The way of processing a flag.
[flagValue] :: Flag a -> Update a

-- | The type of data for the flag argument, i.e. FILE/DIR/EXT
[flagType] :: Flag a -> FlagHelp

-- | The help message associated with this flag.
[flagHelp] :: Flag a -> Help

-- | The type of a flag, i.e. <tt>--foo=<i>TYPE</i></tt>.
type FlagHelp = String

-- | The <a>FlagInfo</a> type has the following meaning:
--   
--   <pre>
--                FlagReq     FlagOpt      FlagOptRare/FlagNone
--   -xfoo        -x=foo      -x=foo       -x -foo
--   -x foo       -x=foo      -x foo       -x foo
--   -x=foo       -x=foo      -x=foo       -x=foo
--   --xx foo     --xx=foo    --xx foo     --xx foo
--   --xx=foo     --xx=foo    --xx=foo     --xx=foo
--   </pre>
data FlagInfo

-- | Required argument
FlagReq :: FlagInfo

-- | Optional argument
FlagOpt :: String -> FlagInfo

-- | Optional argument that requires an = before the value
FlagOptRare :: String -> FlagInfo

-- | No argument
FlagNone :: FlagInfo

-- | A group of items (modes or flags). The items are treated as a list,
--   but the group structure is used when displaying the help message.
data Group a
Group :: [a] -> [a] -> [(Help, [a])] -> Group a

-- | Normal items.
[groupUnnamed] :: Group a -> [a]

-- | Items that are hidden (not displayed in the help message).
[groupHidden] :: Group a -> [a]

-- | Items that have been grouped, along with a description of each group.
[groupNamed] :: Group a -> [(Help, [a])]

-- | A help message that goes with either a flag or a mode.
type Help = String

-- | A mode. Do not use the <a>Mode</a> constructor directly, instead use
--   <a>mode</a> to construct the <a>Mode</a> and then record updates. Each
--   mode has three main features:
--   
--   <ul>
--   <li>A list of submodes (<a>modeGroupModes</a>)</li>
--   <li>A list of flags (<a>modeGroupFlags</a>)</li>
--   <li>Optionally an unnamed argument (<a>modeArgs</a>)</li>
--   </ul>
--   
--   To produce the help information for a mode, either use
--   <tt>helpText</tt> or <a>show</a>.
data Mode a
Mode :: Group (Mode a) -> [Name] -> a -> (a -> Either String a) -> (a -> Maybe [String]) -> Bool -> Help -> [String] -> ([Arg a], Maybe (Arg a)) -> Group (Flag a) -> Mode a

-- | The available sub-modes
[modeGroupModes] :: Mode a -> Group (Mode a)

-- | The names assigned to this mode (for the root mode, this name is used
--   as the program name)
[modeNames] :: Mode a -> [Name]

-- | Value to start with
[modeValue] :: Mode a -> a

-- | Check the value reprsented by a mode is correct, after applying all
--   flags
[modeCheck] :: Mode a -> a -> Either String a

-- | Given a value, try to generate the input arguments.
[modeReform] :: Mode a -> a -> Maybe [String]

-- | Expand <tt>@</tt> arguments with <tt>expandArgsAt</tt>, defaults to
--   <a>True</a>, only applied if using an <a>IO</a> processing function.
--   Only the root <a>Mode</a>s value will be used.
[modeExpandAt] :: Mode a -> Bool

-- | Help text
[modeHelp] :: Mode a -> Help

-- | A longer help suffix displayed after a mode
[modeHelpSuffix] :: Mode a -> [String]

-- | The unnamed arguments, a series of arguments, followed optionally by
--   one for all remaining slots
[modeArgs] :: Mode a -> ([Arg a], Maybe (Arg a))

-- | Groups of flags
[modeGroupFlags] :: Mode a -> Group (Flag a)

-- | A name, either the name of a flag (<tt>--<i>foo</i></tt>) or the name
--   of a mode.
type Name = String

-- | Like functor, but where the the argument isn't just covariant.
class Remap (m :: Type -> Type)

-- | Convert between two values.
remap :: Remap m => (a -> b) -> (b -> (a, a -> b)) -> m a -> m b

-- | A function to take a string, and a value, and either produce an error
--   message (<tt>Left</tt>), or a modified value (<tt>Right</tt>).
type Update a = String -> a -> Either String a

-- | Create a help flag triggered by <tt>-?</tt>/<tt>--help</tt>.
flagHelpSimple :: (a -> a) -> Flag a

-- | Create a help flag triggered by <tt>-?</tt>/<tt>--help</tt>. The user
--   may optionally modify help by specifying the format, such as:
--   
--   <pre>
--   --help=all          - help for all modes
--   --help=html         - help in HTML format
--   --help=100          - wrap the text at 100 characters
--   --help=100,one      - full text wrapped at 100 characters
--   </pre>
flagHelpFormat :: (HelpFormat -> TextFormat -> a -> a) -> Flag a

-- | Create a version flag triggered by <tt>-V</tt>/<tt>--version</tt>.
flagVersion :: (a -> a) -> Flag a

-- | Create a version flag triggered by <tt>--numeric-version</tt>.
flagNumericVersion :: (a -> a) -> Flag a

-- | Create verbosity flags triggered by <tt>-v</tt>/<tt>--verbose</tt> and
--   <tt>-q</tt>/<tt>--quiet</tt>
flagsVerbosity :: (Verbosity -> a -> a) -> [Flag a]

-- | Generate a help message from a mode. The first argument is a prefix,
--   which is prepended when not using <a>HelpFormatBash</a> or
--   <a>HelpFormatZsh</a>.
helpText :: [String] -> HelpFormat -> Mode a -> [Text]

-- | Specify the format to output the help.
data HelpFormat

-- | Equivalent to <a>HelpFormatAll</a> if there is not too much text,
--   otherwise <a>HelpFormatOne</a>.
HelpFormatDefault :: HelpFormat

-- | Display only the first mode.
HelpFormatOne :: HelpFormat

-- | Display all modes.
HelpFormatAll :: HelpFormat

-- | Bash completion information
HelpFormatBash :: HelpFormat

-- | Z shell completion information
HelpFormatZsh :: HelpFormat

-- | Expand <tt>@</tt> directives in a list of arguments, usually obtained
--   from <tt>getArgs</tt>. As an example, given the file <tt>test.txt</tt>
--   with the lines <tt>hello</tt> and <tt>world</tt>:
--   
--   <pre>
--   expandArgsAt ["@test.txt","!"] == ["hello","world","!"]
--   </pre>
--   
--   Any <tt>@</tt> directives in the files will be recursively expanded
--   (raising an error if there is infinite recursion).
--   
--   To supress <tt>@</tt> expansion, pass any <tt>@</tt> arguments after
--   <tt>--</tt>.
expandArgsAt :: [String] -> IO [String]

-- | Given a sequence of arguments, join them together in a manner that
--   could be used on the command line, giving preference to the Windows
--   <tt>cmd</tt> shell quoting conventions.
--   
--   For an alternative version, intended for actual running the result in
--   a shell, see "System.Process.showCommandForUser"
joinArgs :: [String] -> String

-- | Given a string, split into the available arguments. The inverse of
--   <a>joinArgs</a>.
splitArgs :: String -> [String]

-- | How to complete a command line option. The <a>Show</a> instance is
--   suitable for parsing from shell scripts.
data Complete

-- | Complete to a particular value
CompleteValue :: String -> Complete

-- | Complete to a prefix, and a file
CompleteFile :: String -> FilePath -> Complete

-- | Complete to a prefix, and a directory
CompleteDir :: String -> FilePath -> Complete

-- | Given a current state, return the set of commands you could type now,
--   in preference order.
complete :: Mode a -> [String] -> (Int, Int) -> [Complete]


-- | This module provides simple command line argument processing. The main
--   function of interest is <a>cmdArgs</a>. A simple example is:
--   
--   <pre>
--   data Sample = Sample {hello :: String} deriving (Show, Data, Typeable)
--   </pre>
--   
--   <pre>
--   sample = Sample{hello = <a>def</a> <a>&amp;=</a> <a>help</a> "World argument" <a>&amp;=</a> <a>opt</a> "world"}
--            <a>&amp;=</a> <a>summary</a> "Sample v1"
--   </pre>
--   
--   <pre>
--   main = print =&lt;&lt; <a>cmdArgs</a> sample
--   </pre>
--   
--   Attributes are used to control a number of behaviours:
--   
--   <ul>
--   <li>The help message: <a>help</a>, <a>typ</a>, <a>details</a>,
--   <a>summary</a>, <a>program</a>, <a>groupname</a></li>
--   <li>Flag behaviour: <a>opt</a>, <a>enum</a>, <a>verbosity</a>,
--   <a>ignore</a></li>
--   <li>Flag name assignment: <a>name</a>, <a>explicit</a></li>
--   <li>Controlling non-flag arguments: <a>args</a>, <a>argPos</a></li>
--   <li>multi-mode programs: <a>modes</a>, <a>auto</a></li>
--   </ul>
--   
--   <i>Supported Types</i>: Each field in the record must be one of the
--   supported atomic types (<tt>String</tt>, <tt>Int</tt>,
--   <tt>Integer</tt>, <tt>Float</tt>, <tt>Double</tt>, <tt>Bool</tt>, an
--   enumeration, a tuple of atomic types) or a list (<tt>[]</tt>) or
--   <tt>Maybe</tt> wrapping at atomic type.
--   
--   <i>Missing Fields</i>: If a field is shared by multiple modes, it may
--   be omitted in subsequent modes, and will default to the previous
--   value.
--   
--   <i>Purity</i>: 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:
--   
--   <pre>
--   sample = <a>cmdArgsMode</a> $ Sample{hello = ... -- as before
--   </pre>
--   
--   <pre>
--   main = print =&lt;&lt; <a>cmdArgsRun</a> sample
--   </pre>
--   
--   Even using this scheme, sometimes GHC's optimisations may share values
--   who have the same annotation. To disable sharing you may need to
--   specify <tt>{-# OPTIONS_GHC -fno-cse #-}</tt> in the module you define
--   the flags.
--   
--   <i>Pure annotations</i>: Alternatively, you may use pure annotations,
--   which are referentially transparent, but less type safe and more
--   verbose. The initial example may be written as:
--   
--   <tt>sample = <a>record</a> Sample{} [hello := <a>def</a> <a>+=</a>
--   <a>help</a> "World argument" <a>+=</a> <a>opt</a> "world"]</tt> <tt>
--   <a>+=</a> <a>summary</a> "Sample v1"</tt>
--   
--   <pre>
--   main = print =&lt;&lt; (cmdArgs_ sample :: IO Sample)
--   </pre>
--   
--   All the examples are written using impure annotations. To convert to
--   pure annotations follow the rules:
--   
--   <pre>
--   Ctor {field1 = value1 &amp;= ann1, field2 = value2} &amp;= ann2 ==&gt; record Ctor{} [field1 := value1 += ann1, field2 := value2] += ann2
--   Ctor (value1 &amp;= ann1) value2 &amp;= ann2 ==&gt; record Ctor{} [atom value1 += ann1, atom value2] += ann2
--   modes [Ctor1{...}, Ctor2{...}] ==&gt; modes_ [record Ctor1{} [...], record Ctor2{} [...]]
--   Ctor {field1 = enum [X &amp;= ann, Y]} ==&gt; record Ctor{} [enum_ field1 [atom X += ann, atom Y]]
--   </pre>
--   
--   If you are willing to use TemplateHaskell, you can write in the impure
--   syntax, but have your code automatically translated to the pure style.
--   For more details see <a>System.Console.CmdArgs.Quote</a>.
module System.Console.CmdArgs.Implicit

-- | Take impurely annotated records and run the corresponding command
--   line. Shortcut for <tt><a>cmdArgsRun</a> . <a>cmdArgsMode</a></tt>.
--   
--   To use <a>cmdArgs</a> with custom command line arguments see
--   <a>withArgs</a>.
cmdArgs :: Data a => a -> IO a

-- | Take impurely annotated records and turn them in to a <a>Mode</a>
--   value, that can make use of the <a>System.Console.CmdArgs.Explicit</a>
--   functions (i.e. <tt>process</tt>).
--   
--   Annotated records are impure, and will only contain annotations on
--   their first use. The result of this function is pure, and can be
--   reused.
cmdArgsMode :: Data a => a -> Mode (CmdArgs a)

-- | Run a Mode structure. This function reads the command line arguments
--   and then performs as follows:
--   
--   <ul>
--   <li>If invalid arguments are given, it will display the error message
--   and exit.</li>
--   <li>If <tt>--help</tt> is given, it will display the help message and
--   exit.</li>
--   <li>If <tt>--version</tt> is given, it will display the version and
--   exit.</li>
--   <li>In all other circumstances the program will return a value.</li>
--   <li>Additionally, if either <tt>--quiet</tt> or <tt>--verbose</tt> is
--   given (see <a>verbosity</a>) it will set the verbosity (see
--   <a>setVerbosity</a>).</li>
--   </ul>
cmdArgsRun :: Mode (CmdArgs a) -> IO a

-- | Take purely annotated records and run the corresponding command line.
--   Shortcut for <tt><a>cmdArgsRun</a> . <a>cmdArgsMode_</a></tt>.
--   
--   To use <a>cmdArgs_</a> with custom command line arguments see
--   <a>withArgs</a>.
cmdArgs_ :: Data a => Annotate Ann -> IO a

-- | Take purely annotated records and turn them in to a <a>Mode</a> value,
--   that can make use of the <a>System.Console.CmdArgs.Explicit</a>
--   functions (i.e. <tt>process</tt>).
cmdArgsMode_ :: Data a => Annotate Ann -> Mode (CmdArgs a)

-- | Perform the necessary actions dictated by a <a>CmdArgs</a> structure.
--   
--   <ul>
--   <li>If <a>cmdArgsHelp</a> is <tt>Just</tt>, it will display the help
--   message and exit.</li>
--   <li>If <a>cmdArgsVersion</a> is <tt>Just</tt>, it will display the
--   version and exit.</li>
--   <li>In all other circumstances it will return a value.</li>
--   <li>Additionally, if <a>cmdArgsVerbosity</a> is <tt>Just</tt> (see
--   <a>verbosity</a>) it will set the verbosity (see
--   <a>setVerbosity</a>).</li>
--   </ul>
cmdArgsApply :: CmdArgs a -> IO a

-- | A structure to store the additional data relating to <tt>--help</tt>,
--   <tt>--version</tt>, <tt>--quiet</tt> and <tt>--verbose</tt>.
data CmdArgs a
CmdArgs :: a -> Maybe String -> Maybe String -> Maybe Verbosity -> CmdArgsPrivate -> CmdArgs a

-- | The underlying value being wrapped.
[cmdArgsValue] :: CmdArgs a -> a

-- | <tt>Just</tt> if <tt>--help</tt> is given, then gives the help message
--   for display, including a trailing newline.
[cmdArgsHelp] :: CmdArgs a -> Maybe String

-- | <tt>Just</tt> if <tt>--version</tt> is given, then gives the version
--   message for display, including a trailing newline.
[cmdArgsVersion] :: CmdArgs a -> Maybe String

-- | <tt>Just</tt> if <tt>--quiet</tt> or <tt>--verbose</tt> is given, then
--   gives the verbosity to use.
[cmdArgsVerbosity] :: CmdArgs a -> Maybe Verbosity

-- | Private: Only exported due to Haddock limitations.
[cmdArgsPrivate] :: CmdArgs a -> CmdArgsPrivate

-- | Flag: "Put the nth non-flag argument here."
--   
--   This field should be used to store a particular argument position
--   (0-based).
--   
--   <pre>
--   {hello = def &amp;= argPos 0}
--   </pre>
argPos :: Int -> Ann

-- | Flag: "Put non-flag arguments here."
--   
--   All argument flags not captured by <a>argPos</a> are returned by
--   <a>args</a>.
--   
--   <pre>
--   {hello = def &amp;= args}
--   </pre>
args :: 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.
--   
--   <pre>
--   modes [Mode1{..}, Mode2{..} &amp;= auto, Mode3{..}]
--   </pre>
auto :: Ann

-- | Mode: "A longer description of this mode is ..."
--   
--   Suffix to be added to the help message.
--   
--   <pre>
--   Sample{..} &amp;= details ["More details on the website www.example.org"]
--   </pre>
details :: [String] -> 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 <tt>flag</tt>.
--   
--   <pre>
--   {hello = def &amp;= explicit &amp;= name "foo"}
--     --foo=VALUE
--   </pre>
explicit :: 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
--   <tt>groupname</tt>.
--   
--   <pre>
--   {hello = def &amp;= groupname "Welcomes"}
--   Welcomes
--     -h --hello=VALUE
--   </pre>
groupname :: String -> Ann

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

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

-- | Flag/Mode: "Ignore this field, don't let the user set it."
--   
--   A mode or field is not dealt with by CmdArgs.
--   
--   <pre>
--   {hello = def, extra = def &amp;= ignore}
--     --hello=VALUE
--   </pre>
ignore :: Ann

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

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

-- | Flag: "I want users to be able to omit the value associated with this
--   flag."
--   
--   Make the value of a flag optional. If <tt>--flag</tt> is given, it
--   will be treated as <tt>--flag=<i>this_argument</i></tt>.
--   
--   <pre>
--   {hello = def &amp;= opt "foo"}
--     -h --hello[=VALUE]    (default=foo)
--   </pre>
--   
--   Note that all flags in CmdArgs are optional, and if omitted will use
--   their default value. Those annotated with <tt>opt</tt> also allow the
--   flag to be present without an associated value. As an example:
--   
--   <pre>
--   {hello = "DEFAULT" &amp;= opt "OPTIONAL"}
--   </pre>
--   
--   <pre>
--   $ main
--   {hello = "DEFAULT"}
--   $ main --hello
--   {hello = "OPTIONAL"}
--   $ main --hello=VALUE
--   {hello = "VALUE"}
--   </pre>
opt :: (Show a, Typeable a) => a -> 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.
--   
--   <pre>
--   Sample{..} &amp;= program "sample"
--   </pre>
program :: String -> Ann

-- | Modes: "My program name/version/copyright is ..."
--   
--   One line summary of the entire program, the first line of
--   <tt>--help</tt> and the only line of <tt>--version</tt>. If the string
--   contains a version number component will also provide
--   <tt>--numeric-version</tt>.
--   
--   <pre>
--   Sample{..} &amp;= summary "CmdArgs v0.0, (C) Neil Mitchell 1981"
--   </pre>
summary :: 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 <tt>FILE</tt> (<a>typFile</a>)
--   or <tt>DIR</tt> (<a>typDir</a>).
--   
--   <pre>
--   {hello = def &amp;= typ "MESSAGE"}
--     -h --hello=MESSAGE
--   </pre>
typ :: String -> Ann

-- | Flag: "Users must give a directory for this flag's value."
--   
--   Alias for <tt><a>typ</a> <a>DIR</a></tt>.
typDir :: Ann

-- | Flag: "Users must give a file for this flag's value."
--   
--   Alias for <tt><a>typ</a> <a>FILE</a></tt>.
typFile :: Ann

-- | Modes: "My program needs verbosity flags."
--   
--   Add <tt>--verbose</tt> and <tt>--quiet</tt> flags.
verbosity :: Ann

-- | Modes: "Customise the verbosity arguments."
--   
--   Add extra options to a verbosity arguments (<tt>--verbose</tt> and
--   <tt>--quiet</tt>), such as <a>help</a>, <a>name</a>, <a>ignore</a> or
--   <a>explicit</a>. The verbose options come first, followed by the quiet
--   options.
--   
--   <pre>
--   Sample{..} &amp;= verbosityArgs [ignore] [name "silent", explicit]
--   </pre>
verbosityArgs :: [Ann] -> [Ann] -> Ann

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

-- | 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.
(&=) :: Data val => val -> Ann -> val

-- | 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 <a>auto</a>.
--   
--   <pre>
--   data Modes = Mode1 | Mode2 | Mode3 deriving Data
--   cmdArgs $ modes [Mode1,Mode2,Mode3]
--   </pre>
modes :: Data val => [val] -> val

-- | 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. The first
--   element in the list is used as the value of the field.
--   
--   <pre>
--   data State = On | Off deriving Data
--   data Mode = Mode {state :: State}
--   cmdArgs $ Mode {state = enum [On &amp;= help "Turn on",Off &amp;= help "Turn off"]}
--     --on   Turn on
--     --off  Turn off
--   </pre>
--   
--   This annotation can be used to allow multiple flags within a field:
--   
--   <pre>
--   data Mode = Mode {state :: [State]}
--   cmdArgs $ Mode {state = enum [[] &amp;= ignore, [On] &amp;= help "Turn on", [Off] &amp;= help "Turn off"]}
--   </pre>
--   
--   Now <tt>--on --off</tt> would produce <tt>Mode [On,Off]</tt>.
enum :: Data val => [val] -> val

-- | Add an annotation to a value.
(+=) :: Annotate ann -> ann -> Annotate ann
infixl 2 +=

-- | 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 <tt>:=</tt> or <tt>:=+</tt>.
--   
--   This operation is not type safe, and may raise an exception at runtime
--   if any field has the wrong type or label.
record :: Data a => a -> [Annotate ann] -> Annotate ann

-- | Lift a pure value to an annotation.
atom :: Data val => val -> Annotate ann

-- | This type represents an annotated value. The type of the underlying
--   value is not specified.
data Annotate ann

-- | Construct a field, <tt>fieldname := value</tt>.
(:=) :: (c -> f) -> f -> Annotate ann
infix 3 :=

-- | Like <a>enum</a>, but using the pure annotations.
enum_ :: (Data c, Data f) => (c -> f) -> [Annotate Ann] -> Annotate Ann

-- | Like <a>modes</a>, but using the pure annotations.
modes_ :: [Annotate Ann] -> Annotate Ann

-- | The general type of annotations that can be associated with a value.
data Ann

-- | A mode. Do not use the <a>Mode</a> constructor directly, instead use
--   <a>mode</a> to construct the <a>Mode</a> and then record updates. Each
--   mode has three main features:
--   
--   <ul>
--   <li>A list of submodes (<a>modeGroupModes</a>)</li>
--   <li>A list of flags (<a>modeGroupFlags</a>)</li>
--   <li>Optionally an unnamed argument (<a>modeArgs</a>)</li>
--   </ul>
--   
--   To produce the help information for a mode, either use
--   <tt>helpText</tt> or <a>show</a>.
data Mode a
class Typeable a => Data a
class Typeable (a :: k)


-- | This module provides a quotation feature to let you write command line
--   arguments in the impure style, but have them translated into the pure
--   style, as per <a>System.Console.CmdArgs.Implicit</a>. An example:
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell, DeriveDataTypeable, MagicHash #-}
--   import System.Console.CmdArgs.Implicit
--   import System.Console.CmdArgs.Quote
--   
--   data Sample = Sample {hello :: String} deriving (Show, Data, Typeable)
--   
--   $(cmdArgsQuote [d|
--       sample = Sample{hello = def &amp;=# help "World argument" &amp;=# opt "world"}
--                      &amp;=# summary "Sample v1"
--   
--       run = cmdArgs# sample :: IO Sample
--       |])
--   
--   main = print =&lt;&lt; run
--   </pre>
--   
--   Inside <a>cmdArgsQuote</a> you supply the command line parser using
--   attributes in the impure style. If you run with
--   <tt>-ddump-splices</tt> (to see the Template Haskell output), you
--   would see:
--   
--   <pre>
--   run = cmdArgs_
--       (record Sample{} [hello := def += help "World argument" += opt "world"]
--           += summary "Sample v1")
--       :: IO Sample
--   </pre>
--   
--   <i>Stubs</i>
--   
--   To define the original parser you may use either the standard impure
--   annotations (<a>(&amp;=)</a>, <a>modes</a>), or the stub annotations
--   versions defined in this module (<a>(&amp;=#)</a>, <a>modes</a>). The
--   stub versions do not include a <a>Data</a> constraint, so can be used
--   in situations where the Data instance is not yet available - typically
--   when defining the parser in the same module as the data type on GHC
--   7.2 and above. The stub versions should never be used outside
--   <a>cmdArgsQuote</a> and will always raise an error.
--   
--   <i>Explicit types</i>
--   
--   There will be a limited number of situations where an impure parser
--   will require additional types, typically on the result of
--   <a>cmdArgs</a> if the result is used without a fixed type - for
--   example if you <a>show</a> it. Most users will not need to add any
--   types. In some cases you may need to remove some explicit types, where
--   the intermediate type of the annotations has changed - but again, this
--   change should be rare.
--   
--   <i>Completeness</i>
--   
--   The translation is not complete, although works for all practical
--   instances I've tried. The translation works by first expanding out the
--   expression (inlining every function defined within the quote, inlining
--   let bindings), then performs the translation. This scheme leads to two
--   consequences: 1) Any expensive computation executed inside the
--   quotation to produce the command line flags may be duplicated (a very
--   unlikely scenario). 2) As I do not yet have expansion rules for all
--   possible expressions, the expansion (and subsequently the translation)
--   may fail. I am interested in any bug reports where the feature does
--   not work as intended.
module System.Console.CmdArgs.Quote

-- | Quotation function to turn an impure version of
--   <a>System.Console.CmdArgs.Implicit</a> into a pure one. For details
--   see <a>System.Console.CmdArgs.Quote</a>.
cmdArgsQuote :: Q [Dec] -> Q [Dec]

-- | Version of <a>&amp;=</a> without a <a>Data</a> context, only to be
--   used within <a>cmdArgsQuote</a>.
(&=#) :: a -> Ann -> a

-- | Version of <a>modes</a> without a <a>Data</a> context, only to be used
--   within <a>cmdArgsQuote</a>.
modes# :: [a] -> a

-- | Version of <a>cmdArgsMode</a> without a <a>Data</a> context, only to
--   be used within <a>cmdArgsQuote</a>.
cmdArgsMode# :: a -> Mode (CmdArgs a)

-- | Version of <a>cmdArgs</a> without a <a>Data</a> context, only to be
--   used within <a>cmdArgsQuote</a>.
cmdArgs# :: a -> IO a

-- | Version of <a>enum</a> without a <a>Data</a> context, only to be used
--   within <a>cmdArgsQuote</a>.
enum# :: [a] -> a


-- | This module re-exports the implicit command line parser.
module System.Console.CmdArgs


-- | This provides a compatiblity wrapper to the
--   <tt>System.Console.GetOpt</tt> module in <tt>base</tt>. That module is
--   essentially a Haskell port of the GNU <tt>getopt</tt> library.
--   
--   <i>Changes:</i> The changes from <tt>GetOpt</tt> are listed in the
--   documentation for each function.
module System.Console.CmdArgs.GetOpt

-- | Given a help text and a list of option descriptions, generate a
--   <a>Mode</a>.
convert :: String -> [OptDescr a] -> Mode ([a], [String])

-- | Process the command-line, and return the list of values that matched
--   (and those that didn't). The arguments are:
--   
--   <ul>
--   <li>The order requirements (see <a>ArgOrder</a>)</li>
--   <li>The option descriptions (see <a>OptDescr</a>)</li>
--   <li>The actual command line arguments (presumably got from
--   <a>getArgs</a>).</li>
--   </ul>
--   
--   <a>getOpt</a> returns a triple consisting of the option arguments, a
--   list of non-options, and a list of error messages.
--   
--   <i>Changes:</i> The list of errors will contain at most one entry, and
--   if an error is present then the other two lists will be empty.
getOpt :: ArgOrder a -> [OptDescr a] -> [String] -> ([a], [String], [String])

-- | <i>Changes:</i> This is exactly the same as <a>getOpt</a>, but the 3rd
--   element of the tuple (second last) will be an empty list.
getOpt' :: ArgOrder a -> [OptDescr a] -> [String] -> ([a], [String], [String], [String])

-- | Return a string describing the usage of a command, derived from the
--   header (first argument) and the options described by the second
--   argument.
usageInfo :: String -> [OptDescr a] -> String

-- | What to do with options following non-options.
--   
--   <i>Changes:</i> Only <a>Permute</a> is allowed, both
--   <tt>RequireOrder</tt> and <tt>ReturnInOrder</tt> have been removed.
data ArgOrder a
Permute :: ArgOrder a
data OptDescr a
Option :: [Char] -> [String] -> ArgDescr a -> String -> OptDescr a
data ArgDescr a
NoArg :: a -> ArgDescr a
ReqArg :: (String -> a) -> String -> ArgDescr a
OptArg :: (Maybe String -> a) -> String -> ArgDescr a
instance GHC.Internal.Base.Functor System.Console.CmdArgs.GetOpt.ArgOrder
