Options.Applicative.Builder (original) (raw)

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](/package/base-4.6.0.1/docs/Data-Monoid.html#t:Monoid) operations [mempty](/package/base-4.6.0.1/docs/Data-Monoid.html#v:mempty) and [mappend](Options-Applicative-Builder.html#v:mappend), or their aliases [idm](Options-Applicative-Builder.html#v:idm) and [<>](Options-Applicative-Builder.html#v:-60--62-).

For example:

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

creates a parser for an option called "output".

flagSource

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](Options-Applicative-Builder.html#v:switch) instead.

flag'Source

Builder for a flag parser without a default value.

Same as [flag](Options-Applicative-Builder.html#v: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.

Modifiers

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

Add a bash completion action. Common actions include file anddirectory. See http:www.gnu.org_software_bash_manual_html\_node/Programmable-Completion-Builtins.html#Programmable-Completion-Builtins for a complete list.

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

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.

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

Deprecated: Use () instead

Compose modifiers.

Readers

A collection of basic [Option](Options-Applicative-Types.html#t:Option) readers.

Builder for [ParserInfo](Options-Applicative-Types.html#t:ParserInfo)

Builder for [ParserPrefs](Options-Applicative-Types.html#t:ParserPrefs)

Types

data Mod f a Source

An option modifier.

Option modifiers are values that represent a modification of the properties of an option.

The type parameter a is the return type of the option, while f is a record containing its properties (e.g. [OptionFields](Options-Applicative-Builder.html#t:OptionFields) for regular options,[FlagFields](Options-Applicative-Builder.html#t:FlagFields) for flags, etc...).

An option modifier consists of 3 elements:

• A field modifier, of the form f a -> f a. These are essentially (compositions of) setters for some of the properties supported by f.
• An optional default value and function to display it.
• A property modifier, of the form OptProperties -> OptProperties. This is just like the field modifier, but for properties applicable to any option.

Modifiers are instances of [Monoid](/package/base-4.6.0.1/docs/Data-Monoid.html#t:Monoid), and can be composed as such.

You rarely need to deal with modifiers directly, as most of the times it is sufficient to pass them to builders (such as strOption or flag) to create options (see [Builder](Options-Applicative.html#t:Builder)).