HORIZON HASKELLDocslts/ghc-9.10.x248f8f02026-10-05Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · 248f8f0 · 2026-10-05

Moduleoptparse-applicative-0.18.1.0Haskell98

Options.Applicative

  • 21 types
  • 6 classes
  • 80 values

Applicative option parsers

0 declarations

This module exports all one should need for defining and using optparse-applicative command line option parsers.

See https://github.com/pcapriotti/optparse-applicative for a tutorial, and a general introduction to applicative option parsers.

See the sections below for more detail

Exported modules

13 declarations

The standard Applicative module is re-exported here for convenience.

classclass Functor f => Applicative (f :: Type -> Type) where
#

A functor with application, providing operations to

  • embed pure expressions (pure), and

  • sequence computations and combine their results (<*> and liftA2).

A minimal complete definition must include implementations of pure and of either <*> or liftA2. If it defines both, then they must behave the same as their default definitions:

(<*>) = liftA2 id
liftA2 f x y = f Prelude.<$> x <*> y

Further, any definition must satisfy the following:

Identity
pure id <*> v = v
Composition
pure (.) <*> u <*> v <*> w = u <*> (v <*> w)
Homomorphism
pure f <*> pure x = pure (f x)
Interchange
u <*> pure y = pure ($ y) <*> u

The other methods have the following default definitions, which may be overridden with equivalent specialized implementations:

As a consequence of these laws, the Functor instance for f will satisfy

It may be useful to note that supposing

forall x y. p (q x y) = f x . g y

it follows from the above that

liftA2 p (liftA2 q u v) = liftA2 f u . liftA2 g v

If f is also a Monad, it should satisfy

(which implies that pure and <*> satisfy the applicative functor laws).

Methods

  • pure :: a -> f a

    Lift a value into the Structure.

    Examples
    Example1 expression
    pure 1 :: Maybe IntJust 1
    Example1 expression
    pure 'z' :: [Char]"z"
    Example1 expression
    pure (pure ":D") :: Maybe [String]Just [":D"]
  • (<*>) :: f (a -> b) -> f a -> f binfixl 4

    Sequential application.

    A few functors support an implementation of <*> that is more efficient than the default one.

    Example

    Used in combination with (Data.Functor.<$>), (<*>) can be used to build a record.

    Example1 expression
    data MyState = MyState {arg1 :: Foo, arg2 :: Bar, arg3 :: Baz}
    Example3 expressions
    produceFoo :: Applicative f => f FooproduceBar :: Applicative f => f BarproduceBaz :: Applicative f => f Baz
    Example2 expressions
    mkState :: Applicative f => f MyStatemkState = MyState <$> produceFoo <*> produceBar <*> produceBaz
  • liftA2 :: (a -> b -> c) -> f a -> f b -> f c

    Lift a binary function to actions.

    Some functors support an implementation of liftA2 that is more efficient than the default one. In particular, if fmap is an expensive operation, it is likely better to use liftA2 than to fmap over the structure and then use <*>.

    This became a typeclass method in 4.10.0.0. Prior to that, it was a function defined in terms of <*> and fmap.

    Example
    Example1 expression
    liftA2 (,) (Just 3) (Just 5)Just (3,5)
    Example1 expression
    liftA2 (+) [1, 2, 3] [4, 5, 6][5,6,7,6,7,8,7,8,9]
  • (*>) :: f a -> f b -> f binfixl 4

    Sequence actions, discarding the value of the first argument.

    Examples

    If used in conjunction with the Applicative instance for Maybe, you can chain Maybe computations, with a possible "early return" in case of Nothing.

    Example1 expression
    Just 2 *> Just 3Just 3
    Example1 expression
    Nothing *> Just 3Nothing

    Of course a more interesting use case would be to have effectful computations instead of just returning pure values.

    Example4 expressions
    import Data.Charimport GHC.Internal.Text.ParserCombinators.ReadPlet p = string "my name is " *> munch1 isAlpha <* eofreadP_to_S p "my name is Simon"[("Simon","")]
  • (<*) :: f a -> f b -> f ainfixl 4

    Sequence actions, discarding the value of the second argument.

Instances101Applicative, …
valueasum :: (Foldable t, Alternative f) => t (f a) -> f a
#

