System.Console.MultiArg.Combinator

Combinators that are useful for building command-line parsers. These build off the functions in System.Console.MultiArg.Prim. Unlike those functions, these functions have no access to the internals of the parser.

Parser combinators

option :: (Error e, Monad m) => a -> ParserT s e m a -> ParserT s e m a

option x p runs parser p. If p fails without consuming any input, returns x. Otherwise, returns p.

optionMaybe :: (Error e, Monad m) => ParserT s e m a -> ParserT s e m (Maybe a)

optionMaybe p runs parser p. If p fails without returning any input, returns Nothing. If p succeeds, returns the result of p wrapped in a Just. If p fails but consumes input, optionMaybe fails.

notFollowedBy :: (Error e, Monad m) => ParserT s e m a -> ParserT s e m ()

notFollowedBy p succeeds only if parser p fails. If p fails, notFollowedBy succeeds without consuming any input. If p succeeds and consumes input, notFollowedBy fails and consumes input. If p succeeds and does not consume any input, notFollowedBy fails and does not consume any input.

Short options

shortNoArg :: (Error e, Monad m) => ShortOpt -> ParserT s e m ShortOpt

Parses short options that do not take any argument. (It is however okay for the short option to be combined with other short options in the same word.)

shortOptionalArg :: (Error e, Monad m) => ShortOpt -> ParserT s e m (ShortOpt, Maybe Text)

Parses short options that take an optional argument. The argument can be combined in the same word with the short option (-c42) or can be in the ext word (-c 42).

shortOneArg :: (Error e, Monad m) => ShortOpt -> ParserT s e m (ShortOpt, Text)

Parses short options that take a required argument. The argument can be combined in the same word with the short option (-c42) or can be in the ext word (-c 42).

shortTwoArg :: (Error e, Monad m) => ShortOpt -> ParserT s e m (ShortOpt, Text, Text)

Parses short options that take two required arguments. The first argument can be combined in the same word with the short option (-c42) or can be in the ext word (-c 42). The next argument will have to be in a separate word.

shortVariableArg :: (Error e, Monad m) => ShortOpt -> ParserT s e m (ShortOpt, [Text])

Parses short options that take a variable number of arguments. This will keep on parsing option arguments until it encounters one that does not look like an option--that is, until it encounters one that begins with a dash. Therefore, the only way to terminate a variable argument option if it is the last option is with a stopper. The first argument can be combined in the same word with the short option (-c42) or can be in the ext word (-c 42). Subsequent arguments will have to be in separate words.

Long options

nonGNUexactLongOpt :: (Error e, Monad m) => LongOpt -> ParserT s e m LongOpt

Parses only a non-GNU style long option (that is, one that does not take option arguments by attaching them with an equal sign, such as --lines=20).

matchApproxLongOpt :: (Error e, Monad m) => LongOpt -> Set LongOpt -> ParserT s e m (Text, LongOpt, Maybe Text)

Takes a long option and a set of long options. If the next word on the command line unambiguously starts with the name of the long option given, returns the actual text found on the command line, the long option, and the text of any GNU-style option argument. Make sure that the long option you are looking for is both the first argument and that it is included in the set; otherwise this parser will always fail.

matchNonGNUApproxLongOpt :: (Error e, Monad m) => LongOpt -> Set LongOpt -> ParserT s e m (Text, LongOpt)

Like matchApproxLongOpt but only parses non-GNU-style long options.

longNoArg :: (Error e, Monad m) => LongOpt -> ParserT s e m LongOpt

Parses long options that do not take any argument.

longOptionalArg :: (Error e, Monad m) => LongOpt -> ParserT s e m (LongOpt, Maybe Text)

Parses long options that take a single, optional argument. The single argument can be given GNU-style (--lines=20) or non-GNU style in separate words (lines 20).

longOneArg :: (Error e, Monad m) => LongOpt -> ParserT s e m (LongOpt, Text)

Parses long options that take a single, required argument. The single argument can be given GNU-style (--lines=20) or non-GNU style in separate words (lines 20).

longTwoArg :: (Error e, Monad m) => LongOpt -> ParserT s e m (LongOpt, Text, Text)

Parses long options that take a double, required argument. The first argument can be given GNU-style (--lines=20) or non-GNU style in separate words (lines 20). The second argument will have to be in a separate word.

longVariableArg :: (Error e, Monad m) => LongOpt -> ParserT s e m (LongOpt, [Text])

Parses long options that take a variable number of arguments. This will keep on parsing option arguments until it encounters one that does not look like an option--that is, until it encounters one that begins with a dash. Therefore, the only way to terminate a variable argument option if it is the last option is with a stopper. The first argument can be combined in the same word with the short option (--lines=20) or can be in the ext word (--lines 42). Subsequent arguments will have to be in separate words.

Mixed options

mixedNoArg :: (Error e, Monad m) => LongOpt -> [LongOpt] -> [ShortOpt] -> ParserT s e m (Either ShortOpt LongOpt)

Parses at least one long option and a variable number of short and long options that take no arguments.

mixedOptionalArg :: (Error e, Monad m) => LongOpt -> [LongOpt] -> [ShortOpt] -> ParserT s e m (Either ShortOpt LongOpt, Maybe Text)

Parses at least one long option and a variable number of short and long options that take an optional argument.

mixedOneArg :: (Error e, Monad m) => LongOpt -> [LongOpt] -> [ShortOpt] -> ParserT s e m (Either ShortOpt LongOpt, Text)

Parses at least one long option and additional long and short options that take one argument.

mixedTwoArg :: (Error e, Monad m) => LongOpt -> [LongOpt] -> [ShortOpt] -> ParserT s e m (Either ShortOpt LongOpt, Text, Text)

Parses at least one long option and additonal long and short options that take two arguments.

mixedVariableArg :: (Error e, Monad m) => LongOpt -> [LongOpt] -> [ShortOpt] -> ParserT s e m (Either ShortOpt LongOpt, [Text])

Parses at least one long option and additional long and short options that take a variable number of arguments.

Other words

matchApproxWord :: (Error e, Monad m) => Set Text -> ParserT s e m (Text, Text)

Examines the possible words in Set. If there are no pendings, then get the next word and see if it matches one of the words in Set. If so, returns the word actually parsed and the matching word from Set. If there is no match, fails without consuming any input.