Options.Applicative

newtype PrefsMod

Instances

• Newtype PrefsMod _
• Monoid PrefsMod
• Semigroup PrefsMod

newtype OptionFields a

Instances

• Newtype (OptionFields a) _
• HasName OptionFields
• HasCompleter OptionFields
• HasValue OptionFields
• HasMetavar OptionFields

data Mod f a

An option modifier.

Option modifiers are values that represent a modification of the properties of an option.

The type parameter @a@ is the pure type of the option, while @f@ is a record containing its properties (e.g. 'OptionFields' for regular options, 'FlagFields' for flags, etc...).

An option modifier consists of 3 elements:

• A field modifier, of the form @f a -> f a@. These are essentially (compositions of) setters for some of the properties supported by @f@.

• An optional default value and function to display it.

• A property modifier, of the form @OptProperties -> OptProperties@. This is just like the field modifier, but for properties applicable to any option.

Modifiers are instances of 'Monoid', and can be composed as such.

One rarely needs to deal with modifiers directly, as most of the times it is sufficient to pass them to builders (such as 'strOption' or 'flag') to create options (see 'Options.Applicative.Builder').

Contraints are often used to ensure that the modifiers can be sensibly applied. For example, positional arguments can't be specified by long or short names, so the 'HasName' constraint is used to ensure we have a flag or option.

Instances

• Monoid (Mod f a)
• Semigroup (Mod f a)

  @since 0.13.0.0

newtype InfoMod a

Modifier for 'ParserInfo'.

Instances

• Newtype (InfoMod a) _
• Monoid (InfoMod a)
• Semigroup (InfoMod a)

newtype FlagFields a

Instances

• Newtype (FlagFields a) _
• HasName FlagFields

newtype CommandFields a

Instances

• Newtype (CommandFields a) _
• HasMetavar CommandFields

newtype ArgumentFields a

Instances

• Newtype (ArgumentFields a) _
• HasCompleter ArgumentFields
• HasValue ArgumentFields
• HasMetavar ArgumentFields

class HasCompleter f 

Instances

• HasCompleter OptionFields
• HasCompleter ArgumentFields

class HasMetavar f 

Instances

• HasMetavar OptionFields
• HasMetavar ArgumentFields
• HasMetavar CommandFields

class HasName f 

Instances

• HasName OptionFields
• HasName FlagFields

class HasValue f 

Instances

• HasValue OptionFields
• HasValue ArgumentFields

value :: forall a f. HasValue f => a -> Mod f a

Specify a default value for an option.

switch :: Mod FlagFields Boolean -> Parser Boolean

Builder for a boolean flag.

subparserInline :: PrefsMod

Allow full mixing of subcommand and parent arguments by inlining

subparser :: forall a. Mod CommandFields a -> Parser a

Builder for a command parser. The 'command' modifier can be used to

style :: forall a f. (Doc -> Doc) -> Mod f a

Apply a function to the option description in the usage text.

strOption :: Mod OptionFields String -> Parser String

Builder for an option taking a 'String' argument.

strArgument :: Mod ArgumentFields String -> Parser String

Builder for a 'String' argument.

str :: ReadM String

String 'Option' reader.

showHelpOnError :: PrefsMod

Show full help text on any error.

showHelpOnEmpty :: PrefsMod

Show the help text if the user enters only the program name or

showDefaultWith :: forall a f. (a -> String) -> Mod f a

Specify a function to show the default value for an option.

showDefault :: forall a f. Show a => Mod f a

Show the default value for this option using its 'Show' instance.

short :: forall a f. HasName f => Char -> Mod f a

Specify a short name for an option.

progDescDoc :: forall a. Maybe Doc -> InfoMod a

Specify a short program description as a 'Text.PrettyPrint.ANSI.Leijen.Doc'

progDesc :: forall a. String -> InfoMod a

Specify a short program description.

prefs :: PrefsMod -> ParserPrefs

Create a ParserPrefs given a modifier

option :: forall a. ReadM a -> Mod OptionFields a -> Parser a

Builder for an option using the given reader.

number :: ReadM Number

Number 'Option' reader.

noIntersperse :: forall a. InfoMod a

Disable parsing of regular options after arguments. After a positional

noBacktrack :: PrefsMod

Turn off backtracking after subcommand is parsed.

noArgError :: forall a. ParseError -> Mod OptionFields a

Specify the error to display when no argument is provided to this option.

multiSuffix :: String -> PrefsMod

Include a suffix to attach to the metavar when multiple values

metavar :: forall a f. HasMetavar f => String -> Mod f a

Specify a metavariable for the argument.

maybeReader :: forall a. (String -> Maybe a) -> ReadM a

Convert a function producing a 'Maybe' into a reader.

