-- 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.12.0.2
-- | 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 not have a dash as either
-- the first or second character and it 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
-- | Get the arguments from the command line, ensuring they are properly
-- encoded into Unicode.
--
-- base 4.3.1.0 has a System.Environment.getArgs that does not return a
-- Unicode string. Instead, it simply puts each octet into a different
-- Char. Thus its getArgs is broken on UTF-8 and nearly any non-ASCII
-- encoding. As a workaround I use System.Environment.UTF8. The downside
-- of this is that it requires that the command line be encoded in UTF8,
-- regardless of what the default system encoding is.
--
-- Unlike base 4.3.1.0, base 4.4.0.0 actually returns a proper Unicode
-- string when you call System.Environment.getArgs. (base 4.3.1.0 comes
-- with ghc 7.0.4; base 4.4.0.0 comes with ghc 7.2.) The string is
-- encoded depending on the default system locale. The only problem is
-- that System.Environment.UTF8 apparently simply uses
-- System.Environment.getArgs and then assumes that the string it returns
-- has not been decoded. In other words, System.Environment.UTF8 assumes
-- that System.Environment.getArgs is broken, and when
-- System.Environment.getArgs was fixed in base 4.4.0.0, it likely will
-- break System.Environment.UTF8.
--
-- One obvious solution to this problem is to find some other way to get
-- the command line that will not break when base is updated. But it was
-- not easy to find such a thing. The other libraries I saw on hackage
-- (as of January 6, 2012) had problems, such as breakage on ghc 7.2.
-- There is a package that has a simple interface to the UNIX
-- setlocale(3) function, but I'm not sure that what it returns easily
-- and reliably maps to character encodings that you can use with, say,
-- iconv.
--
-- So by use of Cabal and preprocessor macors, the code uses utf8-string
-- if base is less than 4.4, and uses System.Environment.getArgs if base
-- is at least 4.4.
--
-- The GHC bug is here:
--
-- http://hackage.haskell.org/trac/ghc/ticket/3309
module System.Console.MultiArg.GetArgs
-- | Gets the command-line arguments supplied by the program's user. If the
-- base package is older than version 4.4, then this function
-- assumes the command line is encoded in UTF-8, which is true for many
-- newer Unix systems; however, many older systems may use single-byte
-- encodings like ISO-8859. In such cases, this function will give
-- erroneous results.
--
-- If the base package is version 4.4.0 or newer, this function
-- simply uses the getArgs that comes with base. That getArgs
-- detects the system's default encoding and uses that, so it should give
-- accurate results on most systems.
getArgs :: IO [String]
-- | Gets the name of the program that the user invoked. See documentation
-- for getArgs for important caveats that also apply to this
-- function.
getProgName :: IO String
-- | 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 OptArgError
-- | No error message accompanies this failure. multiarg will create a
-- generic error message for you.
NoMsg :: OptArgError
-- | 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 -> OptArgError
-- | Reads in values that are members of Read. Provides a generic error
-- message if the read fails.
reader :: Read a => String -> Exceptional OptArgError 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 OptArgError (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 OptArgError a) -> ArgSpec a
-- | This option takes a single argument, like OneArg. Parsing of
-- the argument might fail.
OneArgE :: (String -> Exceptional OptArgError a) -> ArgSpec a
-- | This option takes two arguments, like TwoArg. Parsing of the
-- arguments might fail.
TwoArgE :: (String -> String -> Exceptional OptArgError a) -> ArgSpec a
-- | This option takes three arguments, like ThreeArg. Parsing of
-- the arguments might fail.
ThreeArgE :: (String -> String -> String -> Exceptional OptArgError a) -> ArgSpec a
-- | This option takes a variable number of arguments, like
-- VariableArg. Parsing of the arguments might fail.
VariableArgE :: ([String] -> Exceptional OptArgError 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 OptArgError
instance Show OptArgError
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.
module System.Console.MultiArg.SimpleParser
-- | 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
-- | Parse a command line.
simple :: Intersperse -> [OptSpec a] -> (String -> a) -> [String] -> Exceptional Error [a]
-- | Parses a simple command line (that is, one without modes) in the IO
-- monad. Gets the arguments for you using getArgs. In addition
-- to the arguments you provide for simple, you also provide
-- online help. This function adds -h and --help
-- options and shows help if the user entered one of these options
-- anywhere on the command line. If help is shown, the program exits
-- successfully. In addition, it will print a message to standard error
-- if parsing the command line fails and then exit unsuccessfully.
simpleWithHelp :: (String -> String) -> Intersperse -> [OptSpec a] -> (String -> a) -> IO [a]
-- | Provides information on each mode that you wish to parse.
data Mode result
Mode :: String -> Intersperse -> [OptSpec b] -> (String -> b) -> ([b] -> result) -> (String -> String) -> Mode result
-- | How the user identifies the mode on the command line. For example,
-- with git this would be commit, pull, etc.
mName :: Mode result -> String
-- | Each mode may have options and positional arguments; may these be
-- interspersed?
mIntersperse :: Mode result -> Intersperse
-- | Options for this mode
mOpts :: Mode result -> [OptSpec b]
-- | How to parse positional arguments for this mode
mPosArgs :: Mode result -> String -> b
-- | Processes the options after they have been parsed.
mProcess :: Mode result -> [b] -> result
-- | Help string for this mode. This is used only in modesWithHelp;
-- modes ignores this. This is displayed on screen exactly as is,
-- so be sure to include the necessary trailing newline. The function is
-- applied to the name of the program (which is retrieved at runtime.)
mHelp :: Mode result -> String -> String
-- | Parses a command line that may feature options followed by a mode
-- followed by more options and then followed by positional arguments.
modes :: [OptSpec a] -> ([a] -> Either ([String] -> result) [Mode result]) -> [String] -> Exceptional Error result
-- | Like modes, but runs in the IO monad. Gets the command line
-- arguments for you. This function adds the options -h and
-- --help, both in the global options and in the options for
-- each mode. If -h or --help is entered in the global
-- options, the global help is shown and the program exits successfully;
-- similarly, if help is requested for a particular mode, that mode's
-- help is shown and the program exits successfully.
--
-- If an error occurs in the processing of the command line, an error
-- message is printed and the program exits with a failure.
modesWithHelp :: (String -> String) -> [OptSpec a] -> ([a] -> Either ([String] -> result) [Mode result]) -> IO result
instance Functor Mode
instance Functor ArgWrap
-- | 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