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

Safe Haskell | Safe-Inferred
Language | Haskell98

Options.Applicative.Types

Synopsis

- data ParseError
  - = ErrorMsg String
  - | InfoMsg String
  - | ShowHelpText (Maybe String)
  - | UnknownError
  - | MissingError IsCmdStart SomeParser
  - | ExpectsArgError String
  - | UnexpectedError String SomeParser
- 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
  }
- data Option a = Option {
  - optMain :: OptReader a
  - optProps :: OptProperties
  }
- data OptName
  - = OptShort !Char
  - | OptLong !String
- isShortName :: OptName -> Bool
- isLongName :: OptName -> Bool
- data OptReader a
  - = OptReader [OptName] (CReader a) (String -> ParseError)
  - | FlagReader [OptName] !a
  - | ArgReader (CReader a)
  - | CmdReader (Maybe String) [(String, ParserInfo a)]
- data OptProperties = OptProperties {
  - propVisibility :: OptVisibility
  - propHelp :: Chunk Doc
  - propMetaVar :: String
  - propShowDefault :: Maybe String
  - propShowGlobal :: Bool
  - propDescMod :: Maybe (Doc -> Doc)
  }
- data OptVisibility
  - = Internal
  - | Hidden
  - | Visible
- data Backtracking
  - = Backtrack
  - | NoBacktrack
  - | SubparserInline
- newtype ReadM a = ReadM {
  - unReadM :: ReaderT String (Except ParseError) a
  }
- readerAsk :: ReadM String
- readerAbort :: ParseError -> ReadM a
- readerError :: String -> ReadM a
- data CReader a = CReader {
  - crCompleter :: Completer
  - crReader :: ReadM a
  }
- data Parser a
  - = NilP (Maybe a)
  - | OptP (Option a)
  - | MultP (Parser (x -> a)) (Parser x)
  - | AltP (Parser a) (Parser a)
  - | BindP (Parser x) (x -> Parser a)
- newtype ParserM r = ParserM {
  - runParserM :: forall x. (r -> Parser x) -> Parser x
  }
- newtype Completer = Completer {
  - runCompleter :: String -> IO [String]
  }
- mkCompleter :: (String -> IO [String]) -> Completer
- newtype CompletionResult = CompletionResult {
  - execCompletion :: String -> IO String
  }
- newtype ParserFailure h = ParserFailure {
  - execFailure :: String -> (h, ExitCode, Int)
  }
- data ParserResult a
  - = Success a
  - | Failure (ParserFailure ParserHelp)
  - | CompletionInvoked CompletionResult
- overFailure :: (ParserHelp -> ParserHelp) -> ParserResult a -> ParserResult a
- type Args = [String]
- data ArgPolicy
  - = Intersperse
  - | NoIntersperse
  - | AllPositionals
  - | ForwardOptions
- newtype ArgumentReachability = ArgumentReachability {
  - argumentIsUnreachable :: Bool
  }
- data AltNodeType
  - = MarkDefault
  - | NoDefault
- data OptTree a
  - = Leaf a
  - | MultNode [OptTree a]
  - | AltNode AltNodeType [OptTree a]
  - | BindNode (OptTree a)
- data ParserHelp = ParserHelp {
  - helpError :: Chunk Doc
  - helpSuggestions :: Chunk Doc
  - helpHeader :: Chunk Doc
  - helpUsage :: Chunk Doc
  - helpDescription :: Chunk Doc
  - helpBody :: Chunk Doc
  - helpGlobals :: Chunk Doc
  - helpFooter :: Chunk Doc
  }
- data SomeParser = SomeParser (Parser a)
- data Context = Context String (ParserInfo a)
- data IsCmdStart
  - = CmdStart
  - | CmdCont
- fromM :: ParserM a -> Parser a
- oneM :: Parser a -> ParserM a
- manyM :: Parser a -> ParserM [a]
- someM :: Parser a -> ParserM [a]
- filterOptional :: OptTree a -> OptTree a
- optVisibility :: Option a -> OptVisibility
- optMetaVar :: Option a -> String
- optHelp :: Option a -> Chunk Doc
- optShowDefault :: Option a -> Maybe String
- optDescMod :: Option a -> Maybe (Doc -> Doc)

