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


-- | Applicative flag parsing
--   
--   <a>https://github.com/mtth/flags-applicative</a>
@package flags-applicative
@version 0.0.4.2


-- | Simple flags parsing module, inspired by
--   <tt>optparse-applicative</tt>.
--   
--   Sample usage (note the default log level and optional context):
--   
--   <pre>
--   module Main where
--   
--   import Control.Applicative ((&lt;|&gt;), optional)
--   import Data.Text (Text)
--   import Flags.Applicative
--   
--   data Options = Options
--     { rootPath :: Text
--     , logLevel :: Int
--     , context :: Maybe Text
--     } deriving Show
--   
--   optionsParser :: FlagParser Options
--   optionsParser = Options &lt;$&gt; textFlag "root" "path to the root"
--                           &lt;*&gt; (autoFlag "log_level" "" &lt;|&gt; pure 0)
--                           &lt;*&gt; (optional $ textFlag "context" "")
--   
--   main :: IO ()
--   main = do
--     (opts, args) &lt;- parseSystemFlagsOrDie optionsParser
--     print opts
--   </pre>
module Flags.Applicative

-- | The name of a flag (without the <tt>--</tt> prefix). Names can use all
--   valid utf-8 characters except <tt>=</tt> (the value delimiter). In
--   general, it's good practice for flag names to be lowercase ASCII with
--   underscores.
--   
--   The following names are reserved and attempting to define a flag with
--   the same name will cause an error:
--   
--   <ul>
--   <li><tt>help</tt>, displays usage when set.</li>
--   <li><tt>swallowed_flags</tt>, flags in this list which are set but
--   undeclared will be ignored rather than cause an error during
--   parsing.</li>
--   <li><tt>swallowed_switches</tt>, similar to <tt>swallowed_flags</tt>
--   but for switches (nullary flags).</li>
--   </ul>
type Name = Text

-- | An human-readable explanation of what the flag does. It is displayed
--   when the parser is invoked with the <tt>--help</tt> flag.
type Description = Text

-- | Flags parser.
--   
--   There are two types of flags:
--   
--   <ul>
--   <li>Nullary flags created with <a>switch</a> and <a>boolFlag</a>,
--   which do not accept a value.</li>
--   <li>Unary flags created with <a>flag</a> and its convenience variants
--   (e.g. <a>textFlag</a>, <a>autoFlag</a>, <a>autoListFlag</a>). These
--   expect a value to be passed in either after an equal sign
--   (<tt>--foo=value</tt>) or as the following input value (<tt>--foo
--   value</tt>). If the value starts with <tt>--</tt>, only the first form
--   is accepted.</li>
--   </ul>
--   
--   You can run a parser using <a>parseFlags</a> or
--   <a>parseSystemFlagsOrDie</a>.
data FlagParser a

-- | The possible parsing errors.
data FlagError

-- | A flag was declared multiple times.
DuplicateFlag :: Name -> FlagError

-- | The parser was empty.
EmptyParser :: FlagError

-- | The input included the <tt>--help</tt> flag.
Help :: Text -> FlagError

-- | At least one unary flag was specified multiple times with different
--   values.
InconsistentFlagValues :: Name -> FlagError

-- | A unary flag's value failed to parse.
InvalidFlagValue :: Name -> Text -> String -> FlagError

-- | A required flag was missing.
MissingFlag :: Name -> FlagError

-- | A unary flag was missing a value. This can happen either if a
--   value-less unary flag was the last token or was followed by a value
--   which is also a flag name (in which case you should use the
--   single-token form: <tt>--flag=--value</tt>).
MissingFlagValue :: Name -> FlagError

-- | A flag with a reserved name was declared.
ReservedFlag :: Name -> FlagError

-- | At least one flag was set but unused. This can happen when optional
--   flags are set but their branch is not selected.
UnexpectedFlags :: NonEmpty Name -> FlagError

-- | An unknown flag was set.
UnknownFlag :: Name -> FlagError

-- | Runs a parser on a list of tokens, returning the parsed flags
--   alongside other non-flag arguments (i.e. which don't start with
--   <tt>--</tt>). If the special <tt>--</tt> token is found, all following
--   tokens will be considered arguments even if they look like flags.
parseFlags :: FlagParser a -> [String] -> Either FlagError (a, [String])

-- | Runs a parser on the system's arguments, or exits with code 1 and
--   prints the relevant error message in case of failure.
parseSystemFlagsOrDie :: FlagParser a -> IO (a, [String])

-- | Returns a parser with the given name and description for a flag with
--   no value, failing if the flag is not present. See also <a>boolFlag</a>
--   for a variant which doesn't fail when the flag is missing.
switch :: Name -> Description -> FlagParser ()

-- | Returns a parser with the given name and description for a flag with
--   no value, returning whether the flag was present.
boolFlag :: Name -> Description -> FlagParser Bool

-- | Returns a parser using the given parsing function, name, and
--   description for a flag with an associated value.
flag :: (Text -> Either String a) -> Name -> Description -> FlagParser a

-- | Returns a parser for a single text value.
textFlag :: Name -> Description -> FlagParser Text

-- | Returns a parser for any value with a <a>Read</a> instance. Prefer
--   <a>textFlag</a> for textual values since <a>flag</a> will expect its
--   values to be double-quoted and might not work as expected.
autoFlag :: Read a => Name -> Description -> FlagParser a

-- | Returns a parser for a single flag with multiple text values.
textListFlag :: Text -> Name -> Description -> FlagParser [Text]

-- | Returns a parser for a single flag with multiple values having a
--   <a>Read</a> instance, with a configurable separator. Empty values are
--   always ignored, so it's possible to declare an empty list as
--   <tt>--list=</tt> and trailing commas are supported.
autoListFlag :: Read a => Text -> Name -> Description -> FlagParser [a]
instance GHC.Show.Show Flags.Applicative.FlagError
instance GHC.Classes.Eq Flags.Applicative.FlagError
instance GHC.Base.Functor Flags.Applicative.FlagParser
instance GHC.Show.Show Flags.Applicative.ParserError
instance GHC.Classes.Eq Flags.Applicative.ParserError
instance GHC.Classes.Ord Flags.Applicative.Usage
instance GHC.Classes.Eq Flags.Applicative.Usage
instance GHC.Classes.Eq Flags.Applicative.Arity
instance GHC.Base.Applicative Flags.Applicative.FlagParser
instance GHC.Base.Alternative Flags.Applicative.FlagParser