Options.OptStream.Raw

This module contains RawParser and RawFollower, which are the actual types used by Parser and Follower internally.

RawParser is the core type of the optstream library. It provides a twice-applicative and once-monadic interface for building command line parsers. It takes care of the parsing itself, but doesn't deal with higher-level features such as help generation. Parser is a (rather thin) wrapper built on top of RawParser in order to provide basic handling of --help. You can build your own interface on top of RawParser to provide more sophisticated features.

Documentation

module Options.OptStream.Classes

Parsers

data RawParser a

A RawParser processes part of a stream of command line arguments and produces an output value of type a. RawParser is the type that Parser uses internally. The differences between these two types are:

• A Parser has a Help object attached to it. A RawParser doesn't.
• RawParser is a Monad, whereas Parser is only an Applicative.

Instances

Monad RawParser

Defined in Options.OptStream.Raw

Methods

(>>=) :: RawParser a -> (a -> RawParser b) -> RawParser b

(>>) :: RawParser a -> RawParser b -> RawParser b

return :: a -> RawParser a

Functor RawParser

Defined in Options.OptStream.Raw

Methods

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

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

MonadFail RawParser

Defined in Options.OptStream.Raw

Methods

fail :: String -> RawParser a

Applicative RawParser

Defined in Options.OptStream.Raw

Methods

pure :: a -> RawParser a

(<*>) :: RawParser (a -> b) -> RawParser a -> RawParser b

liftA2 :: (a -> b -> c) -> RawParser a -> RawParser b -> RawParser c

(*>) :: RawParser a -> RawParser b -> RawParser b

(<*) :: RawParser a -> RawParser b -> RawParser a

Alternative RawParser

Defined in Options.OptStream.Raw

Methods

empty :: RawParser a

(<|>) :: RawParser a -> RawParser a -> RawParser a

some :: RawParser a -> RawParser [a]

many :: RawParser a -> RawParser [a]

SelectiveParser RawParser

Defined in Options.OptStream.Raw

Methods

