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


-- | Utilities and combinators for parsing command line options
--   
--   Here is a simple example of an applicative option parser:
--   
--   <pre>
--   data Sample = Sample
--     { hello :: String
--     , quiet :: Bool }
--   
--   sample :: Parser Sample
--   sample = Sample
--     &lt;$&gt; strOption
--         ( long "hello"
--         &amp; metavar "TARGET"
--         &amp; help "Target for the greeting" )
--     &lt;*&gt; switch
--         ( long "quiet"
--         &amp; help "Whether to be quiet" )
--   </pre>
--   
--   The parser is built using applicative style starting from a set of
--   basic combinators. In this example, <tt>hello</tt> is defined as an
--   <a>option</a> with a <tt>String</tt> argument, while <tt>quiet</tt> is
--   a boolean <a>flag</a> (called <a>switch</a>).
--   
--   A parser can be used like this:
--   
--   <pre>
--   greet :: Sample -&gt; IO ()
--   greet (Sample h False) = putStrLn $ "Hello, " ++ h
--   greet _ = return ()
--   
--   main :: IO ()
--   main = execParser opts &gt;&gt;= greet
--     where
--       opts = info (helper &lt;*&gt; sample)
--         ( fullDesc
--         &amp; progDesc "Print a greeting for TARGET"
--         &amp; header "hello - a test for optparse-applicative" )
--   </pre>
--   
--   The <tt>greet</tt> function is the entry point of the program, while
--   <tt>opts</tt> is a complete description of the program, used when
--   generating a help text. The <a>helper</a> combinator takes any parser,
--   and adds a <tt>help</tt> option to it (which always fails).
--   
--   The <tt>hello</tt> option in this example is mandatory (since it
--   doesn't have a default value), so running the program without any
--   argument will display a help text:
--   
--   <pre>
--   hello - a test for optparse-applicative
--   
--   Usage: hello --hello TARGET [--quiet]
--     Print a greeting for TARGET
--   
--   Available options:
--     -h,--help                Show this help text
--     --hello TARGET           Target for the greeting
--     --quiet                  Whether to be quiet
--   </pre>
--   
--   containing a short usage summary, and a detailed list of options with
--   descriptions.
@package optparse-applicative
@version 0.4.1

module Options.Applicative.Utils

-- | Concatenate two strings with a space in the middle.
(<+>) :: String -> String -> String

-- | Concatenate strings vertically with empty lines in between.
vcat :: [String] -> String

-- | Display pairs of strings in a table.
tabulate :: [(String, String)] -> [String]

-- | Pad a string to a fixed size with whitespace.
pad :: Int -> String -> String

module Options.Applicative.Types

-- | A full description for a runnable <a>Parser</a> for a program.
data ParserInfo a
ParserInfo :: Parser a -> Bool -> String -> String -> String -> Int -> ParserInfo a

-- | the option parser for the program
infoParser :: ParserInfo a -> Parser a

-- | whether the help text should contain full documentation
infoFullDesc :: ParserInfo a -> Bool

-- | brief parser description
infoProgDesc :: ParserInfo a -> String

-- | header of the full parser description
infoHeader :: ParserInfo a -> String

-- | footer of the full parser description
infoFooter :: ParserInfo a -> String

-- | exit code for a parser failure
infoFailureCode :: ParserInfo a -> Int

-- | Global preferences for a top-level <a>Parser</a>.
data ParserPrefs
ParserPrefs :: String -> Bool -> ParserPrefs

-- | metavar suffix for multiple options
prefMultiSuffix :: ParserPrefs -> String

-- | automatically disambiguate abbreviations
prefDisambiguate :: ParserPrefs -> Bool

-- | A single option of a parser.
data Option a
Option :: OptReader a -> OptProperties -> Option a

-- | reader for this option
optMain :: Option a -> OptReader a

-- | properties of this option
optProps :: Option a -> OptProperties
data OptName
OptShort :: !Char -> OptName
OptLong :: !String -> OptName

-- | An <a>OptReader</a> defines whether an option matches an command line
--   argument.
data OptReader a

-- | option reader
OptReader :: [OptName] -> (CReader a) -> OptReader a

-- | flag reader
FlagReader :: [OptName] -> !a -> OptReader a

-- | argument reader
ArgReader :: (CReader a) -> OptReader a

-- | command reader
CmdReader :: [String] -> (String -> Maybe (ParserInfo a)) -> OptReader a

-- | Specification for an individual parser option.
data OptProperties
OptProperties :: OptVisibility -> String -> String -> Maybe String -> OptProperties

-- | whether this flag is shown is the brief description
propVisibility :: OptProperties -> OptVisibility

-- | help text for this option
propHelp :: OptProperties -> String

-- | metavariable for this option
propMetaVar :: OptProperties -> String

-- | what to show in the help text as the default
propShowDefault :: OptProperties -> Maybe String

-- | Visibility of an option in the help text.
data OptVisibility

-- | does not appear in the help text at all
Internal :: OptVisibility

-- | only visible in the full description
Hidden :: OptVisibility

-- | visible both in the full and brief descriptions
Visible :: OptVisibility
data CReader a
CReader :: Completer -> (String -> Maybe a) -> CReader a
crCompleter :: CReader a -> Completer
crReader :: CReader a -> String -> Maybe a

-- | A <tt>Parser a</tt> is an option parser returning a value of type
--   <tt>a</tt>.
data Parser a
NilP :: Maybe a -> Parser a
OptP :: Option a -> Parser a
MultP :: Parser (a -> b) -> Parser a -> Parser b
AltP :: Parser a -> Parser a -> Parser a
BindP :: Parser a -> (a -> Parser b) -> Parser b
newtype ParserM r
ParserM :: (forall x. (r -> Parser x) -> Parser x) -> ParserM r
runParserM :: ParserM r -> forall x. (r -> Parser x) -> Parser x
newtype Completer
Completer :: (String -> IO [String]) -> Completer
runCompleter :: Completer -> String -> IO [String]

-- | Result after a parse error.
data ParserFailure
ParserFailure :: (String -> IO String) -> ExitCode -> ParserFailure

-- | Function which takes the program name as input and returns an error
--   message
errMessage :: ParserFailure -> String -> IO String

-- | Exit code to use for this error
errExitCode :: ParserFailure -> ExitCode
data OptHelpInfo
OptHelpInfo :: Bool -> Bool -> OptHelpInfo
hinfoMulti :: OptHelpInfo -> Bool
hinfoDefault :: OptHelpInfo -> Bool
data OptTree a
Leaf :: a -> OptTree a
MultNode :: [OptTree a] -> OptTree a
AltNode :: [OptTree a] -> OptTree a
fromM :: ParserM a -> Parser a
oneM :: Parser a -> ParserM a
manyM :: Parser a -> ParserM [a]
optVisibility :: Option a -> OptVisibility
optMetaVar :: Option a -> String
optHelp :: Option a -> String
optShowDefault :: Option a -> Maybe String
instance Eq OptName
instance Ord OptName
instance Eq OptVisibility
instance Ord OptVisibility
instance Functor CReader
instance Functor OptReader
instance Functor ParserInfo
instance Functor Option
instance Functor OptTree
instance Show a => Show (OptTree a)
instance Error ParserFailure
instance Monoid Completer
instance Alternative Parser
instance Applicative ParserM
instance Functor ParserM
instance Monad ParserM
instance Applicative Parser
instance Functor Parser

module Options.Applicative.Builder.Completer
listIOCompleter :: IO [String] -> Completer
listCompleter :: [String] -> Completer
bashCompleter :: String -> Completer

module Options.Applicative.Common

-- | A <tt>Parser a</tt> is an option parser returning a value of type
--   <tt>a</tt>.
data Parser a

-- | Create a parser composed of a single option.
liftOpt :: Option a -> Parser a

-- | A full description for a runnable <a>Parser</a> for a program.
data ParserInfo a
ParserInfo :: Parser a -> Bool -> String -> String -> String -> Int -> ParserInfo a

-- | the option parser for the program
infoParser :: ParserInfo a -> Parser a

-- | whether the help text should contain full documentation
infoFullDesc :: ParserInfo a -> Bool

-- | brief parser description
infoProgDesc :: ParserInfo a -> String

-- | header of the full parser description
infoHeader :: ParserInfo a -> String

-- | footer of the full parser description
infoFooter :: ParserInfo a -> String

-- | exit code for a parser failure
infoFailureCode :: ParserInfo a -> Int

-- | Apply a <a>Parser</a> to a command line, and return a result and
--   leftover arguments. This function returns an error if any parsing
--   error occurs, or if any options are missing and don't have a default
--   value.
runParser :: MonadP m => Parser a -> [String] -> m (a, [String])
runParserFully :: MonadP m => Parser a -> [String] -> m a

-- | The default value of a <a>Parser</a>. This function returns an error
--   if any of the options don't have a default value.
evalParser :: Parser a -> Maybe a

-- | Map a polymorphic function over all the options of a parser, and
--   collect the results in a list.
mapParser :: (forall x. OptHelpInfo -> Option x -> b) -> Parser a -> [b]

-- | Like <a>mapParser</a>, but collect the results in a tree structure.
treeMapParser :: (forall x. OptHelpInfo -> Option x -> b) -> Parser a -> OptTree b
optionNames :: OptReader a -> [OptName]
instance Monoid MatchResult

module Options.Applicative.Builder

-- | Builder for a command parser. The <a>command</a> modifier can be used
--   to specify individual commands.
subparser :: Mod CommandFields a -> Parser a

-- | Builder for an argument parser.
argument :: (String -> Maybe a) -> Mod ArgumentFields a -> Parser a

-- | Builder for an argument list parser. All arguments are collected and
--   returned as a list.
--   
--   Note that arguments starting with <tt><a>-</a></tt> are ignored.
--   
--   This parser accepts a special argument: <tt>--</tt>. When a
--   <tt>--</tt> is found on the command line, all following arguments are
--   included in the result, even if they start with <tt><a>-</a></tt>.
arguments :: (String -> Maybe a) -> Mod ArgumentFields [a] -> Parser [a]

-- | Builder for a flag parser.
--   
--   A flag that switches from a "default value" to an "active value" when
--   encountered. For a simple boolean value, use <a>switch</a> instead.
flag :: a -> a -> Mod FlagFields a -> Parser a

-- | Builder for a flag parser without a default value.
--   
--   Same as <a>flag</a>, but with no default value. In particular, this
--   flag will never parse successfully by itself.
--   
--   It still makes sense to use it as part of a composite parser. For
--   example
--   
--   <pre>
--   length &lt;$&gt; many (flag' () (short 't'))
--   </pre>
--   
--   is a parser that counts the number of <a>-t</a> arguments on the
--   command line.
flag' :: a -> Mod FlagFields a -> Parser a

-- | Builder for a boolean flag.
--   
--   <pre>
--   switch = flag False True
--   </pre>
switch :: Mod FlagFields Bool -> Parser Bool

-- | Builder for an option with a null reader. A non-trivial reader can be
--   added using the <a>reader</a> modifier.
nullOption :: Mod OptionFields a -> Parser a

-- | Builder for an option taking a <a>String</a> argument.
strOption :: Mod OptionFields String -> Parser String

-- | Builder for an option using the <a>auto</a> reader.
option :: Read a => Mod OptionFields a -> Parser a

-- | Specify a short name for an option.
short :: HasName f => Char -> Mod f a

-- | Specify a long name for an option.
long :: HasName f => String -> Mod f a

-- | Specify the help text for an option.
help :: String -> Mod f a

-- | Specify a default value for an option.
value :: a -> Mod f a

-- | Specify a function to show the default value for an option.
showDefaultWith :: (a -> String) -> Mod f a

-- | Show the default value for this option using its <a>Show</a> instance.
showDefault :: Show a => Mod f a

-- | Specify the metavariable.
metavar :: String -> Mod f a

-- | Specify the <a>Option</a> reader.
reader :: (String -> Maybe a) -> Mod OptionFields a

-- | Hide this option from the brief description.
hidden :: Mod f a

-- | Hide this option from the help text
internal :: Mod f a

-- | Add a command to a subparser option.
command :: String -> ParserInfo a -> Mod CommandFields a

-- | Add a list of possible completion values.
completeWith :: HasCompleter f => [String] -> Mod f a

-- | Add a bash completion action. Common actions include <tt>file</tt> and
--   <tt>directory</tt>. See
--   http:<i></i>www.gnu.org<i>software</i>bash<i>manual</i>html_node/Programmable-Completion-Builtins.html#Programmable-Completion-Builtins
--   for a complete list.
action :: HasCompleter f => String -> Mod f a

-- | Add a completer to an argument.
--   
--   A completer is a function String -&gt; IO String which, given a
--   partial argument, returns all possible completions for that argument.
completer :: HasCompleter f => Completer -> Mod f a

-- | Trivial option modifier.
idm :: Monoid m => m

-- | Compose modifiers.
(&) :: Monoid m => m -> m -> m

-- | <a>Option</a> reader based on the <a>Read</a> type class.
auto :: Read a => String -> Maybe a

-- | String <a>Option</a> reader.
str :: String -> Maybe String

-- | Null <a>Option</a> reader. All arguments will fail validation.
disabled :: String -> Maybe a
data Mod f a
class HasName f
class HasCompleter f
data OptionFields a
data FlagFields a
data CommandFields a
data ArgumentFields a

-- | Modifier for <a>ParserInfo</a>.
data InfoMod a

-- | Show a full description in the help text of this parser.
fullDesc :: InfoMod a

-- | Only show a brief description in the help text of this parser.
briefDesc :: InfoMod a

-- | Specify a header for this parser.
header :: String -> InfoMod a

-- | Specify a short program description.
progDesc :: String -> InfoMod a

-- | Specify a footer for this parser.
footer :: String -> InfoMod a

-- | Specify an exit code if a parse error occurs.
failureCode :: Int -> InfoMod a

-- | Create a <a>ParserInfo</a> given a <a>Parser</a> and a modifier.
info :: Parser a -> InfoMod a -> ParserInfo a
data PrefsMod
multiSuffix :: String -> PrefsMod
disambiguate :: PrefsMod
prefs :: PrefsMod -> ParserPrefs
instance Functor OptionFields
instance Functor FlagFields
instance Functor CommandFields
instance Functor ArgumentFields
instance Monoid PrefsMod
instance Monoid (InfoMod a)
instance Monoid (Mod f a)
instance Monoid (DefaultProp a)
instance HasCompleter ArgumentFields
instance HasCompleter OptionFields
instance HasName FlagFields
instance HasName OptionFields

module Options.Applicative.BashCompletion
bashCompletionParser :: Parser a -> ParserPrefs -> Parser ParserFailure

module Options.Applicative.Help

-- | Generate descriptions for commands.
cmdDesc :: Parser a -> [String]

-- | Generate a brief help text for a parser.
briefDesc :: ParserPrefs -> Parser a -> String

-- | Generate a full help text for a parser.
fullDesc :: ParserPrefs -> Parser a -> [String]

-- | Generate the help text for a program.
parserHelpText :: ParserPrefs -> ParserInfo a -> String

module Options.Applicative.Extra

-- | A hidden "helper" option which always fails.
helper :: Parser (a -> a)

-- | Run a program description.
--   
--   Parse command line arguments. Display help text and exit if any parse
--   error occurs.
execParser :: ParserInfo a -> IO a

-- | A pure version <a>execParser</a>.
execParserPure :: ParserPrefs -> ParserInfo a -> [String] -> Either ParserFailure a

-- | Run a program description with custom preferences.
customExecParser :: ParserPrefs -> ParserInfo a -> IO a

-- | Generate option summary.
usage :: ParserPrefs -> Parser a -> String -> String

-- | Result after a parse error.
data ParserFailure
ParserFailure :: (String -> IO String) -> ExitCode -> ParserFailure

-- | Function which takes the program name as input and returns an error
--   message
errMessage :: ParserFailure -> String -> IO String

-- | Exit code to use for this error
errExitCode :: ParserFailure -> ExitCode

module Options.Applicative


-- | This module contains an arrow interface for option parsers, which
--   allows to define and combine parsers using the arrow notation and
--   arrow combinators.
--   
--   The arrow syntax is particularly useful to create parsers of nested
--   structures, or records where the order of fields is different from the
--   order in which the parsers should be applied.
--   
--   For example, an <a>arguments</a> parser often needs to be applied
--   last, and that makes it inconvenient to use it for a field which is
--   not the last one in a record.
--   
--   Using the arrow syntax and the functions in this module, one can
--   write, e.g.:
--   
--   <pre>
--   data Options = Options
--     { optArgs :: [String]
--     , optVerbose :: Bool }
--   
--   opts :: Parser Options
--   opts = runA $ proc () -&gt; do
--     verbose &lt;- asA (switch (short 'v')) -&lt; ()
--     args &lt;- asA (arguments str idm) -&lt; ()
--     returnA -&lt; Options args verbose
--   </pre>
--   
--   Parser arrows, created out of regular <a>Parser</a> values using the
--   <a>asA</a> function, are arrows taking <tt>()</tt> as argument and
--   returning the parsed value.
module Options.Applicative.Arrows

-- | For any <a>Applicative</a> functor <tt>f</tt>, <tt>A f</tt> is the
--   <a>Arrow</a> instance associated to <tt>f</tt>.
--   
--   The <a>A</a> constructor can be used to convert a value of type <tt>f
--   (a -&gt; b)</tt> into an arrow.
newtype A f a b
A :: f (a -> b) -> A f a b
unA :: A f a b -> f (a -> b)

-- | Convert a value of type <tt>f a</tt> into an arrow taking <tt>()</tt>
--   as argument.
--   
--   Applied to a value of type <a>Parser</a>, it turns it into an arrow
--   that can be used inside an arrow command, or passed to arrow
--   combinators.
asA :: Applicative f => f a -> A f () a

-- | Convert an arrow back to an applicative value.
--   
--   This function can be used to return a result of type <a>Parser</a>
--   from an arrow command.
runA :: Applicative f => A f () a -> f a

-- | The type of arrows associated to the applicative <a>Parser</a>
--   functor.
type ParserA = A Parser
instance Applicative f => Arrow (A f)
instance Applicative f => Category (A f)
