-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Combinators to build command line parsers
--
-- multiarg is a parser combinator library to build command line parsers.
-- With it you can easily create parsers with options that take more than
-- one option argument--for example, I created multiarg due to the
-- apparent lack of such ability amongst other parsers. Its basic design
-- is loosely inspired by Parsec.
--
-- Provides Parser, a monad you use to build parsers. This monad exposes
-- multiarg's full functionality. The library also has a simple,
-- pre-built parser built with the underlying combinators, which works
-- for many situtations and shields you from the underlying complexity if
-- you don't need it.
--
-- See the documentation in the System.Console.MultiArg module for
-- details.
@package multiarg
@version 0.18.0.0
-- | These types represent options. Option names cannot have a dash as
-- their first or second character, and long option names cannot have an
-- equals sign anywhere in the name.
module System.Console.MultiArg.Option
-- | Short options. Options that are preceded with a single dash on the
-- command line and consist of a single letter. That single letter cannot
-- be a dash. Any other Unicode character is good (including pathological
-- ones like newlines).
data ShortOpt
unShortOpt :: ShortOpt -> Char
-- | Creates a short option. Returns Nothing if the character is not valid
-- for a short option.
makeShortOpt :: Char -> Maybe ShortOpt
-- | Long options. Options that are preceded with two dashes on the command
-- line and typically consist of an entire mnemonic word, such as
-- lines. However, anything that is at least one letter long is
-- fine for a long option name. The name must be at least one character
-- long. It cannot have an equal sign anywhere in its name. Otherwise any
-- Unicode character is good (including pathological ones like newlines).
data LongOpt
unLongOpt :: LongOpt -> String
-- | Makes a long option. Returns Nothing if the string is not a valid long
-- option.
makeLongOpt :: String -> Maybe LongOpt
instance Show ShortOpt
instance Eq ShortOpt
instance Ord ShortOpt
instance Show LongOpt
instance Eq LongOpt
instance Ord LongOpt
-- | Parser primitives. These are the only functions that have access to
-- the internals of the parser. Use these functions if you want to build
-- your own parser from scratch. If your needs are simpler, you will want
-- to look at System.Console.MultiArg.SimpleParser or
-- System.Console.MultiArg.Combinator, which do a lot of grunt
-- work for you.
--
-- Internal design, especially the error handling, is based in large part
-- on Parsec, as described in the paper at
-- http://legacy.cs.uu.nl/daan/pubs.html#parsec.
module System.Console.MultiArg.Prim
-- | Parsers. Internally the parser tracks what input remains to be parsed,
-- whether there are any pending short options, and whether a stopper has
-- been seen. A parser can return a value of any type.
--
-- The parser also includes the notion of failure. Any parser can fail; a
-- failed parser affects the behavior of combinators such as choice.
data Parser a
-- | Runs a parser. This is the only way to change a value of type
-- Parser a into a value of type a (that is, it is the
-- only way to "get out of the Parser monad" or to "escape the Parser
-- monad".)
parse :: [String] -> Parser a -> Exceptional Error a
-- | good a always succeeds without consuming any input and has
-- result a. This provides the implementation for return and
-- pure.
good :: a -> Parser a
-- | Runs the first parser. If it fails without consuming any input, then
-- runs the second parser. If the first parser succeeds, then returns the
-- result of the first parser. If the first parser fails and consumes
-- input, then returns the result of the first parser. This provides the
-- implementation for <|> in Alternative.
choice :: Parser a -> Parser a -> Parser a
-- | Combines two parsers into a single parser. The second parser can
-- optionally depend upon the result from the first parser.
--
-- This applies the first parser. If the first parser succeeds, combine
-- then takes the result from the first parser, applies the function
-- given to the result from the first parser, and then applies the
-- resulting parser.
--
-- If the first parser fails, combine will not apply the second function
-- but instead will bypass the second parser.
--
-- This provides the implementation for >>= in Monad.
bind :: Parser a -> (a -> Parser b) -> Parser b
-- | lookAhead p runs parser p. If p succeeds, lookAhead p
-- succeeds without consuming any input. If p fails without consuming any
-- input, so does lookAhead. If p fails and consumes input, lookAhead
-- also fails and consumes input. If this is undesirable, combine with
-- try.
lookAhead :: Parser a -> Parser a
-- | Runs a parser zero or more times. If the last run of the parser fails
-- without consuming any input, this parser succeeds without consuming
-- any input. If the last run of the parser fails while consuming input,
-- this parser fails while consuming input. This provides the
-- implementation for many in Control.Applicative.
several :: Parser a -> Parser [a]
-- | Runs a parser one or more times. Runs the parser once and then applies
-- several.
several1 :: Parser a -> Parser [a]
-- | manyTill p end runs parser p zero or more times until parser
-- end succeeds. If end succeeds and consumes input,
-- that input is also consumed. in the result of manyTill. If
-- that is a problem, wrap it in lookAhead. Also, if
-- end fails and consumes input, manyTill fails and
-- consumes input. If that is a problem, wrap end in
-- try.
manyTill :: Parser a -> Parser end -> Parser [a]
-- | failString s always fails without consuming any input. The
-- failure contains a record of the string passed in by s. This provides
-- the implementation for fail.
failString :: String -> Parser a
-- | Fail with an unhelpful error message. Usually throwString is
-- more useful, but this is handy to implement some typeclass instances.
genericThrow :: Parser a
-- | Runs the parser given. If it fails without consuming any input,
-- replaces all Expected messages with the one given. Otherwise, returns
-- the result of the parser unchanged.
() :: Parser a -> String -> Parser a
-- | try p behaves just like p, but if p fails, try p will not consume any
-- input.
try :: Parser a -> Parser a
-- | Parses only pending short options. Fails without consuming any input
-- if there has already been a stopper or if there are no pending short
-- options. Fails without consuming any input if there is a pending short
-- option, but it does not match the short option given. Succeeds and
-- consumes a pending short option if it matches the short option given.
pendingShortOpt :: ShortOpt -> Parser ()
-- | Parses only non-pending short options. Fails without consuming any
-- input if:
--
--
-- - there are pending short options
-- - there has already been a stopper
-- - there are no arguments left to parse
-- - the next argument is an empty string
-- - the next argument does not begin with a dash
-- - the next argument is a single dash
-- - the next argument is a short option but it does not match the one
-- given
-- - the next argument is a stopper
--
--
-- Otherwise, consumes the next argument, puts any remaining letters from
-- the argument into a pending short, and removes the first word from
-- remaining arguments to be parsed.
nonPendingShortOpt :: ShortOpt -> Parser ()
-- | Parses only pending short option arguments. For example, for the
-- tail command, if you enter the option -c25, then
-- after parsing the -c option the 25 becomes a pending
-- short option argument because it was in the same command line argument
-- as the -c.
--
-- Fails without consuming any input if:
--
--
-- - a stopper has already been parsed
-- - there are no pending short option arguments
--
--
-- On success, returns the String of the pending short option argument
-- (this String will never be empty).
pendingShortOptArg :: Parser String
-- | Parses an exact long option. That is, the text of the command-line
-- option must exactly match the text of the option. Returns any argument
-- that is attached to the same word of the option with an equal sign
-- (for example, --follow=/dev/random will return Just
-- "/dev/random" for the argument.) If there is no equal sign,
-- returns Nothing for the argument. If there is an equal sign but there
-- is nothing after it, returns Just "" for the argument.
--
-- If you do not want your long option to have equal signs and GNU-style
-- option arguments, wrap this parser in something that will fail if
-- there is an option argument.
--
-- Fails without consuming any input if:
--
--
-- - there are pending short options
-- - a stopper has been parsed
-- - there are no arguments left on the command line
-- - the next argument on the command line does not begin with two
-- dashes
-- - the next argument on the command line is -- (a
-- stopper)
-- - the next argument on the command line does begin with two dashes
-- but its text does not match the argument we're looking for
--
exactLongOpt :: LongOpt -> Parser (Maybe String)
-- | Examines the next word. If it matches a LongOpt in the set
-- unambiguously, returns a tuple of the word actually found and the
-- matching word in the set and the accompanying text after the equal
-- sign (if any). If the Set is empty, this parser will always fail.
approxLongOpt :: Set LongOpt -> Parser (String, LongOpt, Maybe String)
-- | Parses a "stopper" - that is, a double dash. Changes the internal
-- state of the parser to reflect that a stopper has been seen.
stopper :: Parser ()
-- | If a stopper has already been seen, change the internal state back to
-- indicating that no stopper has been seen.
resetStopper :: Parser ()
-- | Returns the next string on the command line as long as there are no
-- pendings. Succeeds even if a stopper is present. Be careful - this
-- will return the next string even if it looks like an option (that is,
-- it starts with a dash.) Consider whether you should be using
-- nonOptionPosArg instead. However this can be useful when parsing
-- command line options after a stopper.
nextWord :: Parser String
-- | Parses the next word on the command line, but only if it exactly
-- matches the word given. Otherwise, fails without consuming any input.
-- Also fails without consuming any input if there are pending short
-- options or if a stopper has already been parsed. Does not pay any
-- attention to whether a stopper is present.
nextWordIs :: String -> Parser ()
-- | If there are pending short options, fails without consuming any input.
--
-- Otherwise, if a stopper has NOT already been parsed, then returns the
-- next word if it is either a single dash or any other word that does
-- not begin with a dash. If the next word does not meet these criteria,
-- fails without consuming any input.
--
-- Otherwise, if a stopper has already been parsed, then returns the next
-- word, regardless of whether it begins with a dash or not.
nonOptionPosArg :: Parser String
-- | 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. Pays no
-- attention to whether a stopper has been seen.
matchApproxWord :: Set String -> Parser (String, String)
-- | Succeeds if there is no more input left.
end :: Parser ()
data Description
Unknown :: Description
General :: String -> Description
Expected :: String -> Description
-- | Error messages. To format error messages for nice display, see
-- formatError.
data Error
Error :: InputDesc -> [Description] -> Error
type InputDesc = String
instance Eq Description
instance Show Description
instance Ord Description
instance Eq Error
instance Show Error
instance Ord Error
instance MonadPlus Parser
instance Monoid (Parser a)
instance Alternative Parser
instance Applicative Parser
instance Functor Parser
instance Monad Parser
-- | 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.
module System.Console.MultiArg.Combinator
-- | 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.
notFollowedBy :: Parser a -> Parser ()
-- | Specifies options for the parseOption function. Each OptSpec
-- represents one command-line option.
data OptSpec a
OptSpec :: [String] -> [Char] -> ArgSpec a -> OptSpec a
-- | Each String is a single long option, such as version. When
-- the user specifies long options on the command line, she must type two
-- dashes; however, do not include the dashes when you specify the long
-- option here. Strings you specify as long options cannot include a dash
-- as either the first or the second character, and they cannot include
-- an equal sign anywhere. If your long option does not meet these
-- conditions, a runtime error will occur.
longOpts :: OptSpec a -> [String]
-- | Each Char is a single short option, such as v. The character
-- cannot be a dash; if it is, a runtime error will occur.
shortOpts :: OptSpec a -> [Char]
-- | What to do each time one of the given long options or short options
-- appears on the command line.
argSpec :: OptSpec a -> ArgSpec a
-- | Indicates errors when parsing options to arguments.
data InputError
-- | No error message accompanies this failure. multiarg will create a
-- generic error message for you.
NoMsg :: InputError
-- | Parsing the argument failed with this error message. An example might
-- be option argument is not an integer or option argument
-- is too large. The text of the options the user provided is
-- automatically prepended to the error message, so do not replicate this
-- in your message.
ErrorMsg :: String -> InputError
-- | Reads in values that are members of Read. Provides a generic error
-- message if the read fails.
reader :: Read a => String -> Exceptional InputError a
-- | Reads in values that are members of Read, but the value does not have
-- to appear on the command line. Provides a generic error message if the
-- read fails. If the argument is Nothing, returns Nothing.
optReader :: Read a => Maybe String -> Exceptional InputError (Maybe a)
-- | Specifies how many arguments each option takes. As with
-- ArgDescr, there are (at least) two ways to use this type. You
-- can simply represent each possible option using different data
-- constructors in an algebraic data type. Or you can have each ArgSpec
-- yield a function that transforms a record. For an example that uses an
-- algebraic data type, see System.Console.MultiArg.SampleParser.
--
-- Some of these value constructors have names ending in E. Use
-- these constructors when you want to parse option arguments that may
-- fail to parse--for example, you want to parse an Int. The function
-- passed as an argument to the value constructor indicates failure by
-- returing an Exception.
data ArgSpec a
-- | This option takes no arguments
NoArg :: a -> ArgSpec a
-- | This option takes an optional argument. As noted in "The Tao of Option
-- Parsing", optional arguments can result in some ambiguity. (Read it
-- here: http://optik.sourceforge.net/doc/1.5/tao.html) If option
-- a takes an optional argument, and b is also an
-- option, what does -ab mean? SimpleParser resolves this
-- ambiguity by assuming that b is an argument to a. If
-- the user does not like this, she can specify -a -b (in such
-- an instance -b is not parsed as an option to -a,
-- because -b begins with a hyphen and therefore "looks like" an
-- option.) Certainly though, optional arguments lead to ambiguity, so if
-- you don't like it, don't use them :)
OptionalArg :: (Maybe String -> a) -> ArgSpec a
-- | This option takes one argument. Here, if option a takes one
-- argument, -a -b will be parsed with -b being an
-- argument to option a, even though -b starts with a
-- hyphen and therefore "looks like" an option.
OneArg :: (String -> a) -> ArgSpec a
-- | This option takes two arguments. Parsed similarly to OneArg.
TwoArg :: (String -> String -> a) -> ArgSpec a
-- | This option takes three arguments. Parsed similarly to OneArg.
ThreeArg :: (String -> String -> String -> a) -> ArgSpec a
-- | This option takes a variable number of arguments--zero or more. Option
-- arguments continue until the command line contains a word that begins
-- with a hyphen. For example, if option a takes a variable
-- number of arguments, then -a one two three -b will be parsed
-- as a taking three arguments, and -a -b will be
-- parsed as a taking no arguments. If the user enters
-- -a as the last option on the command line, then the only way
-- to indicate the end of arguments for a and the beginning of
-- positional argments is with a stopper.
VariableArg :: ([String] -> a) -> ArgSpec a
-- | This option takes a single argument, which must match one of the
-- strings given in the list. The user may supply the shortest
-- unambiguous string. If the argument list to ChoiceArg has duplicate
-- strings, only the first string is used. For instance, ChoiceArg could
-- be useful if you were parsing the --color option to GNU grep,
-- which requires the user to supply one of three arguments:
-- always, never, or auto.
ChoiceArg :: [(String, a)] -> ArgSpec a
-- | This option takes an optional argument, like OptionalArg.
-- Parsing of the optional argument might fail.
OptionalArgE :: (Maybe String -> Exceptional InputError a) -> ArgSpec a
-- | This option takes a single argument, like OneArg. Parsing of
-- the argument might fail.
OneArgE :: (String -> Exceptional InputError a) -> ArgSpec a
-- | This option takes two arguments, like TwoArg. Parsing of the
-- arguments might fail.
TwoArgE :: (String -> String -> Exceptional InputError a) -> ArgSpec a
-- | This option takes three arguments, like ThreeArg. Parsing of
-- the arguments might fail.
ThreeArgE :: (String -> String -> String -> Exceptional InputError a) -> ArgSpec a
-- | This option takes a variable number of arguments, like
-- VariableArg. Parsing of the arguments might fail.
VariableArgE :: ([String] -> Exceptional InputError a) -> ArgSpec a
-- | Parses a single command line option. Examines all the options
-- specified using multiple OptSpec and parses one option on the command
-- line accordingly. Fails without consuming any input if the next word
-- on the command line is not a recognized option. Allows the user to
-- specify the shortest unambiguous match for long options; for example,
-- the user could type --verb for --verbose and
-- --vers for --version.
--
-- This function is applied to a list of OptSpec, rather than to a single
-- OptSpec, because in order to correctly handle the parsing of shortened
-- long options (e.g. --verb rather than --verbose) it
-- is necessary for one function to have access to all of the OptSpec.
-- Applying this function multiple times to different lists of OptSpec
-- and then using the | function to combine them will
-- break the proper parsing of shortened long options.
--
-- For an example that uses this function, see
-- System.Console.MultiArg.SimpleParser.
parseOption :: [OptSpec a] -> Parser a
-- | Formats error messages for nice display. Returns a multi-line string
-- (there is no need to append a newline to the end of the string
-- returned).
formatError :: String -> Error -> String
instance Eq InputError
instance Show InputError
instance Functor ArgSpec
instance Functor OptSpec
-- | Some pre-built command line parsers. One is a simple command line
-- parser that can parse options that take an optional argument, one or
-- two arguments, or a variable number of arguments. For sample code that
-- uses this parser, see System.Console.MultiArg.SampleParser.
--
-- Another parser is provided for multi-mode programs that are similar to
-- git or darcs.
--
-- Previously there was a bug in System.Environment.getArgs that would
-- not properly encode Unicode command line arguments. multiarg used to
-- provide its own GetArgs module to deal with this. This bug was in base
-- 4.3.1.0, which was bundled with ghc 7.0.4. This bug was fixed in base
-- 4.4.0.0, which came with ghc 7.2. Since this bug has been fixed for
-- awhile, multiarg no longer has its own GetArgs module.
module System.Console.MultiArg.CommandLine
-- | What to do after encountering the first non-option,
-- non-option-argument word on the command line? In either case, no more
-- options are parsed after a stopper.
data Intersperse
-- | Additional options are allowed on the command line after encountering
-- the first positional argument. For example, if a and
-- b are options, in the command line -a posarg -b,
-- b will be parsed as an option. If b is not an
-- option and the same command line is entered, then -b will
-- result in an error because -b starts with a hyphen and
-- therefore "looks like" an option.
Intersperse :: Intersperse
-- | No additional options will be parsed after encountering the first
-- positional argument. For example, if a and b are
-- options, in the command line -a posarg -b, b will be
-- parsed as a positional argument rather than as an option.
StopOptions :: Intersperse
-- | The name of the program that was entered on the command line, obtained
-- from System.Environment.getProgName.
type ProgName = String
-- | Specifies a set of options.
data Opts s a
Opts :: [OptSpec a] -> [OptSpec s] -> Opts s a
-- | If the user does not specify any shortcut options, she may specify any
-- number of these options.
oOptions :: Opts s a -> [OptSpec a]
-- | Shortcut options are commonly options such as --help or
-- --version. Such options must be specified alone on the
-- command line. The parser looks for one of these options first. If it
-- finds one and it is the only option on the command line, only this
-- option is processed and returned. If the option is not alone on the
-- command line, an error occurs. If no shortcut option is found, the
-- parser processes non-shortcut options instead.
oShortcuts :: Opts s a -> [OptSpec s]
-- | Things that contain shortcut options that can be changed.
class MapShortcuts f
smap :: MapShortcuts f => (a -> b) -> f a o -> f b o
-- | Specification for both options and positional arguments.
data OptsWithPosArgs s a
OptsWithPosArgs :: Opts s a -> Intersperse -> (String -> Exceptional InputError a) -> OptsWithPosArgs s a
opOpts :: OptsWithPosArgs s a -> Opts s a
opIntersperse :: OptsWithPosArgs s a -> Intersperse
opPosArg :: OptsWithPosArgs s a -> String -> Exceptional InputError a
-- | Specifies a mode.
data Mode s r
Mode :: String -> ([a] -> r) -> OptsWithPosArgs s a -> Mode s r
-- | How the user specifies the mode on the command line. For git
-- for example this might be commit or log.
mModeName :: Mode s r -> String
-- | This function is applied to a list of the results of parsing the
-- options that are specific to this mode. The function returns a type of
-- your choosing (though all modes in the same parser will have to return
-- the same type.)
mGetResult :: Mode s r -> [a] -> r
-- | Options and positional arguments that are specific to this mode. For
-- example, in the command line git commit -a -m 'this is a log
-- message', commit is the mode name and everything after
-- that is specified here as an option or positional argument that is
-- specific to this mode.
mOpts :: Mode s r -> OptsWithPosArgs s a
-- | A pure (non-IO) parser for simple command lines--that is, command
-- lines that do not have modes.
simplePure :: OptsWithPosArgs s a -> [String] -> Exceptional Error (Either s [a])
-- | A parser for simple command lines that do not contain modes. Runs in
-- the IO monad.
simpleIO :: [OptSpec a] -> Intersperse -> (String -> Exceptional InputError a) -> IO [a]
-- | A parser for simple command lines. Adds a --help option for
-- you.
simpleHelp :: (ProgName -> String) -> [OptSpec a] -> Intersperse -> (String -> Exceptional InputError a) -> IO [a]
-- | A parser for simple command lines without modes. Adds options for
-- --help and --version for you.
simpleHelpVersion :: (ProgName -> String) -> (ProgName -> String) -> [OptSpec a] -> Intersperse -> (String -> Exceptional InputError a) -> IO [a]
-- | A pure (non-IO) parser for command lines that contain modes.
modesPure :: Opts s g -> ([g] -> Exceptional String (Either r [Mode s r])) -> [String] -> Exceptional Error (Either s r)
-- | A command line parser for multi-mode command lines. Runs in the IO
-- monad.
modesIO :: Opts s g -> ([g] -> Exceptional String (Either r [Mode s r])) -> IO (Either s r)
-- | Creates an Opts with a help shortcut option.
optsHelp :: h -> [OptSpec a] -> Opts h a
-- | Creates an Opts with help and version shortcut options.
optsHelpVersion :: h -> h -> [OptSpec a] -> Opts h a
-- | Creates a Mode with a help option (help specific to the mode.)
modeHelp :: String -> h -> ([a] -> r) -> [OptSpec a] -> Intersperse -> (String -> Exceptional InputError a) -> Mode h r
instance Functor (Mode s)
instance MapShortcuts Mode
instance Functor (OptsWithPosArgs s)
instance MapShortcuts OptsWithPosArgs
instance MapShortcuts Opts
instance Functor (Opts s)
-- | This is sample code using System.Console.MultiArg. This could
-- be a command-line parser for the version of the Unix command
-- tail that is included with GNU coreutils version 8.5.
-- main simply gets the command line arguments, parses them, and
-- prints out what was parsed. To test it out, simply compile an
-- executable that looks like this and then feed it different options:
--
--
-- import System.Console.MultiArg.SampleParser
-- main = sampleMain Intersperse
--
--
-- or:
--
--
-- import System.Console.MultiArg.SampleParser
-- main = sampleMain StopOptions
--
--
-- The code in the module is the sample code; the sample code is not in
-- the Haddock documentation! If you're reading this in Haddock, you will
-- want to also take a look at the actual source code.
module System.Console.MultiArg.SampleParser
data Flag
Bytes :: String -> Flag
Follow :: (Maybe String) -> Flag
Retry :: Flag
Lines :: String -> Flag
Stats :: String -> Flag
Pid :: String -> Flag
Quiet :: Flag
Sleep :: String -> Flag
Verbose :: Flag
Help :: Flag
Version :: Flag
Filename :: String -> Flag
specs :: [OptSpec Flag]
sampleMain :: Intersperse -> IO ()
instance Show Flag
-- | A combinator library for building command-line parsers.
module System.Console.MultiArg