Options.Applicative.Extra

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

Functor ParserFailure

Defined in Options.Applicative.Types

Methods

fmap :: (a -> b) -> ParserFailure a -> ParserFailure b

(<$) :: a -> ParserFailure b -> ParserFailure a

Show h => Show (ParserFailure h)

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

Applicative ParserResult

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

Defined in Options.Applicative.Types

Methods

fmap :: (a -> b) -> ParserResult a -> ParserResult b

(<$) :: a -> ParserResult b -> ParserResult a

Monad ParserResult

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)

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

Show ParserPrefs

Defined in Options.Applicative.Types

Methods

showsPrec :: Int -> ParserPrefs -> ShowS

show :: ParserPrefs -> String

showList :: [ParserPrefs] -> ShowS

Eq ParserPrefs

Defined in Options.Applicative.Types

Methods

(==) :: ParserPrefs -> ParserPrefs -> Bool

(/=) :: ParserPrefs -> ParserPrefs -> Bool

newtype CompletionResult

Constructors

CompletionResult

Fields

• execCompletion :: String -> IO String

Instances

Show CompletionResult

Defined in Options.Applicative.Types

Methods

showsPrec :: Int -> CompletionResult -> ShowS

show :: CompletionResult -> String

showList :: [CompletionResult] -> ShowS