long :: forall a f. HasName f => String -> Mod f a

Specify a long name for an option.

internal :: forall a f. Mod f a

Hide this option from the help text

int :: ReadM Int

Int 'Option' reader.

infoOption :: forall a. String -> Mod OptionFields (a -> a) -> Parser (a -> a)

An option that always fails and displays a message.

info :: forall a. Parser a -> InfoMod a -> ParserInfo a

Create a 'ParserInfo' given a 'Parser' and a modifier.

idm :: forall m. Monoid m => m

Trivial option modifier.

hidden :: forall a f. Mod f a

Hide this option from the brief description.

helpDoc :: forall a f. Maybe Doc -> Mod f a

Specify the help text for an option as a 'Text.PrettyPrint.ANSI.Leijen.Doc'

help :: forall f a. String -> Mod f a

Specify the help text for an option.

headerDoc :: forall a. Maybe Doc -> InfoMod a

Specify a header for this parser as a 'Text.PrettyPrint.ANSI.Leijen.Doc'

header :: forall a. String -> InfoMod a

Specify a header for this parser.

fullDesc :: forall a. InfoMod a

Show a full description in the help text of this parser.

forwardOptions :: forall a. InfoMod a

Intersperse matched options and arguments normally, but allow unmatched

footerDoc :: forall a. Maybe Doc -> InfoMod a

Specify a footer for this parser as a 'Text.PrettyPrint.ANSI.Leijen.Doc'

footer :: forall a. String -> InfoMod a

Specify a footer for this parser.

flag' :: forall a. a -> Mod FlagFields a -> Parser a

Builder for a flag parser without a default value.

flag :: forall a. a -> a -> Mod FlagFields a -> Parser a

Builder for a flag parser.

failureCode :: forall a. ExitCode -> InfoMod a

Specify an exit code if a parse error occurs.

eitherReader :: forall a. (String -> Either String a) -> ReadM a

Convert a function producing an 'Either' into a reader.

disambiguate :: PrefsMod

Turn on disambiguation.

disabled :: forall a. ReadM a

Null 'Option' reader. All arguments will fail validation.

defaultPrefs :: ParserPrefs

Default preferences.

completer :: forall a f. HasCompleter f => Completer -> Mod f a

Add a completer to an argument.

completeWith :: forall a f. HasCompleter f => Array String -> Mod f a

Add a list of possible completion values.

commandGroup :: forall a. String -> Mod CommandFields a

Add a description to a group of commands.

command :: forall a. String -> ParserInfo a -> Mod CommandFields a

Add a command to a subparser option.

columns :: Int -> PrefsMod

Set the maximum width of the generated help text.

briefDesc :: forall a. InfoMod a

Only show a brief description in the help text of this parser.

boolean :: ReadM Boolean

Boolean 'Option' reader.

argument :: forall a. ReadM a -> Mod ArgumentFields a -> Parser a

Builder for an argument parser.

action :: forall a f. HasCompleter f => String -> Mod f a

Add a bash completion action. Common actions include @file@ and

abortOption :: forall a. ParseError -> Mod OptionFields (a -> a) -> Parser (a -> a)

An option that always fails.

listIOCompleter :: Effect (Array String) -> Completer

Create a 'Completer' from an IO action

listCompleter :: (Array String) -> Completer

Create a 'Completer' from a constant

bashCompleter :: String -> Completer

Run a compgen completion action.

renderFailure :: ParserFailure ParserHelp -> String -> Tuple String ExitCode

parserFailure :: forall a. ParserPrefs -> ParserInfo a -> ParseError -> Array Context -> ParserFailure ParserHelp

Generate a ParserFailure from a ParseError in a given Context.

hsubparser :: forall a. Mod CommandFields a -> Parser a

Builder for a command parser with a "helper" option attached.

helper :: forall a. Parser (a -> a)

A hidden "helper" option which always fails.

handleParseResult :: forall a. ParserResult a -> Effect a

Handle ParserResult.

getParseResult :: forall a. ParserResult a -> Maybe a

Extract the actual result from a ParserResult value.

execParserPure :: forall a. ParserPrefs -> ParserInfo a -> Array String -> ParserResult a

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

execParser :: forall a. ParserInfo a -> Effect a

Run a program description.

customExecParser :: forall a. ParserPrefs -> ParserInfo a -> Effect a

Run a program description with custom preferences.

Operator alias for Options.Applicative.Internal.Utils.apApplyFlipped (left-associative / precedence 4)

newtype ReadM a

A reader is used by the 'option' and 'argument' builders to parse the data passed by the user on the command line into a data type.

The most common are 'str' which is used for 'String', there are readers for Int, Number, Boolean.

