-- 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.8
-- |
-- {-# 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 <file>
-- docopt-sample echo [--caps] <string>
--
-- Options:
-- -c, --caps Caps-lock the echoed argument
-- |]
--
-- getArgOrExit = getArgOrExitWith patterns
--
-- main :: IO ()
-- main = do
-- args <- parseArgsOrExit patterns =<< getArgs
--
-- when (args `isPresent` (command "cat")) $ do
-- file <- args `getArgOrExit` (argument "file")
-- putStr =<< readFile file
--
-- when (args `isPresent` (command "echo")) $ do
-- let charTransform = if args `isPresent` (longOption "caps")
-- then toUpper
-- else id
-- string <- args `getArgOrExit` (argument "string")
-- putStrLn $ map charTransform string
--
module System.Console.Docopt
-- | A QuasiQuoter which parses a usage string and returns a
-- Docopt.
--
-- Example usage:
--
--
-- patterns :: Docopt
-- patterns = [docopt|
-- docopt-sample version 0.1.0
--
-- Usage:
-- docopt-sample cat <file>
-- docopt-sample echo [--caps] <string>
--
-- Options:
-- -c, --caps Caps-lock the echoed argument
-- |]
--
--
-- For help with the docopt usage format, see the readme on
-- github.
docopt :: QuasiQuoter
-- | Same as docopt, but parses the given file instead of a literal
-- string.
--
-- Example:
--
--
-- patterns :: Docopt
-- patterns = [docoptFile|USAGE|]
--
--
-- where USAGE 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 parseArgs, but exitWithUsage on parse failure.
-- E.g.
--
--
-- args <- parseArgsOrExit patterns =<< getArgs
--
parseArgsOrExit :: Docopt -> [String] -> IO Arguments
-- | The abstract data type ParseError represents parse errors. It
-- provides the source position (SourcePos) of the error and a
-- list of error messages (Message). A ParseError can be
-- returned by the function parse. ParseError is an
-- instance of the Show and Eq 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
-- | True if an option was present at all in an invocation.
--
-- Useful with longOptions and shortOptions, and in
-- conjunction with when.
isPresent :: Arguments -> Option -> Bool
notPresent :: Arguments -> Option -> Bool
-- | Just the value of the argument supplied, or Nothing if
-- one was not given.
--
-- If the option's presence is required by your Docopt usage text
-- (e.g. a positional argument), as in
--
--
-- Usage:
-- prog <required>
--
--
-- then getArg args (argument "required") is guaranteed to be a
-- Just.
getArg :: Arguments -> Option -> Maybe String
-- | Same as getArg, but exitWithUsage if Nothing.
--
-- As in getArg, if your usage pattern required the option,
-- getArgOrExitWith will not exit.
getArgOrExitWith :: Docopt -> Arguments -> Option -> IO String
-- | Same as getArg, but eliminate Nothing with a default
-- argument.
getArgWithDefault :: Arguments -> String -> Option -> String
-- | Returns all occurrences of a repeatable option, e.g.
-- <file>....
getAllArgs :: Arguments -> Option -> [String]
-- | Return the number of occurrences of an option in an invocation.
--
-- Useful with repeatable flags, e.g. [ -v | -vv | -vvv].
getArgCount :: Arguments -> Option -> Int
-- | For Usage: prog cmd, ask for command "cmd".
--
-- For Usage: prog - or Usage: prog [-], ask for
-- command "-". Same for --.
command :: String -> Option
-- | For Usage: prog <file>, ask for argument
-- "file".
--
-- Note: A Usage: prog --output=<file> is
-- not matched by argument "file". See longOption.
argument :: String -> Option
-- | For Usage: prog -h, ask for shortOption 'h'.
--
-- For Usage: prog -o=<file>, ask for shortOption
-- 'o'.
shortOption :: Char -> Option
-- | For Usage: prog --version, ask for longOption
-- "version".
--
-- For Usage: prog --output=<file>, ask for longOption
-- "output".
longOption :: String -> Option
-- | Deprecated: Monadic query functions will soon be removed
getAllArgsM :: Monad m => Arguments -> Option -> m [String]
-- | Deprecated: Monadic query functions will soon be removed
notPresentM :: Monad m => Arguments -> Option -> m Bool
-- | Deprecated: Monadic query functions will soon be removed
isPresentM :: Monad m => Arguments -> Option -> m Bool
-- | Deprecated: Use getAllArgs instead
getFirstArg :: MonadFail m => Arguments -> Option -> m String
module System.Console.Docopt.NoTH
-- | Parse docopt-formatted usage patterns.
--
-- For help with the docopt usage format, see the readme on
-- github.
parseUsage :: String -> Either ParseError Docopt
-- | Same as parseUsage, but exitWithUsage on parse failure.
-- E.g.
--
--
-- let usageStr = "Usage:\n prog [--option]\n"
-- patterns <- parseUsageOrExit usageStr
--
parseUsageOrExit :: String -> IO Docopt
-- | Parse command line arguments.
parseArgs :: Docopt -> [String] -> Either ParseError Arguments
-- | Same as parseArgs, but exitWithUsage on parse failure.
-- E.g.
--
--
-- args <- parseArgsOrExit patterns =<< getArgs
--
parseArgsOrExit :: Docopt -> [String] -> IO Arguments
-- | The abstract data type ParseError represents parse errors. It
-- provides the source position (SourcePos) of the error and a
-- list of error messages (Message). A ParseError can be
-- returned by the function parse. ParseError is an
-- instance of the Show and Eq 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
-- | True if an option was present at all in an invocation.
--
-- Useful with longOptions and shortOptions, and in
-- conjunction with when.
isPresent :: Arguments -> Option -> Bool
notPresent :: Arguments -> Option -> Bool
-- | Just the value of the argument supplied, or Nothing if
-- one was not given.
--
-- If the option's presence is required by your Docopt usage text
-- (e.g. a positional argument), as in
--
--
-- Usage:
-- prog <required>
--
--
-- then getArg args (argument "required") is guaranteed to be a
-- Just.
getArg :: Arguments -> Option -> Maybe String
-- | Same as getArg, but exitWithUsage if Nothing.
--
-- As in getArg, if your usage pattern required the option,
-- getArgOrExitWith will not exit.
getArgOrExitWith :: Docopt -> Arguments -> Option -> IO String
-- | Same as getArg, but eliminate Nothing with a default
-- argument.
getArgWithDefault :: Arguments -> String -> Option -> String
-- | Returns all occurrences of a repeatable option, e.g.
-- <file>....
getAllArgs :: Arguments -> Option -> [String]
-- | Return the number of occurrences of an option in an invocation.
--
-- Useful with repeatable flags, e.g. [ -v | -vv | -vvv].
getArgCount :: Arguments -> Option -> Int
-- | For Usage: prog cmd, ask for command "cmd".
--
-- For Usage: prog - or Usage: prog [-], ask for
-- command "-". Same for --.
command :: String -> Option
-- | For Usage: prog <file>, ask for argument
-- "file".
--
-- Note: A Usage: prog --output=<file> is
-- not matched by argument "file". See longOption.
argument :: String -> Option
-- | For Usage: prog -h, ask for shortOption 'h'.
--
-- For Usage: prog -o=<file>, ask for shortOption
-- 'o'.
shortOption :: Char -> Option
-- | For Usage: prog --version, ask for longOption
-- "version".
--
-- For Usage: prog --output=<file>, ask for longOption
-- "output".
longOption :: String -> Option
-- | Deprecated: Monadic query functions will soon be removed
getAllArgsM :: Monad m => Arguments -> Option -> m [String]
-- | Deprecated: Monadic query functions will soon be removed
notPresentM :: Monad m => Arguments -> Option -> m Bool
-- | Deprecated: Monadic query functions will soon be removed
isPresentM :: Monad m => Arguments -> Option -> m Bool
-- | Deprecated: Use getAllArgs instead
getFirstArg :: MonadFail m => Arguments -> Option -> m String