Options.Applicative.Builder

Parser builders

This module contains utility functions and combinators to create parsers for individual options.

Each parser builder takes an option modifier, which can be specified by composing basic modifiers using & and idm (which are just convenient synonyms for the Category operations >>> and id).

For example:

 out = strOption
     ( long "output"
     & short 'o'
     & metavar "FILENAME" )

creates a parser for an option called "output".

subparser :: Mod CommandFields a b -> Parser b

Builder for a command parser. The command modifier can be used to specify individual commands.

argument :: (String -> Maybe a) -> Mod Identity a b -> Parser b

Builder for an argument parser.

arguments :: (String -> Maybe a) -> Mod Identity a b -> Parser [b]

Builder for an argument list parser. All arguments are collected and returned as a list.

Note that arguments starting with - are ignored.

This parser accepts a special argument: --. When a -- is found on the command line, all following arguments are included in the result, even if they start with -.

flag

Arguments

:: a

default value

-> a

active value

-> Mod FlagFields a b

option modifier

-> Parser b

Builder for a flag parser.

A flag that switches from a "default value" to an "active value" when encountered. For a simple boolean value, use switch instead.

flag'

Arguments

:: a

active value

-> Mod FlagFields a b

option modifier

-> Parser b

Builder for a flag parser without a default value.

Same as flag, but with no default value. In particular, this flag will never parse successfully by itself.

It still makes sense to use it as part of a composite parser. For example

 length <$> many (flag' () (short 't'))

is a parser that counts the number of -t arguments on the command line.

switch :: Mod FlagFields Bool a -> Parser a

Builder for a boolean flag.

 switch = flag False True

nullOption :: Mod OptionFields a b -> Parser b

Builder for an option with a null reader. A non-trivial reader can be added using the reader modifier.

strOption :: Mod OptionFields String a -> Parser a

Builder for an option taking a String argument.

option :: Read a => Mod OptionFields a b -> Parser b

Builder for an option using the auto reader.

Modifiers

short :: HasName f => Char -> Mod f a a

Specify a short name for an option.

long :: HasName f => String -> Mod f a a

Specify a long name for an option.

help :: String -> Mod f a a

Specify the help text for an option.

value :: a -> Mod f a a

Specify a default value for an option.

metavar :: String -> Mod f a a

Specify the metavariable.

reader :: (String -> Maybe a) -> Mod OptionFields a a

Specify the Option reader.

hidden :: Mod f a a

Hide this option from the brief description.

internal :: Mod f a a

Hide this option from the help text

transform :: Functor f => (a -> b) -> Mod f a b

Apply a transformation to the return value of this option.

This can be used, for example, to provide a default value for a required option, like:

strOption
( transform Just
& value Nothing )

command :: String -> ParserInfo a -> Mod CommandFields a a

Add a command to a subparser option.

idm :: Category hom => hom a a

Trivial option modifier.

(&) :: Category hom => hom a b -> hom b c -> hom a c

Compose modifiers.

Readers

A collection of basic Option readers.

auto :: Read a => String -> Maybe a

Option reader based on the Read type class.

str :: String -> Maybe String

String Option reader.

disabled :: String -> Maybe a

Null Option reader. All arguments will fail validation.

Internals

data Mod f a b

Instances

Category (Mod f)

class HasName f

Instances

HasName FlagFields

HasName OptionFields

data OptionFields a

Instances

Functor OptionFields

HasName OptionFields

data FlagFields a

Instances

Functor FlagFields

HasName FlagFields

data CommandFields a

Instances

Functor CommandFields

Builder for ParserInfo

data InfoMod a b

Modifier for ParserInfo.

Instances

Category InfoMod

fullDesc :: InfoMod a a

Specify a full description for this parser.

header :: String -> InfoMod a a

Specify a header for this parser.

progDesc :: String -> InfoMod a a

Specify a short program description.

footer :: String -> InfoMod a a

Specify a footer for this parser.

failureCode :: Int -> InfoMod a a

Specify an exit code if a parse error occurs.

info :: Parser a -> InfoMod a a -> ParserInfo a

Create a ParserInfo given a Parser and a modifier.

Builder for ParserPrefs

type PrefsMod = PrefsModC ParserPrefs ParserPrefs

Modifier for ParserPrefs.

multiSuffix :: String -> PrefsMod

prefs :: PrefsMod -> ParserPrefs