The sum of a collection of actions using (<|>), generalizing concat.

asum is just like msum, but generalised to Alternative.

Examples

Basic usage:

Example1 expression
asum [Just "Hello", Nothing, Just "World"]Just "Hello"
value(<$>) :: Functor f => (a -> b) -> f a -> f b
#

An infix synonym for fmap.

The name of this operator is an allusion to Prelude.$. Note the similarities between their types:

 ($)  ::              (a -> b) ->   a ->   b
(<$>) :: Functor f => (a -> b) -> f a -> f b

Whereas Prelude.$ is function application, <$> is function application lifted over a Functor.

Examples

Convert from a Maybe Int to a Maybe String using show:

Example1 expression
show <$> NothingNothing
Example1 expression
show <$> Just 3Just "3"

Convert from an Either Int Int to an Either Int String using show:

Example1 expression
show <$> Left 17Left 17
Example1 expression
show <$> Right 17Right "17"

Double each element of a list:

Example1 expression
(*2) <$> [1,2,3][2,4,6]

Apply even to the second element of a pair:

Example1 expression
even <$> (2,2)(2,True)
method(<$) :: a -> f b -> f a
#

Replace all locations in the input with the same value. The default definition is fmap . const, but this may be overridden with a more efficient version.

Examples

Perform a computation with Maybe and replace the result with a constant value if it is Just:

Example2 expressions
'a' <$ Just 2Just 'a''a' <$ NothingNothing
classclass Applicative f => Alternative (f :: Type -> Type) where
#

A monoid on applicative functors.

If defined, some and many should be the least solutions of the equations:

Examples
Example1 expression
Nothing <|> Just 42Just 42
Example1 expression
[1, 2] <|> [3, 4][1,2,3,4]
Example1 expression
empty <|> print (2^15)32768

Methods

  • empty :: f a

    The identity of <|>

    empty <|> a     == a
a     <|> empty == a
  • (<|>) :: f a -> f a -> f ainfixl 3

    An associative binary operation

  • some :: f a -> f [a]

    One or more.

    Examples
    Example1 expression
    some (putStr "la")lalalalalalalalala... * goes on forever *
    Example1 expression
    some Nothingnothing
    Example1 expression
    take 5 <$> some (Just 1)* hangs forever *

    Note that this function can be used with Parsers based on Applicatives. In that case some parser will attempt to parse parser one or more times until it fails.

  • many :: f a -> f [a]

    Zero or more.

    Examples
    Example1 expression
    many (putStr "la")lalalalalalalalala... * goes on forever *
    Example1 expression
    many NothingJust []
    Example1 expression
    take 5 <$> many (Just 1)* hangs forever *

    Note that this function can be used with Parsers based on Applicatives. In that case many parser will attempt to parse parser zero or more times until it fails.

Instances51Alternative, …
value(<**>) :: Applicative f => f a -> f (a -> b) -> f b
#

A variant of <*> with the types of the arguments reversed. It differs from flip (<*>) in that the effects are resolved in the order the arguments are presented.

Examples
Example1 expression
(<**>) (print 1) (id <$ print 2)12
Example1 expression
flip (<*>) (print 1) (id <$ print 2)21
Example1 expression
ZipList [4, 5, 6] <**> ZipList [(+1), (*2), (/3)]ZipList {getZipList = [5.0,10.0,2.0]}
valueliftA :: Applicative f => (a -> b) -> f a -> f b
#

Lift a function to actions. Equivalent to Functor's fmap but implemented using only Applicative's methods: liftA f a = pure f <*> a

As such this function may be used to implement a Functor instance from an Applicative one.

Examples

Using the Applicative instance for Lists:

Example1 expression
liftA (+1) [1, 2][2,3]

Or the Applicative instance for Maybe

Example1 expression
liftA (+1) (Just 3)Just 4
valueliftA3 :: Applicative f => (a -> b -> c -> d) -> f a -> f b -> f c -> f d
#

Lift a ternary function to actions.

newtypenewtype Const a (b :: k)
#

The Const functor.

Examples
Example1 expression
fmap (++ "World") (Const "Hello")Const "Hello"

