-- 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.2.0


-- | 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; (flag "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, can use all valid utf-8 characters but <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>, used to display usage when set.</li>
--   </ul>
type Name = Text

-- | An human-readable explanation of what the flag does.
type Description = Text

-- | Flags parser.
--   
--   There are two types of flags:
--   
--   <ul>
--   <li>Nullary flags created with 'switch which are <a>True</a> when set
--   and <a>False</a> otherwise. For example <tt>--version</tt> or
--   <tt>--enable_foo</tt>.</li>
--   <li>Unary flags created with <a>unaryFlag</a> and its convenience
--   variants (e.g. <a>textFlag</a>, <a>flag</a>, <a>repeatedFlag</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>.
data FlagParser a

-- | The possible parsing errors.
data FlagError

-- | A flag was declared multiple times.
DuplicateFlag :: Name -> 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

-- | 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 nullary parser with the given name and description.
switch :: Name -> Description -> FlagParser Bool

-- | Returns a unary parser using the given parsing function, name, and
--   description.
unaryFlag :: (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.
flag :: Read a => Name -> Description -> FlagParser a

-- | Returns a parser for a multiple text value.
repeatedTextFlag :: Text -> Name -> Description -> FlagParser [Text]

-- | Returns a parser for multiple values with a <a>Read</a> instance, with
--   a configurable separator.
repeatedFlag :: 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