# Documentation

data ParseError #

Constructors

ErrorMsg String |
InfoMsg String |
ShowHelpText (Maybe String) |
UnknownError |
MissingError IsCmdStart SomeParser |
ExpectsArgError String |
UnexpectedError String SomeParser |

#### Instances

Instances details

Monoid ParseError # |
Instance details Defined in Options.Applicative.Types Methods mempty :: ParseError # mappend :: ParseError -> ParseError -> ParseError # mconcat :: [ParseError] -> ParseError #
Semigroup ParseError # |
Instance details Defined in Options.Applicative.Types Methods (<>) :: ParseError -> ParseError -> ParseError # sconcat :: NonEmpty ParseError -> ParseError # stimes :: Integral b => b -> ParseError -> ParseError #

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 #

data Option a #

A single option of a parser.

Constructors

Option |
Fields optMain :: OptReader a reader for this option optProps :: OptProperties properties of this option

#### Instances

Instances details

Functor Option # |
Instance details Defined in Options.Applicative.Types Methods fmap :: (a -> b) -> Option a -> Option b # (<$) :: a -> Option b -> Option a #
Show (Option a) # |
Instance details Defined in Options.Applicative.Types Methods showsPrec :: Int -> Option a -> ShowS # show :: Option a -> String # showList :: [Option a] -> ShowS #

data OptName #

Constructors

OptShort !Char |
OptLong !String |

#### Instances

Instances details

Show OptName # |
Instance details Defined in Options.Applicative.Types Methods showsPrec :: Int -> OptName -> ShowS # show :: OptName -> String # showList :: [OptName] -> ShowS #
Eq OptName # |
Instance details Defined in Options.Applicative.Types Methods (==) :: OptName -> OptName -> Bool # (/=) :: OptName -> OptName -> Bool #
Ord OptName # |
Instance details Defined in Options.Applicative.Types Methods compare :: OptName -> OptName -> Ordering # (<) :: OptName -> OptName -> Bool # (<=) :: OptName -> OptName -> Bool # (>) :: OptName -> OptName -> Bool # (>=) :: OptName -> OptName -> Bool # max :: OptName -> OptName -> OptName # min :: OptName -> OptName -> OptName #

isShortName :: OptName -> Bool #

isLongName :: OptName -> Bool #

data OptReader a #

An `OptReader` defines whether an option matches an command line argument.

Constructors

OptReader [OptName] (CReader a) (String -> ParseError) | option reader
FlagReader [OptName] !a | flag reader
ArgReader (CReader a) | argument reader
CmdReader (Maybe String) [(String, ParserInfo a)] | command reader

#### Instances

Instances details

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

data OptProperties #

Specification for an individual parser option.

Constructors

OptProperties |
Fields propVisibility :: OptVisibility whether this flag is shown in the brief description propHelp :: Chunk Doc help text for this option propMetaVar :: String metavariable for this option propShowDefault :: Maybe String what to show in the help text as the default propShowGlobal :: Bool whether the option is presented in global options text propDescMod :: Maybe (Doc -> Doc) a function to run over the brief description

#### Instances

Instances details

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

data OptVisibility #

Visibility of an option in the help text.

Constructors

Internal | does not appear in the help text at all
Hidden | only visible in the full description
Visible | visible both in the full and brief descriptions

#### Instances

Instances details

Show OptVisibility # |
Instance details Defined in Options.Applicative.Types Methods showsPrec :: Int -> OptVisibility -> ShowS # show :: OptVisibility -> String # showList :: [OptVisibility] -> ShowS #
Eq OptVisibility # |
Instance details Defined in Options.Applicative.Types Methods (==) :: OptVisibility -> OptVisibility -> Bool # (/=) :: OptVisibility -> OptVisibility -> Bool #
Ord OptVisibility # |
Instance details Defined in Options.Applicative.Types Methods compare :: OptVisibility -> OptVisibility -> Ordering # (<) :: OptVisibility -> OptVisibility -> Bool # (<=) :: OptVisibility -> OptVisibility -> Bool # (>) :: OptVisibility -> OptVisibility -> Bool # (>=) :: OptVisibility -> OptVisibility -> Bool # max :: OptVisibility -> OptVisibility -> OptVisibility # min :: OptVisibility -> OptVisibility -> OptVisibility #