Because we ignore the second type parameter to Const, the Applicative instance, which has (<*>) :: Monoid m => Const m (a -> b) -> Const m a -> Const m b essentially turns into Monoid m => m -> m -> m, which is (<>)

Example1 expression
Const [1, 2, 3] <*> Const [4, 5, 6]Const [1,2,3,4,5,6]

Constructors

Instances46Generic1, Bifoldable, Bifoldable1, Bifunctor, Bitraversable, Eq2, …
newtypenewtype WrappedArrow (a :: Type -> Type -> Type) b c
#

Constructors

Instances8Generic1, Functor, Applicative, Alternative, Data, Generic, …
newtypenewtype WrappedMonad (m :: Type -> Type) a
#

Constructors

Instances9Generic1, Monad, Functor, Applicative, Alternative, Data, …
valueoptional :: Alternative f => f a -> f (Maybe a)
#

One or none.

It is useful for modelling any computation that is allowed to fail.

Examples

Using the Alternative instance of Control.Monad.Except, the following functions:

Example1 expression
import Control.Monad.Except
Example2 expressions
canFail = throwError "it failed" :: Except String Intfinal = return 42                :: Except String Int

Can be combined by allowing the first function to fail:

Example1 expression
runExcept $ canFail *> finalLeft "it failed"
Example1 expression
runExcept $ optional canFail *> finalRight 42
newtypenewtype ZipList a
#

Lists, but with an Applicative functor based on zipping.

Examples

In contrast to the Applicative for GHC.List.List:

Example1 expression
(+) <$> [1, 2, 3] <*> [4, 5, 6][5,6,7,6,7,8,7,8,9]

The Applicative instance of ZipList applies the operation by pairing up the elements, analogous to zipWithN

Example1 expression
(+) <$> ZipList [1, 2, 3] <*> ZipList [4, 5, 6]ZipList {getZipList = [5,7,9]}
Example1 expression
(,,,) <$> ZipList [1, 2] <*> ZipList [3, 4] <*> ZipList [5, 6] <*> ZipList [7, 8]ZipList {getZipList = [(1,3,5,7),(2,4,6,8)]}
Example1 expression
ZipList [(+1), (^2), (/ 2)] <*> ZipList [5, 5, 5]ZipList {getZipList = [6.0,25.0,2.5]}

Constructors

