-- 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.6.0.0 -- | 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 -- | 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. 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 combine. 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 -- | parserMap f p applies function f to the result of parser p. -- First parser p is run. If it succeeds, function f is applied to the -- result and another parser is returned with the result. If it fails, f -- is not applied and a failed parser is returned. This provides the -- implementation for fmap. parserMap :: (a -> b) -> Parser a -> Parser b -- | good a always succeeds without consuming any input and has -- result a. This provides the implementation for return and -- pure. good :: a -> Parser a -- | apply l r applies the function found in parser l to the result of -- parser r. First the l parser is run. If it succeeds, it has a -- resulting function. Then the r parser is run. If it succeeds, the -- function from the l parser is applied to the result of the r parser, -- and a new parser is returned with the result. If either parser l or -- parser r fails, then a failed parser is returned. This provides the -- implementation for <*> in Applicative. apply :: Parser (a -> b) -> Parser a -> Parser b -- | 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. combine :: 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 -- | several p runs parser p zero or more times and returns all the -- results. This proceeds like this: parser p is run and, if it succeeds, -- the result is saved and parser p is run again. Repeat. Eventually this -- will have to fail. If the last run of parser p fails without consuming -- any input, then several p runs successfully. The state of the parser -- is updated to reflect the successful runs of p. If the last run of -- parser p fails but it consumed input, then several p fails. The state -- of the parser is updated to reflect the state up to and including the -- run that partially consumed input. The parser is left in a failed -- state. -- -- This semantic can come in handy. For example you might run a parser -- multiple times that parses an option and arguments to the option. If -- the arguments fail to parse, then several will fail. -- -- This function provides the implementation for many. several :: Parser a -> Parser [a] -- | manyTill p e runs parser p repeatedly until parser e succeeds. -- -- More precisely, first it runs parser e. If parser e succeeds, then -- manyTill returns the result of all the preceding successful parses of -- p. If parser e fails (it does not matter whether e consumed any input -- or not), manyTill runs parser p again. What happens next depends on -- whether p succeeded or failed. If p succeeded, then the loop starts -- over by running parser e again. If p failed (it does not matter -- whether it consumed any input or not), then manyTill fails. The state -- of the parser is updated to reflect its state after the failed run of -- p, and the parser is left in a failed state. -- -- Should parser e succeed (as it will on a successful application of -- manyTill), then the parser state will reflect that parser e -- succeeded--that is, if parser e consumes input, that input will be -- consumed in the parser that is returned. Wrap e inside of -- lookAhead if that is undesirable. -- -- Be particularly careful to get the order of the arguments correct. -- Applying this function to reversed arguments will yield bugs that are -- very difficult to diagnose. manyTill :: Parser a -> Parser end -> Parser [a] -- | throw e always fails without consuming any input and returns a failed -- parser with error state e. throw :: Message -> Parser a -- | throwString 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. throwString :: String -> Parser a -- | Fail with an unhelpful error message. Usually throw 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, -- then applies the given function to the list of messages and replaces -- the list of messages with the list returned by the function. -- Otherwise, returns the result of the parser. () :: Parser a -> ([Message] -> [Message]) -> 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, in order: -- -- -- -- 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: -- -- -- -- 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 the option, -- and 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: -- -- exactLongOpt :: LongOpt -> Parser (Maybe String) -- | Examines the next word. If it matches a Text 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. 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. nextArg :: Parser String -- | 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 -- | Succeeds if there is no more input left. end :: Parser () -- | Error messages. data Message -- | The parser expected to see one thing, but it actually saw something -- else. The string indicates what was expected. Expected :: String -> Message -- | The fromString function was applied. StrMsg :: String -> Message -- | A previous list of error messages was replaced with this error -- message. Replaced :: String -> Message -- | Any other error; used by genericThrow. UnknownError :: Message -- | An Error contains a list of Messages and a String indicating where the -- error happened. data Error Error :: [Message] -> Location -> Error type Location = String instance Show Message instance Show Error instance Show ParseSt instance MonadPlus Parser instance Monad Parser instance Alternative Parser instance Monoid (Parser a) instance Applicative Parser instance Functor 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 () -- | Runs the parser given. If it succeeds, then returns the result of the -- parser. If it fails and consumes input, returns the result of the -- parser. If it fails without consuming any input, then removes all -- previous errors, replacing them with a single error of type Replaced -- containing the string given. () :: Parser a -> String -> Parser a -- | 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 -- | 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. 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 -- | 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 -- | 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. matchApproxWord :: Set String -> Parser (String, String) instance Functor ArgSpec instance Functor OptSpec -- | 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. 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 -- | 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 -- | 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. 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 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 -- | Like Either, but explicitly intended for handling of -- exceptional results. In contrast to Either we do not support -- fail. Calling fail in the Exceptional monad is an -- error. This way, we do not require that an exception can be derived -- from a String, yet, we require no constraint on the exception -- type at all. data Exceptional e a :: * -> * -> * Success :: a -> Exceptional e a Exception :: e -> Exceptional e a -- | An Error contains a list of Messages and a String indicating where the -- error happened. data Error Error :: [Message] -> Location -> Error -- | Error messages. data Message -- | The parser expected to see one thing, but it actually saw something -- else. The string indicates what was expected. Expected :: String -> Message -- | The fromString function was applied. StrMsg :: String -> Message -- | A previous list of error messages was replaced with this error -- message. Replaced :: String -> Message -- | Any other error; used by genericThrow. UnknownError :: Message -- | 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] -- | Parse a command line. parse :: Intersperse -> [OptSpec a] -> (String -> a) -> [String] -> Exceptional Error [a] -- | 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] -- | 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 sampleMain :: Intersperse -> IO () instance Show Flag -- | A combinator library for building command-line parsers. module System.Console.MultiArg