data Backtracking #

Constructors

Backtrack |
NoBacktrack |
SubparserInline |

#### Instances

Instances details

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

newtype ReadM a #

A newtype over 'ReaderT String Except', used by option readers.

Constructors

ReadM |
Fields unReadM :: ReaderT String (Except ParseError) a

#### Instances

Instances details

Alternative ReadM # |
Instance details Defined in Options.Applicative.Types Methods empty :: ReadM a # (<|>) :: ReadM a -> ReadM a -> ReadM a # some :: ReadM a -> ReadM [a] # many :: ReadM a -> ReadM [a] #
Applicative ReadM # |
Instance details Defined in Options.Applicative.Types Methods pure :: a -> ReadM a # (<*>) :: ReadM (a -> b) -> ReadM a -> ReadM b # liftA2 :: (a -> b -> c) -> ReadM a -> ReadM b -> ReadM c # (*>) :: ReadM a -> ReadM b -> ReadM b # (<*) :: ReadM a -> ReadM b -> ReadM a #
Functor ReadM # |
Instance details Defined in Options.Applicative.Types Methods fmap :: (a -> b) -> ReadM a -> ReadM b # (<$) :: a -> ReadM b -> ReadM a #
Monad ReadM # |
Instance details Defined in Options.Applicative.Types Methods (>>=) :: ReadM a -> (a -> ReadM b) -> ReadM b # (>>) :: ReadM a -> ReadM b -> ReadM b # return :: a -> ReadM a #
MonadPlus ReadM # |
Instance details Defined in Options.Applicative.Types Methods mzero :: ReadM a # mplus :: ReadM a -> ReadM a -> ReadM a #
MonadFail ReadM # |
Instance details Defined in Options.Applicative.Types Methods fail :: String -> ReadM a #

readerAsk :: ReadM String #

Return the value being read.

readerAbort :: ParseError -> ReadM a #

Abort option reader by exiting with a `ParseError`.

readerError :: String -> ReadM a #

Abort option reader by exiting with an error message.

data CReader a #

Constructors

CReader |
Fields crCompleter :: Completer crReader :: ReadM a

#### Instances

Instances details

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

data Parser a #

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

Constructors

