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


-- | A command-line interface parser that will make you smile
--   
--   Docopt parses command-line interface usage text that adheres to a
--   familiar syntax, and from it builds a command-line argument parser
--   that will ensure your program is invoked correctly with the available
--   options specified in the usage text. This allows the developer to
--   write a usage text and get an argument parser for free.
@package docopt
@version 0.7.0.5

module System.Console.Docopt.NoTH

-- | Parse docopt-formatted usage patterns.
--   
--   For help with the docopt usage format, see <a>the readme on
--   github</a>.
parseUsage :: String -> Either ParseError Docopt

-- | Same as <a>parseUsage</a>, but <a>exitWithUsage</a> on parse failure.
--   E.g.
--   
--   <pre>
--   let usageStr = "Usage:\n  prog [--option]\n"
--   patterns &lt;- parseUsageOrExit usageStr
--   </pre>
parseUsageOrExit :: String -> IO Docopt

-- | Parse command line arguments.
parseArgs :: Docopt -> [String] -> Either ParseError Arguments

-- | Same as <a>parseArgs</a>, but <a>exitWithUsage</a> on parse failure.
--   E.g.
--   
--   <pre>
--   args &lt;- parseArgsOrExit patterns =&lt;&lt; getArgs
--   </pre>
parseArgsOrExit :: Docopt -> [String] -> IO Arguments

-- | The abstract data type <tt>ParseError</tt> represents parse errors. It
--   provides the source position (<a>SourcePos</a>) of the error and a
--   list of error messages (<a>Message</a>). A <tt>ParseError</tt> can be
--   returned by the function <a>parse</a>. <tt>ParseError</tt> is an
--   instance of the <a>Show</a> and <a>Eq</a> classes.
data ParseError :: *

-- | An abstract data type which represents Docopt usage patterns.
data Docopt

-- | Retrieve the original usage string.
usage :: Docopt -> String

-- | Exit after printing usage text.
exitWithUsage :: Docopt -> IO a

-- | Exit after printing a custom message followed by usage text. Intended
--   for convenience when more context can be given about what went wrong.
exitWithUsageMessage :: Docopt -> String -> IO a

-- | A named leaf node of the usage pattern tree
data Option

-- | Maps each Option to all of the valued parsed from the command line (in
--   order of last to first, if multiple values encountered)
type Arguments = Map Option ArgValue

-- | <a>True</a> if an option was present at all in an invocation.
--   
--   Useful with <a>longOption</a>s and <a>shortOption</a>s, and in
--   conjunction with <a>when</a>.
isPresent :: Arguments -> Option -> Bool
notPresent :: Arguments -> Option -> Bool

-- | <a>Just</a> the value of the argument supplied, or <a>Nothing</a> if
--   one was not given.
--   
--   If the option's presence is required by your <a>Docopt</a> usage text
--   (e.g. a positional argument), as in
--   
--   <pre>
--   Usage:
--     prog &lt;required&gt;
--   </pre>
--   
--   then <tt>getArg args (argument 'required')</tt> is guaranteed to be a
--   <a>Just</a>.
getArg :: Arguments -> Option -> Maybe String

-- | Same as <a>getArg</a>, but <a>exitWithUsage</a> if <a>Nothing</a>.
--   
--   As in <a>getArg</a>, if your usage pattern required the option,
--   <a>getArgOrExitWith</a> will not exit.
getArgOrExitWith :: Docopt -> Arguments -> Option -> IO String

-- | Same as <a>getArg</a>, but eliminate <a>Nothing</a> with a default
--   argument.
getArgWithDefault :: Arguments -> String -> Option -> String

-- | Returns all occurrences of a repeatable option, e.g.
--   <tt>&lt;file&gt;...</tt>.
getAllArgs :: Arguments -> Option -> [String]

-- | Return the number of occurrences of an option in an invocation.
--   
--   Useful with repeatable flags, e.g. <tt>[ -v | -vv | -vvv]</tt>.
getArgCount :: Arguments -> Option -> Int

-- | For <tt>Usage: prog cmd</tt>, ask for <tt>command "cmd"</tt>.
--   
--   For <tt>Usage: prog -</tt> or <tt>Usage: prog [-]</tt>, ask for
--   <tt>command "-"</tt>. Same for <tt>--</tt>.
command :: String -> Option

