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

Safe Haskell | Safe-Inferred
Language | Haskell98

Options.Applicative.Extra

Contents

- Extra parser utilities

Synopsis

- helper :: Parser (a -> a)
- helperWith :: Mod OptionFields (a -> a) -> Parser (a -> a)
- hsubparser :: Mod CommandFields a -> Parser a
- simpleVersioner :: String -> Parser (a -> a)
- execParser :: ParserInfo a -> IO a
- customExecParser :: ParserPrefs -> ParserInfo a -> IO 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 :: Backtracking
  - prefColumns :: Int
  - prefHelpLongEquals :: Bool
  - prefHelpShowGlobal :: Bool
  - prefTabulateFill :: 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.

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

    opts :: ParserInfo Sample
    opts = info (sample <**> helper) mempty

helperWith :: Mod OptionFields (a -> a) -> Parser (a -> a) #

Like helper, but with a minimal set of modifiers that can be extended as desired.

    opts :: ParserInfo Sample
    opts = info (sample <**> helperWith (mconcat [
             long "help",
             short 'h',
             help "Show this help text",
             hidden
           ])) mempty

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.

simpleVersioner #

Arguments

:: String | Version string to be shown
-> Parser (a -> a) |

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

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

execParser :: ParserInfo a -> IO a #

Run a program description.

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

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

Run a program description with custom preferences.

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 Nothing) mempty

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

newtype ParserFailure h #

Constructors

ParserFailure |

Fields

- execFailure :: String -> (h, ExitCode, Int)

#### Instances

Instances details

Functor ParserFailure # |
Instance details Defined in Options.Applicative.Types Methods fmap :: (a -> b) -> ParserFailure a -> ParserFailure b # (<$) :: a -> ParserFailure b -> ParserFailure a #
Show h => Show (ParserFailure h) # |
Instance details Defined in Options.Applicative.Types 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

Instances details

Applicative ParserResult # |
Instance details Defined in Options.Applicative.Types Methods pure :: a -> ParserResult a # (<*>) :: ParserResult (a -> b) -> ParserResult a -> ParserResult b # liftA2 :: (a -> b -> c) -> ParserResult a -> ParserResult b -> ParserResult c # (*>) :: ParserResult a -> ParserResult b -> ParserResult b # (<*) :: ParserResult a -> ParserResult b -> ParserResult a #
Functor ParserResult # |
Instance details Defined in Options.Applicative.Types Methods fmap :: (a -> b) -> ParserResult a -> ParserResult b # (<$) :: a -> ParserResult b -> ParserResult a #
Monad ParserResult # |
Instance details Defined in Options.Applicative.Types Methods (>>=) :: ParserResult a -> (a -> ParserResult b) -> ParserResult b # (>>) :: ParserResult a -> ParserResult b -> ParserResult b # return :: a -> ParserResult a #
Show a => Show (ParserResult a) # |
Instance details Defined in Options.Applicative.Types 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 :: 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 #

newtype CompletionResult #

Constructors

CompletionResult |

Fields

- execCompletion :: String -> IO String

#### Instances

Instances details

Show CompletionResult # |
Instance details Defined in Options.Applicative.Types Methods showsPrec :: Int -> CompletionResult -> ShowS # show :: CompletionResult -> String # showList :: [CompletionResult] -> ShowS #