optparse-applicative-0.18.1.0: Utilities and combinators for parsing command line options

Safe Haskell | Safe-Inferred
Language | Haskell98

Options.Applicative.Common

Contents

- Option parsers
- Program descriptions
- Running parsers
- Low-level utilities

Synopsis

- data Parser a
- liftOpt :: Option a -> Parser a
- showOption :: OptName -> String
- data ParserInfo a = ParserInfo {
  - infoParser :: Parser a
  - infoFullDesc :: Bool
  - infoProgDesc :: Chunk Doc
  - infoHeader :: Chunk Doc
  - infoFooter :: Chunk Doc
  - infoFailureCode :: Int
  - infoPolicy :: ArgPolicy
  }
- data ParserPrefs = ParserPrefs {
  - prefMultiSuffix :: String
  - prefDisambiguate :: Bool
  - prefShowHelpOnError :: Bool
  - prefShowHelpOnEmpty :: Bool
  - prefBacktrack :: Backtracking
  - prefColumns :: Int
  - prefHelpLongEquals :: Bool
  - prefHelpShowGlobal :: Bool
  - prefTabulateFill :: Int
  }
- runParserInfo :: MonadP m => ParserInfo a -> Args -> m a
- runParserFully :: MonadP m => ArgPolicy -> Parser a -> Args -> m a
- runParserStep :: MonadP m => ArgPolicy -> Parser a -> String -> Args -> m (Maybe (Parser a), Args)
- runParser :: MonadP m => ArgPolicy -> IsCmdStart -> Parser a -> Args -> m (a, Args)
- evalParser :: Parser a -> Maybe a
- mapParser :: (forall x. ArgumentReachability -> Option x -> b) -> Parser a -> [b]
- treeMapParser :: (forall x. ArgumentReachability -> Option x -> b) -> Parser a -> OptTree b
- optionNames :: OptReader a -> [OptName]

# Option parsers

A `Parser` is composed of a list of options. Several kinds of options are supported:

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

data Parser a #

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

#### Instances

Instances details

Alternative Parser # |
Instance details Defined in Options.Applicative.Types Methods empty :: Parser a # (<|>) :: Parser a -> Parser a -> Parser a # some :: Parser a -> Parser [a] # many :: Parser a -> Parser [a] #
Applicative Parser # |
Instance details Defined in Options.Applicative.Types Methods pure :: a -> Parser a # (<*>) :: Parser (a -> b) -> Parser a -> Parser b # liftA2 :: (a -> b -> c) -> Parser a -> Parser b -> Parser c # (*>) :: Parser a -> Parser b -> Parser b # (<*) :: Parser a -> Parser b -> Parser a #
Functor Parser # |
Instance details Defined in Options.Applicative.Types Methods fmap :: (a -> b) -> Parser a -> Parser b # (<$) :: a -> Parser b -> Parser a #

liftOpt :: Option a -> Parser a #

Create a parser composed of a single option.

showOption :: OptName -> String #

# Program descriptions

data ParserInfo a #

A full description for a runnable `Parser` for a program.

Constructors

ParserInfo |

Fields

- infoParser :: Parser a

  the option parser for the program

- infoFullDesc :: Bool

  whether the help text should contain full documentation

- infoProgDesc :: Chunk Doc

  brief parser description

- infoHeader :: Chunk Doc

  header of the full parser description

- infoFooter :: Chunk Doc

  footer of the full parser description

- infoFailureCode :: Int

  exit code for a parser failure

- infoPolicy :: ArgPolicy

  allow regular options and flags to occur after arguments (default: InterspersePolicy)

#### Instances

Instances details

Functor ParserInfo # |
Instance details Defined in Options.Applicative.Types Methods fmap :: (a -> b) -> ParserInfo a -> ParserInfo b # (<$) :: a -> ParserInfo b -> ParserInfo a #

data ParserPrefs #

Global preferences for a top-level `Parser`.

Constructors

ParserPrefs |

Fields

- prefMultiSuffix :: String

  metavar suffix for multiple options

- prefDisambiguate :: Bool

  automatically disambiguate abbreviations (default: False)

- prefShowHelpOnError :: Bool

  always show help text on parse errors (default: False)

- prefShowHelpOnEmpty :: Bool

  show the help text for a command or subcommand if it fails with no input (default: False)

- prefBacktrack :: Backtracking

  backtrack to parent parser when a subcommand fails (default: Backtrack)

- prefColumns :: Int

  number of columns in the terminal, used to format the help page (default: 80)

- prefHelpLongEquals :: Bool

  when displaying long names in usage and help, use an '=' sign for long names, rather than a single space (default: False)

- prefHelpShowGlobal :: Bool

  when displaying subparsers' usage help, show parent options under a "global options" section (default: False)

- prefTabulateFill :: Int

  Indentation width for tables

#### Instances

Instances details

Show ParserPrefs # |
Instance details Defined in Options.Applicative.Types Methods showsPrec :: Int -> ParserPrefs -> ShowS # show :: ParserPrefs -> String # showList :: [ParserPrefs] -> ShowS #
Eq ParserPrefs # |
Instance details Defined in Options.Applicative.Types Methods (==) :: ParserPrefs -> ParserPrefs -> Bool # (/=) :: ParserPrefs -> ParserPrefs -> Bool #

# Running parsers

runParserInfo :: MonadP m => ParserInfo a -> Args -> m a #

runParserFully :: MonadP m => ArgPolicy -> Parser a -> Args -> m a #

runParserStep :: MonadP m => ArgPolicy -> Parser a -> String -> Args -> m (Maybe (Parser a), Args) #

runParser :: MonadP m => ArgPolicy -> IsCmdStart -> Parser a -> Args -> m (a, Args) #

Apply a `Parser` to a command line, and return a result and leftover arguments. This function returns an error if any parsing error occurs, or if any options are missing and don't have a default value.

evalParser :: Parser a -> Maybe a #

The default value of a `Parser`. This function returns an error if any of the options don't have a default value.

# Low-level utilities

mapParser :: (forall x. ArgumentReachability -> Option x -> b) -> Parser a -> [b] #

Map a polymorphic function over all the options of a parser, and collect the results in a list.

treeMapParser :: (forall x. ArgumentReachability -> Option x -> b) -> Parser a -> OptTree b #

Like `mapParser`, but collect the results in a tree structure.

optionNames :: OptReader a -> [OptName] #