-- | For <tt>Usage: prog &lt;file&gt;</tt>, ask for <tt>argument
--   "file"</tt>.
--   
--   <b>Note:</b> A <tt>Usage: prog --output=&lt;file&gt;</tt> is
--   <i>not</i> matched by <tt>argument "file"</tt>. See <a>longOption</a>.
argument :: String -> Option

-- | For <tt>Usage: prog -h</tt>, ask for <tt>shortOption 'h'</tt>.
--   
--   For <tt>Usage: prog -o=&lt;file&gt;</tt>, ask for <tt>shortOption
--   'o'</tt>.
shortOption :: Char -> Option

-- | For <tt>Usage: prog --version</tt>, ask for <tt>longOption
--   "version"</tt>.
--   
--   For <tt>Usage: prog --output=&lt;file&gt;</tt>, ask for <tt>longOption
--   "output"</tt>.
longOption :: String -> Option

-- | <i>Deprecated: Monadic query functions will soon be removed</i>
getAllArgsM :: Monad m => Arguments -> Option -> m [String]

-- | <i>Deprecated: Monadic query functions will soon be removed</i>
notPresentM :: Monad m => Arguments -> Option -> m Bool

-- | <i>Deprecated: Monadic query functions will soon be removed</i>
isPresentM :: Monad m => Arguments -> Option -> m Bool

-- | <i>Deprecated: Use <a>getAllArgs</a> instead</i>
getFirstArg :: Monad m => Arguments -> Option -> m String