(<#>) :: RawParser (a -> b) -> RawParser a -> RawParser b

(<-#>) :: RawParser (a -> b) -> RawParser a -> RawParser b

(<#->) :: RawParser (a -> b) -> RawParser a -> RawParser b

(<-|>) :: RawParser a -> RawParser a -> RawParser a

(<|->) :: RawParser a -> RawParser a -> RawParser a

eof :: RawParser ()

many :: RawParser a -> RawParser [a]

some :: RawParser a -> RawParser [a]

optional :: RawParser a -> RawParser (Maybe a)

between :: Int -> Int -> RawParser a -> RawParser [a]

perm :: [RawParser a] -> RawParser [a]

ApplicativeFail RawParser

Defined in Options.OptStream.Raw

Methods

failA :: String -> RawParser a

FunctorFail RawParser

Defined in Options.OptStream.Raw

Methods

fmapOrFail :: (a -> Either String b) -> RawParser a -> RawParser b

runParser :: RawParser a -> [String] -> Either ParserError a

See runParser.

runParserIO :: IOOps m => RawParser a -> [String] -> m a

See runParserIO.

parseArgs :: IOOps m => RawParser a -> m a

See parseArgs.

Atomic parsers

type OptionForm = String

High-level option parsers all accept a list of option forms. An option form is simply a String.

There are two kinds of legal option forms: short forms, e.g. "-f", and long forms, e.g. "--foo". Any function that accepts an OptionForm will fail with an error if the option form is illegal. See isLegalOptionForm.

isLegalOptionForm :: OptionForm -> Bool

Checks whether the given string is a legal option form. A legal short form is -C, where C is any character other than -. A legal long form is --STR, where STR is any non-empty string.

This function is here just in case. Normally the programmer will provide option forms as string literals, so they will probably be legal.

Example:

>>> isLegalOptionForm "-f"
True
>>> isLegalOptionForm "--foo"
True
>>> isLegalOptionForm "bar"
False
>>> isLegalOptionForm ""
False
>>> isLegalOptionForm "-"
False
>>> isLegalOptionForm "--"
False
>>> isLegalOptionForm "---"
True

Flags

flag'

Arguments

:: [OptionForm]

Flag forms, e.g. ["-f", "--foo"].

-> RawParser ()

A parser that succeeds upon consuming the flag.

See flag'.

flagSep'

Arguments

:: [OptionForm]

Flag forms, e.g. ["-f", "--foo"].

-> RawParser ()

A parser that succeeds upon consuming the flag.

See flagSep'.

Parameters

param'

Arguments

:: [OptionForm]

All parameter forms, e.g. ["-n", "--name"].

-> String

Metavariable for error messages.

-> RawParser String

A parser that returns the parameter value.

See param'.

paramRead'

Arguments

:: Read a

=> [OptionForm]

All parameter forms, e.g. ["-n", "--number"].

-> String

Metavariable for error messages.

-> RawParser a

A parser that returns the parsed parameter value.

See paramRead'.

paramChar'

Arguments

:: [OptionForm]

All parameter forms, e.g. ["-s", "--separator"].

-> String

Metavariable for error messages.

-> RawParser Char

A parser that returns the parsed parameter value.

See paramChar'.

Free arguments

freeArg'

Arguments

:: String

Metavariable for error messages (arbitrary string).

-> RawParser String

Parser that consumes and returns the first free argument it sees.

See freeArg'.

freeArgRead'

Arguments

:: Read a

=> String

Metavariable for error messages (arbitrary string).

-> RawParser a

Parser that consumes the first free argument it sees and parses it down to type a.

See freeArgRead'.

freeArgChar'

Arguments

:: String

Metavariable for error messages.

-> RawParser Char

Parser that consumes the first free argument it sees and parses it down to a Char.

See freeArgChar'.

anyArg'

Arguments

:: String

Metavariable for error messages.

-> RawParser String

Parser that consumes and returns the first argument it sees.

See anyArg'.

anyArgRead'

Arguments

:: Read a

=> String

Metavariable for error messages.

-> RawParser a

Parser that consumes the first argument it sees and parses it down to type a.

See anyArgRead'.

anyArgChar'

Arguments

:: String

Metavariable for error messages.

-> RawParser Char

Parser that consumes the first argument it sees and parses it down to a Char.

See anyArgChar'.

Multi-parameters

multiParam'

Arguments

:: [OptionForm]

All multi-parameter forms, e.g. ["-p", "--person"].

-> RawFollower a

How to process the following arguments.

-> RawParser a

A parser that consumes the option form and the following arguments.

See multiParam'.

data RawFollower a

A RawFollower consumes zero or more strings from a stream and then produces a result of type a. This is the type that Follower uses internally. The differences between RawFollower and Follower are:

• A Follower has a help string attached to it, a RawFollower doesn't.
• RawFollower is a Monad, whereas Follower is only an Applicative.

Instances

Monad RawFollower

Defined in Options.OptStream.Raw

Methods

(>>=) :: RawFollower a -> (a -> RawFollower b) -> RawFollower b

(>>) :: RawFollower a -> RawFollower b -> RawFollower b

return :: a -> RawFollower a

Functor RawFollower

Defined in Options.OptStream.Raw

Methods

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

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

MonadFail RawFollower

Defined in Options.OptStream.Raw

Methods

fail :: String -> RawFollower a

Applicative RawFollower

Defined in Options.OptStream.Raw

Methods

pure :: a -> RawFollower a

(<*>) :: RawFollower (a -> b) -> RawFollower a -> RawFollower b

liftA2 :: (a -> b -> c) -> RawFollower a -> RawFollower b -> RawFollower c

(*>) :: RawFollower a -> RawFollower b -> RawFollower b

(<*) :: RawFollower a -> RawFollower b -> RawFollower a

ApplicativeFail RawFollower

Defined in Options.OptStream.Raw

Methods

failA :: String -> RawFollower a

FunctorFail RawFollower

Defined in Options.OptStream.Raw

Methods

fmapOrFail :: (a -> Either String b) -> RawFollower a -> RawFollower b

next

Arguments

:: String

Metavariable for error messages.

-> RawFollower String

See next

nextRead

Arguments

:: Read a

=> String

Metavariable for error messages.

-> RawFollower a

See nextRead.

nextChar

Arguments

:: String

Metavariable for error messages.

-> RawFollower Char

See nextChar.

nextMetavar :: RawFollower a -> Maybe String

See nextMetavar.

Utilities

withVersion'

Arguments

:: String

Version info to be shown to the user.

-> RawParser a

An existing RawParser.

-> RawParser (Either String a)

A wrapper RawParser that returns either a or the given version string.

See withVersion'.

withVersionIO'

Arguments

:: IOOps m

=> String

Version information to show to the user.

-> RawParser (m a)

An existing RawParser.

-> RawParser (m a)

A wrapper that handles --version.

See withVersionIO'.

beforeDashes

Arguments

:: RawParser a

An existing RawParser.

-> RawParser a

A wrapper that handles --.

See beforeDashes.

Low-level parsers

block

Arguments

:: String

Block name for "missing argument" error messages. Arbitrary string.

-> (String -> Maybe (RawFollower a))

A function that decides whether to skip or consume a command line argument.

-> RawParser a

A RawParser that consumes one consecutive block of command line arguments.

See block.

short

Arguments

:: String

Short flag name for "missing argument" error messages. Arbitrary string.

-> (Char -> Maybe a)

A function that decides whether to skip or consume a short flag.

-> RawParser a

A RawParser that consumes one short flag.

See short.

match

Arguments

:: String

The exact command line argument to match.

-> RawParser String

A parser that finishes after matching and consuming the argument.

See match.

matchAndFollow

Arguments

:: String

Command line argument that starts a block.

-> RawFollower a

A follower that consumes the rest of the block.

-> RawParser a

See matchAndFollow.

matchShort

Arguments

:: Char

A short flag, e.g. 'x' will match -x or an occurence of 'x' in a bundle of short flags like -xyz.

-> RawParser Char

See matchShort.

quiet :: RawParser a -> RawParser a

See quiet.

eject

Arguments

:: RawParser a

An existing parser.

-> RawParser b

A parser that may trigger an ejection.

-> RawParser (Either b a)

See eject.

Errors

data ParserError

An error returned by runParser. There are three kinds of errors:

• An unexpected command line argument. This means that the top-level parser skipped (didn't consume) an input token (a command-line argument or a short flag inside an argument).
• A missing argument. This means that either the top-level parser refused to consume EOF, or that EOF was reached when a Follower was holding the stream and wanted more input. The error message will generally contain a list of possible items missing (flags or metavariables).
• A custom error thrown with e.g. failA or fmapOrFail.

Instances

Eq ParserError

Defined in Options.OptStream.Raw

Methods

(==) :: ParserError -> ParserError -> Bool

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

Ord ParserError

Defined in Options.OptStream.Raw

Methods

compare :: ParserError -> ParserError -> Ordering

(<) :: ParserError -> ParserError -> Bool

(<=) :: ParserError -> ParserError -> Bool

(>) :: ParserError -> ParserError -> Bool

(>=) :: ParserError -> ParserError -> Bool

max :: ParserError -> ParserError -> ParserError

min :: ParserError -> ParserError -> ParserError

Show ParserError

Defined in Options.OptStream.Raw

Methods

showsPrec :: Int -> ParserError -> ShowS

show :: ParserError -> String

showList :: [ParserError] -> ShowS

formatParserError :: ParserError -> String

Formats a ParserError to a human-readable string.