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


-- | This module implements a lightweight flags parser, 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
--   
--   -- Custom flags for our example.
--   data Flags = Flags
--     { rootPath :: Text
--     , logLevel :: Int
--     , context :: Maybe Text
--     } deriving Show
--   
--   -- Returns a parser from CLI arguments to our custom flags.
--   flagsParser :: FlagsParser Flags
--   flagsParser = Flags
--     &lt;$&gt; flag textVal "root" "path to the root"
--     &lt;*&gt; (flag autoVal "log_level" "" &lt;|&gt; pure 0)
--     &lt;*&gt; (optional $ flag textVal "context" "")
--   
--   main :: IO ()
--   main = do
--     (flags, args) &lt;- parseSystemFlagsOrDie flagsParser
--     print flags
--   </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

-- | 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 -> FlagsParser ()

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

-- | Returns a parser using the given value reader, name, and description
--   for a flag with an associated value.
flag :: Reader a -> Name -> Description -> FlagsParser a

-- | The type used to read flag values.
type Reader a = Text -> Either String a

-- | Returns a reader for any value with a <a>Read</a> instance. Prefer
--   <a>textVal</a> for textual values since <a>autoVal</a> will expect its
--   values to be double-quoted and might not work as expected.
autoVal :: Read a => Reader a

-- | Returns a reader for a single text value.
textVal :: Reader Text

-- | Returns a reader for a single string value. This can useful when
--   interfacing with non-text APIs (e.g. <a>FilePath</a>) but in general
--   prefer <a>textVal</a>.
stringVal :: Reader String

-- | Returns a reader for any number with a <a>Fractional</a> instance
--   (e.g. <a>Double</a>, <a>Float</a>).
fracVal :: Fractional a => Reader a

-- | Returns a reader for any number with an 'Integral instance (e.g.
--   <a>Int</a>, <a>Integer</a>).
intVal :: Integral a => Reader a

-- | Returns a reader for <a>Enum</a> instances. This reader assumes that
--   enum (Haskell) constructors are written in PascalCase and expects
--   UPPER_SNAKE_CASE as command-line flag values. For example:
--   
--   <pre>
--   data Mode = Flexible | Strict deriving (Bounded, Enum, Show)
--   modeFlag = flag enumVal "mode" "the mode" :: FlagsParser Mode
--   </pre>
--   
--   The above flag will accept values <tt>--mode=FLEXIBLE</tt> and
--   <tt>--mode=STRICT</tt>.
enumVal :: (Bounded a, Enum a, Show a) => Reader a

-- | Returns a reader for network hosts of the form <tt>hostname:port</tt>.
--   The port part is optional.
hostVal :: Reader (HostName, Maybe PortNumber)

-- | Transforms a single-valued unary flag into one which accepts multiple
--   comma-separated values. For example, to parse a comma-separated list
--   of integers:
--   
--   <pre>
--   countsFlag = flag (listOf intVal) "counts" "the counts"
--   </pre>
--   
--   Empty text values are ignored, which means both that trailing commas
--   are supported and that an empty list can be specified simply by
--   specifying an empty value on the command line. Note that escapes are
--   not supported, so values should not contain any commas.
listOf :: Reader a -> Reader [a]

-- | Transforms a single-valued unary flag into one which accepts a
--   comma-separated list of colon-delimited key-value pairs. The syntax is
--   <tt>key:value[,key:value...]</tt>. Note that escapes are not
--   supported, so neither keys not values should contain colons or commas.
mapOf :: Ord a => Reader a -> Reader b -> Reader (Map a b)

-- | 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>. 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 FlagsParser a

-- | The possible parsing errors.
data FlagsError

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

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

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

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

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

-- | A required flag was missing; at least one of the returned flags should
--   be set.
MissingFlags :: NonEmpty Name -> FlagsError

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

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

-- | A nullary flag was given a value.
UnexpectedFlagValue :: Name -> FlagsError

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

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

-- | 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 :: FlagsParser a -> [String] -> Either FlagsError (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 :: FlagsParser a -> IO (a, [String])
instance GHC.Classes.Eq Flags.Applicative.Arity
instance GHC.Classes.Ord Flags.Applicative.Usage
instance GHC.Classes.Eq Flags.Applicative.Usage
instance GHC.Show.Show Flags.Applicative.ParserError
instance GHC.Classes.Eq Flags.Applicative.ParserError
instance GHC.Base.Functor Flags.Applicative.FlagsParser
instance GHC.Show.Show Flags.Applicative.FlagsError
instance GHC.Classes.Eq Flags.Applicative.FlagsError
instance GHC.Base.Applicative Flags.Applicative.FlagsParser
instance GHC.Base.Alternative Flags.Applicative.FlagsParser