-- | Example:
--   
--   <pre>
--   {-# LANGUAGE QuasiQuotes #-}
--   module Main where
--   
--   import Control.Monad (when)
--   import Data.Char (toUpper)
--   import System.Environment (getArgs)
--   import System.Console.Docopt
--   
--   patterns :: Docopt
--   patterns = [docopt|
--   docopt-sample version 0.1.0
--   
--   Usage:
--     docopt-sample cat &lt;file&gt;
--     docopt-sample echo [--caps] &lt;string&gt;
--   
--   Options:
--     -c, --caps    Caps-lock the echoed argument
--   |]
--   
--   getArgOrExit = getArgOrExitWith patterns
--   
--   main :: IO ()
--   main = do
--     args &lt;- parseArgsOrExit patterns =&lt;&lt; getArgs
--   
--     when (args `isPresent` (command "cat")) $ do
--       file &lt;- args `getArgOrExit` (argument "file")
--       putStr =&lt;&lt; readFile file
--   
--     when (args `isPresent` (command "echo")) $ do
--       let charTransform = if args `isPresent` (longOption "caps")
--                           then toUpper
--                           else id
--       string &lt;- args `getArgOrExit` (argument "string")
--       putStrLn $ map charTransform string
--   </pre>
module System.Console.Docopt

-- | A <a>QuasiQuoter</a> which parses a usage string and returns a
--   <a>Docopt</a>.
--   
--   Example usage:
--   
--   <pre>
--   patterns :: Docopt
--   patterns = [docopt|
--   docopt-sample version 0.1.0
--   
--   Usage:
--     docopt-sample cat &lt;file&gt;
--     docopt-sample echo [--caps] &lt;string&gt;
--   
--   Options:
--     -c, --caps    Caps-lock the echoed argument
--   |]
--   </pre>
--   
--   For help with the docopt usage format, see <a>the readme on
--   github</a>.
docopt :: QuasiQuoter

-- | Same as <a>docopt</a>, but parses the given file instead of a literal
--   string.
--   
--   Example:
--   
--   <pre>
--   patterns :: Docopt
--   patterns = [docoptFile|USAGE|]
--   </pre>
--   
--   where <tt>USAGE</tt> is the name of a file which contains the usage
--   string (relative to the directory from which ghc is invoked).
docoptFile :: QuasiQuoter

-- | Parse command line arguments.
parseArgs :: Docopt -> [String] -> Either ParseError Arguments

-- | Same as <a>parseArgs</a>, but <a>exitWithUsage</a> on parse failure.
--   E.g.
--   
--   <pre>
--   args &lt;- parseArgsOrExit patterns =&lt;&lt; getArgs
--   </pre>
parseArgsOrExit :: Docopt -> [String] -> IO Arguments

-- | The abstract data type <tt>ParseError</tt> represents parse errors. It
--   provides the source position (<a>SourcePos</a>) of the error and a
--   list of error messages (<a>Message</a>). A <tt>ParseError</tt> can be
--   returned by the function <a>parse</a>. <tt>ParseError</tt> is an
--   instance of the <a>Show</a> and <a>Eq</a> classes.
data ParseError :: *

-- | An abstract data type which represents Docopt usage patterns.
data Docopt

-- | Retrieve the original usage string.
usage :: Docopt -> String

-- | Exit after printing usage text.
exitWithUsage :: Docopt -> IO a

-- | Exit after printing a custom message followed by usage text. Intended
--   for convenience when more context can be given about what went wrong.
exitWithUsageMessage :: Docopt -> String -> IO a

-- | A named leaf node of the usage pattern tree
data Option

-- | Maps each Option to all of the valued parsed from the command line (in
--   order of last to first, if multiple values encountered)
type Arguments = Map Option ArgValue

-- | <a>True</a> if an option was present at all in an invocation.
--   
--   Useful with <a>longOption</a>s and <a>shortOption</a>s, and in
--   conjunction with <a>when</a>.
isPresent :: Arguments -> Option -> Bool
notPresent :: Arguments -> Option -> Bool

-- | <a>Just</a> the value of the argument supplied, or <a>Nothing</a> if
--   one was not given.
--   
--   If the option's presence is required by your <a>Docopt</a> usage text
--   (e.g. a positional argument), as in
--   
--   <pre>
--   Usage:
--     prog &lt;required&gt;
--   </pre>
--   
--   then <tt>getArg args (argument 'required')</tt> is guaranteed to be a
--   <a>Just</a>.
getArg :: Arguments -> Option -> Maybe String

-- | Same as <a>getArg</a>, but <a>exitWithUsage</a> if <a>Nothing</a>.
--   
--   As in <a>getArg</a>, if your usage pattern required the option,
--   <a>getArgOrExitWith</a> will not exit.
getArgOrExitWith :: Docopt -> Arguments -> Option -> IO String

-- | Same as <a>getArg</a>, but eliminate <a>Nothing</a> with a default
--   argument.
getArgWithDefault :: Arguments -> String -> Option -> String

-- | Returns all occurrences of a repeatable option, e.g.
--   <tt>&lt;file&gt;...</tt>.
getAllArgs :: Arguments -> Option -> [String]

-- | Return the number of occurrences of an option in an invocation.
--   
--   Useful with repeatable flags, e.g. <tt>[ -v | -vv | -vvv]</tt>.
getArgCount :: Arguments -> Option -> Int

-- | For <tt>Usage: prog cmd</tt>, ask for <tt>command "cmd"</tt>.
--   
--   For <tt>Usage: prog -</tt> or <tt>Usage: prog [-]</tt>, ask for
--   <tt>command "-"</tt>. Same for <tt>--</tt>.
command :: String -> Option

-- | For <tt>Usage: prog &lt;file&gt;</tt>, ask for <tt>argument
--   "file"</tt>.
--   
--   <b>Note:</b> A <tt>Usage: prog --output=&lt;file&gt;</tt> is
--   <i>not</i> matched by <tt>argument "file"</tt>. See <a>longOption</a>.
argument :: String -> Option

-- | For <tt>Usage: prog -h</tt>, ask for <tt>shortOption 'h'</tt>.
--   
--   For <tt>Usage: prog -o=&lt;file&gt;</tt>, ask for <tt>shortOption
--   'o'</tt>.
shortOption :: Char -> Option

-- | For <tt>Usage: prog --version</tt>, ask for <tt>longOption
--   "version"</tt>.
--   
--   For <tt>Usage: prog --output=&lt;file&gt;</tt>, ask for <tt>longOption
--   "output"</tt>.
longOption :: String -> Option

-- | <i>Deprecated: Monadic query functions will soon be removed</i>
getAllArgsM :: Monad m => Arguments -> Option -> m [String]

-- | <i>Deprecated: Monadic query functions will soon be removed</i>
notPresentM :: Monad m => Arguments -> Option -> m Bool

-- | <i>Deprecated: Monadic query functions will soon be removed</i>
isPresentM :: Monad m => Arguments -> Option -> m Bool

-- | <i>Deprecated: Use <a>getAllArgs</a> instead</i>
getFirstArg :: Monad m => Arguments -> Option -> m String
