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. A modifier can be created by composing the basic modifiers provided by this module using the Monoid operations mempty and mappend, or their aliases idm and &.

For example:

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

creates a parser for an option called "output".

subparser :: Mod CommandFields a -> Parser a

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

argument :: (String -> Maybe a) -> Mod ArgumentFields a -> Parser a

Builder for an argument parser ignoring arguments starting with -.

argument' :: (String -> Maybe a) -> Mod ArgumentFields a -> Parser a

Builder for an argument parser.

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

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

arguments1 :: (String -> Maybe a) -> Mod ArgumentFields [a] -> Parser [a]

Like arguments, but require at least one argument.

flag

Arguments

:: a

default value

-> a

active value

-> Mod FlagFields a

option modifier

-> Parser a

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

option modifier

-> Parser a

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

Builder for a boolean flag.

 switch = flag False True

nullOption :: Mod OptionFields a -> Parser a

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

strOption :: Mod OptionFields String -> Parser String

Builder for an option taking a String argument.

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

Builder for an option using the auto reader.

Modifiers

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

Specify a short name for an option.

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

Specify a long name for an option.

help :: String -> Mod f a

Specify the help text for an option.

value :: a -> Mod f a

Specify a default value for an option.

showDefaultWith :: (a -> String) -> Mod f a

Specify a function to show the default value for an option.

showDefault :: Show a => Mod f a

Show the default value for this option using its Show instance.

metavar :: String -> Mod f a

Specify the metavariable.

reader :: (String -> Either ParseError a) -> Mod OptionFields a

Specify the Option reader.

noArgError :: ParseError -> Mod OptionFields a

Specify the error to display when no argument is provided to this option.

data ParseError

Constructors

ErrorMsg String

ShowHelpText

Instances

Show ParseError

Error ParseError

hidden :: Mod f a

Hide this option from the brief description.

internal :: Mod f a

Hide this option from the help text

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

Add a command to a subparser option.

completeWith :: HasCompleter f => [String] -> Mod f a

Add a list of possible completion values.

action :: HasCompleter f => String -> Mod f a

Add a bash completion action. Common actions include file and directory. See http:www.gnu.orgsoftwarebashmanualhtml_node/Programmable-Completion-Builtins.html#Programmable-Completion-Builtins for a complete list.

completer :: HasCompleter f => Completer -> Mod f a

Add a completer to an argument.

A completer is a function String -> IO String which, given a partial argument, returns all possible completions for that argument.

idm :: Monoid m => m

Trivial option modifier.

(&) :: Monoid m => m -> m -> m

Deprecated: Use (<>) instead

Compose modifiers.

(<>) :: Monoid m => m -> m -> m

An infix synonym for mappend.

Readers

A collection of basic Option readers.

auto :: Monad m => Read a => String -> m a

Option reader based on the Read type class.

str :: Monad m => String -> m String

String Option reader.

disabled :: Monad m => String -> m a

Null Option reader. All arguments will fail validation.

Builder for ParserInfo

data InfoMod a

Modifier for ParserInfo.

Instances

Monoid (InfoMod a)

fullDesc :: InfoMod a

Show a full description in the help text of this parser.

briefDesc :: InfoMod a

Only show a brief description in the help text of this parser.

header :: String -> InfoMod a

Specify a header for this parser.

progDesc :: String -> InfoMod a

Specify a short program description.

footer :: String -> InfoMod a

Specify a footer for this parser.

failureCode :: Int -> InfoMod a

Specify an exit code if a parse error occurs.

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

Create a ParserInfo given a Parser and a modifier.

Builder for ParserPrefs

data PrefsMod

Instances

Monoid PrefsMod

multiSuffix :: String -> PrefsMod

disambiguate :: PrefsMod

showHelpOnError :: PrefsMod

noBacktrack :: PrefsMod

prefs :: PrefsMod -> ParserPrefs