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

Safe Haskell | Safe
Language | Haskell98

Options.Applicative.Extra

Contents

- Extra parser utilities

Synopsis

- helper :: Parser (a -> a)
- hsubparser :: Mod CommandFields a -> Parser a
- execParser :: ParserInfo a -> IO a
- execParserMaybe :: ParserInfo a -> [String] -> Maybe a
- customExecParser :: ParserPrefs -> ParserInfo a -> IO a
- customExecParserMaybe :: ParserPrefs -> ParserInfo a -> [String] -> Maybe a
- execParserPure :: ParserPrefs -> ParserInfo a -> [String] -> ParserResult a
- getParseResult :: ParserResult a -> Maybe a
- handleParseResult :: ParserResult a -> IO a
- parserFailure :: ParserPrefs -> ParserInfo a -> ParseError -> [Context] -> ParserFailure ParserHelp
- renderFailure :: ParserFailure ParserHelp -> String -> (String, ExitCode)
- newtype ParserFailure h = ParserFailure {
  - execFailure :: String -> (h, ExitCode, Int)
  }
- overFailure :: (ParserHelp -> ParserHelp) -> ParserResult a -> ParserResult a
- data ParserResult a
  - = Success a
  - | Failure (ParserFailure ParserHelp)
  - | CompletionInvoked CompletionResult
- data ParserPrefs = ParserPrefs {
  - prefMultiSuffix :: String
  - prefDisambiguate :: Bool
  - prefShowHelpOnError :: Bool
  - prefShowHelpOnEmpty :: Bool
  - prefBacktrack :: Bool
  - prefColumns :: Int
  }
- newtype CompletionResult = CompletionResult {
  - execCompletion :: String -> IO String
  }

# Extra parser utilities

This module contains high-level functions to run parsers.

helper :: Parser (a -> a) #

A hidden "helper" option which always fails.

hsubparser :: Mod CommandFields a -> Parser a #

Builder for a command parser with a "helper" option attached. Used in the same way as `subparser`, but includes a "--help|-h" inside the subcommand.

execParser :: ParserInfo a -> IO a #

Run a program description.

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

execParserMaybe :: ParserInfo a -> [String] -> Maybe a #

Deprecated: Use execParserPure together with getParseResult instead

Run a program description in pure code.

This function behaves like `execParser`, but can be called from pure code. Note that, in case of errors, no message is displayed, and this function simply returns `Nothing`.

If you need to keep track of error messages, use `execParserPure` instead.

customExecParser :: ParserPrefs -> ParserInfo a -> IO a #

Run a program description with custom preferences.

customExecParserMaybe :: ParserPrefs -> ParserInfo a -> [String] -> Maybe a #

Deprecated: Use execParserPure together with getParseResult instead

Run a program description with custom preferences in pure code.

See `execParserMaybe` for details.

execParserPure #

Arguments

:: ParserPrefs | Global preferences for this parser
-> ParserInfo a | Description of the program to run
-> [String] | Program arguments
-> ParserResult a |

The most general way to run a program description in pure code.

getParseResult :: ParserResult a -> Maybe a #

Extract the actual result from a `ParserResult` value.

This function returns `Nothing` in case of errors. Possible error messages or completion actions are simply discarded.

If you want to display error messages and invoke completion actions appropriately, use `handleParseResult` instead.

handleParseResult :: ParserResult a -> IO a #

Handle `ParserResult`.

parserFailure :: ParserPrefs -> ParserInfo a -> ParseError -> [Context] -> ParserFailure ParserHelp #

Generate a `ParserFailure` from a `ParseError` in a given `Context`.

This function can be used, for example, to show the help text for a parser:

    handleParseResult . Failure $ parserFailure pprefs pinfo ShowHelpText mempty

renderFailure :: ParserFailure ParserHelp -> String -> (String, ExitCode) #

newtype ParserFailure h #

Constructors

ParserFailure |
Fields execFailure :: String -> (h, ExitCode, Int)

Instances

Functor ParserFailure # |
Methods fmap :: (a -> b) -> ParserFailure a -> ParserFailure b # (<$) :: a -> ParserFailure b -> ParserFailure a #
Show h => Show (ParserFailure h) # |
Methods showsPrec :: Int -> ParserFailure h -> ShowS # show :: ParserFailure h -> String # showList :: [ParserFailure h] -> ShowS #

overFailure :: (ParserHelp -> ParserHelp) -> ParserResult a -> ParserResult a #

data ParserResult a #

Result of `execParserPure`.

Constructors

Success a |
Failure (ParserFailure ParserHelp) |
CompletionInvoked CompletionResult |

Instances

Monad ParserResult # |
Methods (>>=) :: ParserResult a -> (a -> ParserResult b) -> ParserResult b # (>>) :: ParserResult a -> ParserResult b -> ParserResult b # return :: a -> ParserResult a # fail :: String -> ParserResult a #
Functor ParserResult # |
Methods fmap :: (a -> b) -> ParserResult a -> ParserResult b # (<$) :: a -> ParserResult b -> ParserResult a #
Applicative ParserResult # |
Methods pure :: a -> ParserResult a # (<*>) :: ParserResult (a -> b) -> ParserResult a -> ParserResult b # (*>) :: ParserResult a -> ParserResult b -> ParserResult b # (<*) :: ParserResult a -> ParserResult b -> ParserResult a #
Show a => Show (ParserResult a) # |
Methods showsPrec :: Int -> ParserResult a -> ShowS # show :: ParserResult a -> String # showList :: [ParserResult a] -> ShowS #

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 :: Bool backtrack to parent parser when a subcommand fails (default: True) prefColumns :: Int number of columns in the terminal, used to format the help page (default: 80)

Instances

Eq ParserPrefs # |
Methods (==) :: ParserPrefs -> ParserPrefs -> Bool # (/=) :: ParserPrefs -> ParserPrefs -> Bool #
Show ParserPrefs # |
Methods showsPrec :: Int -> ParserPrefs -> ShowS # show :: ParserPrefs -> String # showList :: [ParserPrefs] -> ShowS #

newtype CompletionResult #

Constructors

CompletionResult |
Fields execCompletion :: String -> IO String

Instances

Show CompletionResult # |
Methods showsPrec :: Int -> CompletionResult -> ShowS # show :: CompletionResult -> String # showList :: [CompletionResult] -> ShowS #