NilP (Maybe a) |
OptP (Option a) |
MultP (Parser (x -> a)) (Parser x) |
AltP (Parser a) (Parser a) |
BindP (Parser x) (x -> Parser 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 #

newtype ParserM r #

Constructors

ParserM |
Fields runParserM :: forall x. (r -> Parser x) -> Parser x

#### Instances

Instances details

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

newtype Completer #

A shell complete function.

Constructors

Completer |
Fields runCompleter :: String -> IO [String]

#### Instances

Instances details

Monoid Completer # |
Instance details Defined in Options.Applicative.Types Methods mempty :: Completer # mappend :: Completer -> Completer -> Completer # mconcat :: [Completer] -> Completer #
Semigroup Completer # |
Instance details Defined in Options.Applicative.Types Methods (<>) :: Completer -> Completer -> Completer # sconcat :: NonEmpty Completer -> Completer # stimes :: Integral b => b -> Completer -> Completer #

mkCompleter :: (String -> IO [String]) -> Completer #

Smart constructor for a `Completer`

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 #

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 #

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 #

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

type Args = [String] #

data ArgPolicy #

Policy for how to handle options within the parse

Constructors

Intersperse | The default policy, options and arguments can be interspersed. A `--` option can be passed to ensure all following commands are treated as arguments.
NoIntersperse | Options must all come before arguments, once a single positional argument or subcommand is parsed, all remaining arguments are treated as positionals. A `--` option can be passed if the first positional one needs starts with `-`.
AllPositionals | No options are parsed at all, all arguments are treated as positionals. Is the policy used after `--` is encountered.
ForwardOptions | Options and arguments can be interspersed, but if a given option is not found, it is treated as a positional argument. This is sometimes useful if one is passing through most options to another tool, but are supplying just a few of their own options.

#### Instances

Instances details

Show ArgPolicy # |
Instance details Defined in Options.Applicative.Types Methods showsPrec :: Int -> ArgPolicy -> ShowS # show :: ArgPolicy -> String # showList :: [ArgPolicy] -> ShowS #
Eq ArgPolicy # |
Instance details Defined in Options.Applicative.Types Methods (==) :: ArgPolicy -> ArgPolicy -> Bool # (/=) :: ArgPolicy -> ArgPolicy -> Bool #
Ord ArgPolicy # |
Instance details Defined in Options.Applicative.Types Methods compare :: ArgPolicy -> ArgPolicy -> Ordering # (<) :: ArgPolicy -> ArgPolicy -> Bool # (<=) :: ArgPolicy -> ArgPolicy -> Bool # (>) :: ArgPolicy -> ArgPolicy -> Bool # (>=) :: ArgPolicy -> ArgPolicy -> Bool # max :: ArgPolicy -> ArgPolicy -> ArgPolicy # min :: ArgPolicy -> ArgPolicy -> ArgPolicy #

newtype ArgumentReachability #

Constructors

ArgumentReachability |
Fields argumentIsUnreachable :: Bool If the result is a positional, if it can't be accessed in the current parser position ( first arg )

#### Instances

Instances details

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

data AltNodeType #

This type encapsulates whether an `AltNode` of an `OptTree` should be displayed with brackets around it.

Constructors

MarkDefault |
NoDefault |

#### Instances

Instances details

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

data OptTree a #

Constructors

Leaf a |
MultNode [OptTree a] |
AltNode AltNodeType [OptTree a] |
BindNode (OptTree a) |

#### Instances

Instances details

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

data ParserHelp #

Constructors

ParserHelp |
Fields helpError :: Chunk Doc helpSuggestions :: Chunk Doc helpHeader :: Chunk Doc helpUsage :: Chunk Doc helpDescription :: Chunk Doc helpBody :: Chunk Doc helpGlobals :: Chunk Doc helpFooter :: Chunk Doc

#### Instances

Instances details

Monoid ParserHelp # |
Instance details Defined in Options.Applicative.Help.Types Methods mempty :: ParserHelp # mappend :: ParserHelp -> ParserHelp -> ParserHelp # mconcat :: [ParserHelp] -> ParserHelp #
Semigroup ParserHelp # |
Instance details Defined in Options.Applicative.Help.Types Methods (<>) :: ParserHelp -> ParserHelp -> ParserHelp # sconcat :: NonEmpty ParserHelp -> ParserHelp # stimes :: Integral b => b -> ParserHelp -> ParserHelp #
Show ParserHelp # |
Instance details Defined in Options.Applicative.Help.Types Methods showsPrec :: Int -> ParserHelp -> ShowS # show :: ParserHelp -> String # showList :: [ParserHelp] -> ShowS #

data SomeParser #

Constructors

SomeParser (Parser a) |

data Context #

Subparser context, containing the `name` of the subparser and its parser info. Used by parserFailure to display relevant usage information when parsing inside a subparser fails.

Constructors

Context String (ParserInfo a) |

data IsCmdStart #

Constructors

CmdStart |
CmdCont |

#### Instances

Instances details

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

fromM :: ParserM a -> Parser a #

oneM :: Parser a -> ParserM a #

manyM :: Parser a -> ParserM [a] #

someM :: Parser a -> ParserM [a] #

filterOptional :: OptTree a -> OptTree a #

optVisibility :: Option a -> OptVisibility #

optMetaVar :: Option a -> String #

optHelp :: Option a -> Chunk Doc #

optShowDefault :: Option a -> Maybe String #

optDescMod :: Option a -> Maybe (Doc -> Doc) #