More complex types can use the 'eitherReader' or 'maybeReader' functions to pattern match or use a more expressive parser like a member of the 'Parsec' family. A newtype over 'ReaderT String Except', used by option readers.

Instances

• Newtype (ReadM a) _
• Functor ReadM
• Apply ReadM
• Applicative ReadM
• Alt ReadM
• Plus ReadM
• Alternative ReadM
• Bind ReadM
• Monad ReadM
• MonadThrow String ReadM
• MonadZero ReadM
• MonadPlus ReadM

data ParserResult a

Result of 'execParserPure'.

Constructors

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

Instances

• Generic (ParserResult a) _
• (Show a) => Show (ParserResult a)
• Functor ParserResult
• Apply ParserResult
• Applicative ParserResult
• Bind ParserResult
• Monad ParserResult

newtype ParserPrefs

Global preferences for a top-level 'Parser'. A 'ParserPrefs' contains general preferences for all command-line options, and can be built with the 'prefs' function.

Constructors

• ParserPrefs { prefBacktrack :: Backtracking, prefColumns :: Int, prefDisambiguate :: Boolean, prefMultiSuffix :: String, prefShowHelpOnEmpty :: Boolean, prefShowHelpOnError :: Boolean }

Instances

• Newtype ParserPrefs _
• Eq ParserPrefs
• Generic ParserPrefs _
• Show ParserPrefs

newtype ParserInfo a

A 'ParserInfo' describes a command line program, used to generate a help screen. Two help modes are supported: brief and full. In brief mode, only an option and argument summary is displayed, while in full mode each available option and command, including hidden ones, is described.

A basic 'ParserInfo' with default values for fields can be created using the 'info' function.

Constructors

• ParserInfo { infoFailureCode :: ExitCode, infoFooter :: Chunk Doc, infoFullDesc :: Boolean, infoHeader :: Chunk Doc, infoParser :: Parser a, infoPolicy :: ArgPolicy, infoProgDesc :: Chunk Doc }

Instances

• Newtype (ParserInfo a) _
• Functor ParserInfo

newtype ParserHelp

Constructors

• ParserHelp { helpBody :: Chunk Doc, helpError :: Chunk Doc, helpFooter :: Chunk Doc, helpHeader :: Chunk Doc, helpSuggestions :: Chunk Doc, helpUsage :: Chunk Doc }

Instances

• Newtype ParserHelp _
• Show ParserHelp
• Semigroup ParserHelp
• Monoid ParserHelp

newtype ParserFailure h

Constructors

• ParserFailure (String -> Tuple3 h ExitCode Int)

Instances

• Newtype (ParserFailure h) _
• Show (ParserFailure h)
• Functor ParserFailure

data Parser a

A 'Parser' is the core type in optparse-applicative. A value of type Parser a@ represents a specification for a set of options, which will yield a value of type a when the command line arguments are successfully parsed.

There are several types of primitive 'Parser'.

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

** Parser builders

Each parser builder takes an option modifier. A modifier can be created by composing the basic modifiers provided by here using the 'Monoid' operations mempty' and 'append', or their aliases 'idm' and '<>'.

For example:

out = strOption ( long "output" <> short 'o' <> metavar "FILENAME" )

creates a parser for an option called "output".

Instances

• Functor Parser
• Apply Parser
• Applicative Parser
• Alt Parser
• Plus Parser
• Alternative Parser

data ParseError

Constructors

• ErrorMsg String
• InfoMsg String
• ShowHelpText
• UnknownError
• MissingError IsCmdStart SomeParser
• ExpectsArgError String
• UnexpectedError String SomeParser

Instances

• Monoid ParseError
• Semigroup ParseError

newtype CompletionResult

Constructors

• CompletionResult { execCompletion :: String -> Effect String }

Instances

• Newtype CompletionResult _
• Show CompletionResult

newtype Completer

optparse-applicative supplies a rich completion system for bash, zsh, and fish shells.

'Completer' functions are used for option and argument to complete their values.

Use the 'completer' builder to use these. The 'action' and 'completeWith' builders are also provided for convenience, to use 'bashCompleter' and 'listCompleter' as a 'Mod'.

Instances

• Newtype Completer _
• Semigroup Completer
• Monoid Completer

some :: forall a. Parser a -> Parser (List a)

readerError :: forall a. String -> ReadM a

Abort option reader by exiting with an error message.

readerAbort :: forall a. ParseError -> ReadM a

Abort option reader by exiting with a 'ParseError'.

overFailure :: forall a. (ParserHelp -> ParserHelp) -> ParserResult a -> ParserResult a

mkCompleter :: (String -> Effect (Array String)) -> Completer

Smart constructor for a 'Completer'

many :: forall a. Parser a -> Parser (List a)