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.
>>> 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 (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, …
AlternativeGetDefined in binary-0.8.9.3 · Data.Binary.Get.Internal
AlternativeSeqDefined in containers-0.8 · Data.Sequence.Internal
AlternativeZipListDefined in ghc-internal-10.0.0 · GHC.Internal.Functor.ZipList
AlternativeMaybeDefined in ghc-internal-10.0.0 · GHC.Internal.Base
Picks the leftmost Just value, or, alternatively, Nothing.
AlternativeSTMDefined in ghc-internal-10.0.0 · GHC.Internal.STM
sequence computations and combine their results (<*> and liftA2).
A minimal complete definition must include implementations of pure
and one of either <*> or liftA2. If it defines both, then they must behave
the same as their default definitions:
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.
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.Char>>> import GHC.Internal.Text.ParserCombinators.ReadP>>> let p = string "my name is " *> munch1 isAlpha <* eof>>> readP_to_S p "my name is Simon"[("Simon","")]
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
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 (<>)
typeItem (ZipLista) = aDefined in ghc-internal-10.0.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.
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.
A Parser a is an option parser returning a value of type a.
Instances3Functor, Applicative, Alternative
FunctorParserDefined in optparse-applicative-0.19.0.0 · Options.Applicative.Types
ApplicativeParserDefined in optparse-applicative-0.19.0.0 · Options.Applicative.Types
AlternativeParserDefined in optparse-applicative-0.19.0.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" )
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'.
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'.
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.
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.
Parser builders take a modifier, which represents a modification of the
properties of an option, and can be composed as a monoid.
Constraints 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.
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 Options.Applicative.strOption
or Options.Applicative.flag) to
create options (see Options.Applicative.Builder).
Instances2Semigroup, Monoid
Semigroup (Modfa)Defined in optparse-applicative-0.19.0.0 · Options.Applicative.Builder.Internal
Monoid (Modfa)Defined in optparse-applicative-0.19.0.0 · Options.Applicative.Builder.Internal
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.
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.
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.
HasMetavarArgumentFieldsDefined in optparse-applicative-0.19.0.0 · Options.Applicative.Builder.Internal
HasMetavarCommandFieldsDefined in optparse-applicative-0.19.0.0 · Options.Applicative.Builder.Internal
HasMetavarOptionFieldsDefined in optparse-applicative-0.19.0.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.
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)
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.
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.
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