-- 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.1.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 Data.Text.Read (decimal)
--   import Flags.Applicative
--   import System.Environment (getArgs)
--   
--   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; (numericFlag decimal "log_level" "" &lt;|&gt; pure 0)
--                           &lt;*&gt; (optional $ textFlag "context" "")
--   
--   main :: IO ()
--   main = do
--     args &lt;- getArgs
--     print $ parseFlags optionsParser args
--   </pre>
module Flags.Applicative

-- | The name of a flag, can use all characters but <tt>=</tt> (the value
--   delimiter). It's good practice for flag names to be lowercase ASCII
--   with underscores.
type Name = Text

-- | Flags parser.
--   
--   There are two types of flags:
--   
--   <ul>
--   <li>Nullary flags created with <a>boolFlag</a> which are <a>True</a>
--   when set and <a>False</a> otherwise (a.k.a. switches). 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>numericFlag</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

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

-- | The parser is invalid. Unlike other <a>FlagError</a> constructors,
--   this indicates an issue with the parser's declaration (rather than the
--   input tokens).
InvalidParser :: ParserError -> 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

-- | Parser definition errors.
data ParserError

-- | The same flag name was declared multiple times.
DuplicateFlag :: Name -> ParserError

-- | The parser is empty (this should not happen if you use standard
--   combinators).
Empty :: ParserError

-- | 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, [Text])

-- | Returns a nullary parser with the given name and description.
boolFlag :: Name -> Text -> FlagParser Bool

-- | Returns a unary parser using the given parsing function, name, and
--   description.
unaryFlag :: (Text -> Either String a) -> Name -> Text -> FlagParser a

-- | Returns a flag with <a>Text</a> values.
textFlag :: Name -> Text -> FlagParser Text

-- | Returns a flag which can parse numbers using the helper methods in
--   <a>Data.Text.Read</a> (e.g. <a>decimal</a>).
numericFlag :: Reader a -> Name -> Text -> 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.Eq Flags.Applicative.Arity
instance GHC.Base.Applicative Flags.Applicative.FlagParser
instance GHC.Base.Alternative Flags.Applicative.FlagParser