Instances18Functor, Applicative, Foldable, Traversable, Alternative, NFData1, …
  • Functor ZipListDefined in ghc-internal-9.1003.0 · GHC.Internal.Functor.ZipList
  • Applicative ZipListDefined in ghc-internal-9.1003.0 · GHC.Internal.Functor.ZipList
    f <$> ZipList xs1 <*> ... <*> ZipList xsN
    = ZipList (zipWithN f xs1 ... xsN)

    where zipWithN refers to the zipWith function of the appropriate arity (zipWith, zipWith3, zipWith4, ...). For example:

    (\a b c -> stimes c [a, b]) <$> ZipList "abcd" <*> ZipList "567" <*> ZipList [1..]
    = ZipList (zipWith3 (\a b c -> stimes c [a, b]) "abcd" "567" [1..])
    = ZipList {getZipList = ["a5","b6b6","c7c7c7"]}
  • Foldable ZipListDefined in ghc-internal-9.1003.0 · GHC.Internal.Functor.ZipList
  • Traversable ZipListDefined in ghc-internal-9.1003.0 · GHC.Internal.Functor.ZipList
  • Alternative ZipListDefined in ghc-internal-9.1003.0 · GHC.Internal.Functor.ZipList
  • NFData1 ZipListDefined in deepseq-1.5.0.0 · Control.DeepSeq
  • Generic1 ZipListDefined in ghc-internal-9.1003.0 · GHC.Internal.Functor.ZipList
  • IsList (ZipList a)Defined in ghc-internal-9.1003.0 · GHC.Internal.IsList
  • Eq a => Eq (ZipList a)Defined in ghc-internal-9.1003.0 · GHC.Internal.Functor.ZipList
  • Data a => Data (ZipList a)Defined in ghc-internal-9.1003.0 · GHC.Internal.Functor.ZipList
  • Ord a => Ord (ZipList a)Defined in ghc-internal-9.1003.0 · GHC.Internal.Functor.ZipList
  • Read a => Read (ZipList a)Defined in ghc-internal-9.1003.0 · GHC.Internal.Functor.ZipList
  • Show a => Show (ZipList a)Defined in ghc-internal-9.1003.0 · GHC.Internal.Functor.ZipList
  • Generic (ZipList a)Defined in ghc-internal-9.1003.0 · GHC.Internal.Functor.ZipList
  • NFData a => NFData (ZipList a)Defined in deepseq-1.5.0.0 · Control.DeepSeq
  • type Rep (ZipList a) = D1 ('MetaData "ZipList" "GHC.Internal.Functor.ZipList" "ghc-internal" 'True) (C1 ('MetaCons "ZipList" 'PrefixI 'True) (S1 ('MetaSel ('Just "getZipList") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [a])))Defined in ghc-internal-9.1003.0 · GHC.Internal.Functor.ZipList
  • type Rep1 ZipList = D1 ('MetaData "ZipList" "GHC.Internal.Functor.ZipList" "ghc-internal" 'True) (C1 ('MetaCons "ZipList" 'PrefixI 'True) (S1 ('MetaSel ('Just "getZipList") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec1 [])))Defined in ghc-internal-9.1003.0 · GHC.Internal.Functor.ZipList
  • type Item (ZipList a) = aDefined in ghc-internal-9.1003.0 · GHC.Internal.IsList

Option Parsers

1 declaration

A Parser is the core type in optparse-applicative. A value of type Parser a represents a specification for a set of options, which will yield a value of type a when the command line arguments are successfully parsed.

There are several types of primitive Parser.

  • Flags: simple no-argument options. When a flag is encountered on the command line, its value is returned.

  • Options: options with an argument. An option can define a reader, which converts its argument from String to the desired value, or throws a parse error if the argument does not validate correctly.

  • Arguments: positional arguments, validated in the same way as option arguments.

  • Commands. A command defines a completely independent sub-parser. When a command is encountered, the whole command line is passed to the corresponding parser.

See the "Parser Builders" section for how to construct and customise these parsers.

datadata Parser a
#

A Parser a is an option parser returning a value of type a.

Instances3Functor, Applicative, Alternative
  • Functor ParserDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Types
  • Applicative ParserDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Types
  • Alternative ParserDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Types

Parser builders

This section 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 here 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".

valueflag
  1. :: a

    default value

  2. -> a

    active value

  3. -> Mod FlagFields a

    option modifier

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

Note: Because this parser will never fail, it can not be used with combinators such as some or many, as these combinators continue until a failure occurs. See flag'.

valueflag'
  1. :: a

    active value

  2. -> Mod FlagFields a

    option modifier

  3. -> 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, alternatively

flag' True (long "on") <|> flag' False (long "off")

will require the user to enter '--on' or '--off' on the command line.

valueswitch :: Mod FlagFields Bool -> Parser Bool
#

Builder for a boolean flag.

Note: Because this parser will never fail, it can not be used with combinators such as some or many, as these combinators continue until a failure occurs. See flag'.

switch = flag False True
valueoption :: ReadM a -> Mod OptionFields a -> Parser a
#

Builder for an option using the given reader.

This is a regular option, and should always have either a long or short name specified in the modifiers (or both).

nameParser = option str ( long "name" <> short 'n' )
valuesubparser :: Mod CommandFields a -> Parser a
#

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

By default, sub-parsers allow backtracking to their parent's options when they are completed. To allow full mixing of parent and sub-parser options, turn on subparserInline; otherwise, to disable backtracking completely, use noBacktrack.

valueabortOption :: ParseError -> Mod OptionFields (a -> a) -> Parser (a -> a)
#

An option that always fails.

When this option is encountered, the option parser immediately aborts with the given parse error. If you simply want to output a message, use infoOption instead.

valuehelper :: Parser (a -> a)
#

A hidden "helper" option which always fails.

A common usage pattern is to apply this applicatively when creating a ParserInfo

opts :: ParserInfo Sample
opts = info (sample <**> helper) mempty
valuesimpleVersioner
  1. :: String

    Version string to be shown

  2. -> Parser (a -> a)
#

A hidden "--version" option that displays the version.

opts :: ParserInfo Sample
opts = info (sample <**> simpleVersioner "v1.2.3") mempty

Modifiers

Parser builders take a modifier, which represents a modification of the properties of an option, and can be composed as a monoid.

Contraints are often used to ensure that the modifiers can be sensibly applied. For example, positional arguments can't be specified by long or short names, so the HasName constraint is used to ensure we have a flag or option.

datadata Mod (f :: Type -> Type) a
#

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 for regular options, 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, and can be composed as such.

One rarely needs 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 Options.Applicative.Builder).

Instances2Semigroup, Monoid
  • Semigroup (Mod f a)Defined in optparse-applicative-0.18.1.0 · Options.Applicative.Builder.Internal
  • Monoid (Mod f a)Defined in optparse-applicative-0.18.1.0 · Options.Applicative.Builder.Internal
valuehelp :: String -> Mod f a
#

Specify the help text for an option.

valuehelpDoc :: Maybe Doc -> Mod f a
#

Specify the help text for an option as a 'Prettyprinter.Doc AnsiStyle' value.

valuevalue :: HasValue f => a -> Mod f a
#

Specify a default value for an option.

Note: Because this modifier means the parser will never fail, do not use it with combinators such as some or many, as these combinators continue until a failure occurs. Careless use will thus result in a hang.

To display the default value, combine with showDefault or showDefaultWith.

valuemetavar :: HasMetavar f => String -> Mod f a
#

Specify a metavariable for the argument.

Metavariables have no effect on the actual parser, and only serve to specify the symbolic name for an argument to be displayed in the help text.

valuehidden :: Mod f a
#

Hide this option from the brief description.

Use internal to hide the option from the help text too.

valueinternal :: Mod f a
#

Hide this option completely from the help text

Use hidden if the option should remain visible in the full description.

valuestyle :: (Doc -> Doc) -> Mod f a
#

Apply a function to the option description in the usage text.

import Options.Applicative.Help
flag' () (short 't' <> style (annotate bold))

NOTE: This builder is more flexible than its name and example allude. One of the motivating examples for its addition was to use const to completely replace the usage text of an option.

valuecommand :: String -> ParserInfo a -> Mod CommandFields a
#

Add a command to a subparser option.

Suggested usage for multiple commands is to add them to a single subparser. e.g.

sample :: Parser Sample
sample = subparser
       ( command "hello"
         (info hello (progDesc "Print greeting"))
      <> command "goodbye"
         (info goodbye (progDesc "Say goodbye"))
       )
valuecommandGroup :: String -> Mod CommandFields a
#

Add a description to a group of commands.

Advanced feature for separating logical groups of commands on the parse line.

If using the same metavar for each group of commands, it may yield a more attractive usage text combined with hidden for some groups.

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

valueidm :: Monoid m => m
#

Trivial option modifier.

methodmappend :: a -> a -> a
#

An associative operation

NOTE: This method is redundant and has the default implementation mappend = (<>) since base-4.11.0.0. Should it be implemented manually, since mappend is a synonym for (<>), it is expected that the two functions are defined the same way. In a future GHC release mappend will be removed from Monoid.

datadata OptionFields a
#
Instances4HasCompleter, HasMetavar, HasName, HasValue
datadata FlagFields a
#
Instances1HasName
  • HasName FlagFieldsDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Builder.Internal
classclass HasName (f :: Type -> Type) where
#
Instances2HasName
  • HasName FlagFieldsDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Builder.Internal
  • HasName OptionFieldsDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Builder.Internal

Readers

A reader is used by the option and argument builders to parse the data passed by the user on the command line into a data type.

The most common are str which is used for String like types, including ByteString and Text; and auto, which uses the Read typeclass, and is good for simple types like Int or Double.

More complex types can use the eitherReader or maybeReader functions to pattern match or use a more expressive parser like a member of the Parsec family.

newtypenewtype ReadM a
#

A newtype over 'ReaderT String Except', used by option readers.

Instances6Monad, Functor, MonadFail, Applicative, Alternative, MonadPlus
  • Monad ReadMDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Types
  • Functor ReadMDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Types
  • MonadFail ReadMDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Types
  • Applicative ReadMDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Types
  • Alternative ReadMDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Types
  • MonadPlus ReadMDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Types
valueeitherReader :: (String -> Either String a) -> ReadM a
#

Convert a function producing an Either into a reader.

As an example, one can create a ReadM from an attoparsec Parser easily with

import qualified Data.Attoparsec.Text as A
import qualified Data.Text as T
attoparsecReader :: A.Parser a -> ReadM a
attoparsecReader p = eitherReader (A.parseOnly p . T.pack)

Program descriptions

0 declarations

ParserInfo

A ParserInfo describes a command line program, used to generate a help screen. Two help modes are supported: brief and full. In brief mode, only an option and argument summary is displayed, while in full mode each available option and command, including hidden ones, is described.

A ParserInfo should be created with the info function and a set of InfoMod modifiers.

datadata ParserInfo a
#

A full description for a runnable Parser for a program.

Constructors

Instances1Functor
  • Functor ParserInfoDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Types
newtypenewtype InfoMod a
#

Modifier for ParserInfo.

Instances2Semigroup, Monoid
  • Semigroup (InfoMod a)Defined in optparse-applicative-0.18.1.0 · Options.Applicative.Builder
  • Monoid (InfoMod a)Defined in optparse-applicative-0.18.1.0 · Options.Applicative.Builder
valuefullDesc :: InfoMod a
#

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

valuebriefDesc :: InfoMod a
#

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

valuenoIntersperse :: InfoMod a
#

Disable parsing of regular options after arguments. After a positional argument is parsed, all remaining options and arguments will be treated as a positional arguments. Not recommended in general as users often expect to be able to freely intersperse regular options and flags within command line options.

valueforwardOptions :: InfoMod a
#

Intersperse matched options and arguments normally, but allow unmatched options to be treated as positional arguments. This is sometimes useful if one is wrapping a third party cli tool and needs to pass options through, while also providing a handful of their own options. Not recommended in general as typos by the user may not yield a parse error and cause confusion.

Running parsers

3 declarations

The execParser family of functions are used to run parsers

valueexecParser :: ParserInfo a -> IO a
#

Run a program description.

Parse command line arguments. Display help text and exit if any parse error occurs.

Handling parser results manually

ParserPrefs

A ParserPrefs contains general preferences for all command-line options, and should be built with the prefs function.

datadata ParserPrefs
#

Global preferences for a top-level Parser.

Constructors

Instances2Eq, Show
  • Eq ParserPrefsDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Types
  • Show ParserPrefsDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Types
newtypenewtype PrefsMod
#
Instances2Semigroup, Monoid
  • Semigroup PrefsModDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Builder
  • Monoid PrefsModDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Builder
valueshowHelpOnEmpty :: PrefsMod
#

Show the help text if the user enters only the program name or subcommand.

This will suppress a "Missing:" error and show the full usage instead if a user just types the name of the program.

valuesubparserInline :: PrefsMod
#

Allow full mixing of subcommand and parent arguments by inlining selected subparsers into the parent parser.

NOTE: When this option is used, preferences for the subparser which effect the parser behaviour (such as noIntersperse) are ignored.

valuehelpLongEquals :: PrefsMod
#

Show equals sign, rather than space, in usage and help text for options with long names.

Completions

5 declarations

optparse-applicative supplies a rich completion system for bash, zsh, and fish shells.

Completer functions are used for option and argument to complete their values.

Use the completer builder to use these. The action and completeWith builders are also provided for convenience, to use bashCompleter and listCompleter as a Mod.

newtypenewtype Completer
#

A shell complete function.

Instances2Semigroup, Monoid
  • Semigroup CompleterDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Types
  • Monoid CompleterDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Types

Types

5 declarations
datadata ParserHelp
#

Constructors

Instances3Show, Semigroup, Monoid
  • Show ParserHelpDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Help.Types
  • Semigroup ParserHelpDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Help.Types
  • Monoid ParserHelpDefined in optparse-applicative-0.18.1.0 · Options.Applicative.Help.Types
datadata ParserResult a
#

Result of execParserPure.

Constructors

Instances4Monad, Functor, Applicative, Show