Safe Haskell | Safe |
---|---|
Language | Haskell2010 |
Simple flags parsing module, inspired by optparse-applicative
.
Sample usage (note the default log level and optional context):
module Main where import Control.Applicative ((<|>), 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 <$> textFlag "root" "path to the root" <*> (flag "log_level" "" <|> pure 0) <*> (optional $ textFlag "context" "") main :: IO () main = do (opts, args) <- parseSystemFlagsOrDie optionsParser print opts
Synopsis
- type Name = Text
- type Description = Text
- data FlagParser a
- data FlagError
- parseFlags :: FlagParser a -> [String] -> Either FlagError (a, [String])
- parseSystemFlagsOrDie :: FlagParser a -> IO (a, [String])
- switch :: Name -> Description -> FlagParser Bool
- unaryFlag :: (Text -> Either String a) -> Name -> Description -> FlagParser a
- textFlag :: Name -> Description -> FlagParser Text
- flag :: Read a => Name -> Description -> FlagParser a
- repeatedTextFlag :: Text -> Name -> Description -> FlagParser [Text]
- repeatedFlag :: Read a => Text -> Name -> Description -> FlagParser [a]
Documentation
The name of a flag, can use all valid utf-8 characters but =
(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:
help
, used to display usage when set.
type Description = Text Source #
An human-readable explanation of what the flag does.
data FlagParser a Source #
Flags parser.
There are two types of flags:
- Nullary flags created with 'switch which are
True
when set andFalse
otherwise. For example--version
or--enable_foo
. - Unary flags created with
unaryFlag
and its convenience variants (e.g.textFlag
,flag
,repeatedFlag
). These expect a value to be passed in either after an equal sign (--foo=value
) or as the following input value (--foo value
). If the value starts with--
, only the first form is accepted.
You can run a parser using parseFlags
.
Instances
Functor FlagParser Source # | |
Defined in Flags.Applicative fmap :: (a -> b) -> FlagParser a -> FlagParser b # (<$) :: a -> FlagParser b -> FlagParser a # | |
Applicative FlagParser Source # | |
Defined in Flags.Applicative pure :: a -> FlagParser a # (<*>) :: FlagParser (a -> b) -> FlagParser a -> FlagParser b # liftA2 :: (a -> b -> c) -> FlagParser a -> FlagParser b -> FlagParser c # (*>) :: FlagParser a -> FlagParser b -> FlagParser b # (<*) :: FlagParser a -> FlagParser b -> FlagParser a # | |
Alternative FlagParser Source # | |
Defined in Flags.Applicative empty :: FlagParser a # (<|>) :: FlagParser a -> FlagParser a -> FlagParser a # some :: FlagParser a -> FlagParser [a] # many :: FlagParser a -> FlagParser [a] # |
The possible parsing errors.
DuplicateFlag Name | A flag was declared multiple times. |
Help Text | The input included the |
InconsistentFlagValues Name | At least one unary flag was specified multiple times with different values. |
InvalidFlagValue Name Text String | A unary flag's value failed to parse. |
MissingFlag Name | A required flag was missing. |
MissingFlagValue Name | 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: |
UnexpectedFlags (NonEmpty Name) | At least one flag was set but unused. This can happen when optional flags are set but their branch is not selected. |
UnknownFlag Name | An unknown flag was set. |
parseFlags :: FlagParser a -> [String] -> Either FlagError (a, [String]) Source #
Runs a parser on a list of tokens, returning the parsed flags alongside other non-flag
arguments (i.e. which don't start with --
). If the special --
token is found, all following
tokens will be considered arguments (even if they look like flags).
parseSystemFlagsOrDie :: FlagParser a -> IO (a, [String]) Source #
Runs a parser on the system's arguments, or exits with code 1 and prints the relevant error message in case of failure.
Defining flags
switch :: Name -> Description -> FlagParser Bool Source #
Returns a nullary parser with the given name and description.
unaryFlag :: (Text -> Either String a) -> Name -> Description -> FlagParser a Source #
Returns a unary parser using the given parsing function, name, and description.
textFlag :: Name -> Description -> FlagParser Text Source #
Returns a parser for a single text value.
flag :: Read a => Name -> Description -> FlagParser a Source #
repeatedTextFlag :: Text -> Name -> Description -> FlagParser [Text] Source #
Returns a parser for a multiple text value.
repeatedFlag :: Read a => Text -> Name -> Description -> FlagParser [a] Source #
Returns a parser for multiple values with a Read
instance, with a configurable separator.