Flags.Applicative

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 :: FlagsParser Options
optionsParser = Options <$> textFlag "root" "path to the root"
                        <*> (autoFlag "log_level" "" <|> pure 0)
                        <*> (optional $ textFlag "context" "")

main :: IO ()
main = do
  (opts, args) <- parseSystemFlagsOrDie optionsParser
  print opts

Types

type Name = Text

The name of a flag (without the -- prefix). Names can use all valid utf-8 characters except = (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, displays usage when set.
• swallowed_flags, flags in this list which are set but undeclared will be ignored rather than cause an error during parsing.
• swallowed_switches, similar to swallowed_flags but for switches (nullary flags).

type Description = Text

An human-readable explanation of what the flag does. It is displayed when the parser is invoked with the --help flag.

data FlagsParser a

Flags parser.

There are two types of flags:

• Nullary flags created with switch and boolFlag, which do not accept a value.
• Unary flags created with flag and its convenience variants (e.g. textFlag, autoFlag, autoListFlag). 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 or parseSystemFlagsOrDie.

Instances

Functor FlagsParser

Defined in Flags.Applicative

Methods

fmap :: (a -> b) -> FlagsParser a -> FlagsParser b

(<$) :: a -> FlagsParser b -> FlagsParser a

Applicative FlagsParser

Defined in Flags.Applicative

Methods

pure :: a -> FlagsParser a

(<*>) :: FlagsParser (a -> b) -> FlagsParser a -> FlagsParser b

liftA2 :: (a -> b -> c) -> FlagsParser a -> FlagsParser b -> FlagsParser c

(*>) :: FlagsParser a -> FlagsParser b -> FlagsParser b

(<*) :: FlagsParser a -> FlagsParser b -> FlagsParser a

Alternative FlagsParser

Defined in Flags.Applicative

Methods

empty :: FlagsParser a

(<|>) :: FlagsParser a -> FlagsParser a -> FlagsParser a

some :: FlagsParser a -> FlagsParser [a]

many :: FlagsParser a -> FlagsParser [a]

data FlagError

The possible parsing errors.

Constructors

DuplicateFlag Name

A flag was declared multiple times.

EmptyParser

The parser was empty.

Help Text

The input included the --help flag.

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.

MissingFlags (NonEmpty Name)

A required flag was missing; at least one of the returned flags should be set.

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: --flag=--value).

ReservedFlag Name

A flag with a reserved name was declared.

UnexpectedFlagValue Name

A nullary flag was given a value.

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.

Instances

Eq FlagError

Defined in Flags.Applicative

Methods

(==) :: FlagError -> FlagError -> Bool

(/=) :: FlagError -> FlagError -> Bool

Show FlagError

Defined in Flags.Applicative

Methods

showsPrec :: Int -> FlagError -> ShowS

show :: FlagError -> String

showList :: [FlagError] -> ShowS

Running parsers

parseFlags :: FlagsParser a -> [String] -> Either FlagError (a, [String])

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 :: FlagsParser a -> IO (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.

Declaring flags

Nullary flags

switch :: Name -> Description -> FlagsParser ()

Returns a parser with the given name and description for a flag with no value, failing if the flag is not present. See also boolFlag for a variant which doesn't fail when the flag is missing.

boolFlag :: Name -> Description -> FlagsParser Bool

Returns a parser with the given name and description for a flag with no value, returning whether the flag was present.

Unary flags

flag :: (Text -> Either String a) -> Name -> Description -> FlagsParser a

Returns a parser using the given parsing function, name, and description for a flag with an associated value.

textFlag :: Name -> Description -> FlagsParser Text

Returns a parser for a single text value.

hostFlag :: Name -> Description -> FlagsParser (HostName, Maybe PortNumber)

Returns a parser for network hosts of the form hostname:port. The port part is optional.

autoFlag :: Read a => Name -> Description -> FlagsParser a

Returns a parser for any value with a Read instance. Prefer textFlag for textual values since flag will expect its values to be double-quoted and might not work as expected.

textListFlag :: Text -> Name -> Description -> FlagsParser [Text]

Returns a parser for a single flag with multiple text values.

autoListFlag :: Read a => Text -> Name -> Description -> FlagsParser [a]

Returns a parser for a single flag with multiple values having a Read instance, with a configurable separator. Empty values are always ignored, so it's possible to declare an empty list as --list= and trailing commas are supported.