-- 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 ParserT, a monad you use to build parsers. ParserT is a monad -- transformer, so you can layer it on top of other monads. For instance -- you could layer it on the IO monad so that your parser can perform IO. -- -- It 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.2.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 module System.Console.MultiArg.TextNonEmpty data TextNonEmpty TextNonEmpty :: Char -> Text -> TextNonEmpty instance Show TextNonEmpty instance Eq TextNonEmpty -- | These types represent options. They are abstract and in a separate -- module to prevent you from accidentally making an option with an -- invalid name. 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 -- | This function is partial. It calls error if its argument is a single -- dash. This is the only way to make a short option so it prevents you -- from making one that is invalid. makeShortOpt :: Char -> 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 -> Text -- | This function is partial. It calls error if its argument contains text -- that is not a valid long option. This is the only way to make a long -- option so it prevents you from making invalid ones. makeLongOpt :: Text -> LongOpt instance Show ShortOpt instance Eq ShortOpt instance Ord ShortOpt instance Show LongOpt instance Eq LongOpt instance Ord LongOpt -- | Errors. Parsing a command line when a user has entered it correctly is -- easy; doing something sensible when an incorrect line has been entered -- is a bit more difficult. This module exports an Error -- typeclass, which you can declare instances of in order to have your -- own type to represent errors. Or you can use SimpleError, which -- is already an instance of Error. module System.Console.MultiArg.Error -- | Instances of this typeclass represent multiarg errors. You can declare -- instances of this typeclass so that you can use your own type for -- errors. This makes multiarg easy to integrate into your own programs. -- Then you can also easily add other errors, which you can report from -- the parsers you build by calling throw. class Error e parseErr :: Error e => Expecting -> Saw -> e -- | A simple type that is already an instance of Error. data SimpleError SimpleError :: Expecting -> Saw -> SimpleError -- | Generates error messages. printError :: SimpleError -> Text -- | Each error consists of two parts: what the parser was expecting to -- see, and what it actually saw. This type holds what the parser -- expected to see. If you just want to give some text to be used in an -- error message, use ExpTextError. To generate a generic error, -- use ExpOtherFailure. data Expecting ExpPendingShortOpt :: ShortOpt -> Expecting ExpExactLong :: LongOpt -> Expecting ExpApproxLong :: (Set LongOpt) -> Expecting ExpLongOptArg :: Expecting ExpPendingShortArg :: Expecting ExpStopper :: Expecting ExpNextArg :: Expecting ExpNonOptionPosArg :: Expecting ExpEnd :: Expecting ExpNonGNUExactLong :: LongOpt -> Expecting ExpMatchingApproxLong :: LongOpt -> (Set LongOpt) -> Expecting ExpNonGNUMatchingApproxLong :: LongOpt -> (Set LongOpt) -> Expecting ExpApproxWord :: (Set Text) -> Expecting ExpOptionOrPosArg :: Expecting ExpTextError :: Text -> Expecting ExpNonPendingShortOpt :: ShortOpt -> Expecting ExpNotFollowedBy :: Expecting ExpOtherFailure :: Expecting -- | Generates an error message from an Expecting. printExpecting :: Expecting -> Text -- | What the parser actually saw. To give some text to be used in the -- error message, use SawTextError. To generate a generic error, -- use SawOtherFailure. data Saw SawNoPendingShorts :: Saw SawWrongPendingShort :: Char -> Saw SawNoArgsLeft :: Saw SawEmptyArg :: Saw SawSingleDashArg :: Saw SawStillPendingShorts :: TextNonEmpty -> Saw SawNotShortArg :: Text -> Saw SawWrongShortArg :: Char -> Saw SawNotLongArg :: Text -> Saw SawWrongLongArg :: Text -> Saw SawNoMatches :: Text -> Saw SawMultipleMatches :: (Set LongOpt) -> Text -> Saw SawNoPendingShortArg :: Saw SawAlreadyStopper :: Saw SawNewStopper :: Saw SawNotStopper :: Saw SawLeadingDashArg :: Text -> Saw SawMoreInput :: Saw SawGNULongOptArg :: Text -> Saw SawNotMatchingApproxLong :: Text -> LongOpt -> Saw SawMatchingApproxLongWithArg :: Text -> Saw SawMultipleApproxMatches :: (Set Text) -> Text -> Saw SawNoOption :: Saw SawNoOptionOrPosArg :: Saw SawTextError :: Text -> Saw SawFollowedBy :: Saw SawOtherFailure :: Saw -- | Generates error messages from a Saw. printSaw :: Saw -> Text instance Show Expecting instance Eq Expecting instance Show Saw instance Eq Saw instance Show SimpleError instance Eq SimpleError instance Error SimpleError instance Error Text -- | Parser primitives. These are the only functions that have access to -- the internals of the parser. module System.Console.MultiArg.Prim -- | Parser a is a parser with user state (), error type -- SimpleError, underlying monad Identity, and result type a. type Parser a = ParserT () SimpleError Identity a -- | ParserE e a is a parser with user state (), error type e, -- underlying monad Identity, and result type a. type ParserE e a = ParserT () e Identity a -- | ParserSE s e a is a parser with user state s, error type e, -- underlying monad Identity, and result type a. type ParserSE s e a = ParserT s e Identity a -- | ParserT s e m a is a parser with user state s, error type e, -- underlying monad m, and result type a. Internally the parser is a -- state monad which keeps track of what is remaining to be parsed. Since -- the parser has an internal state anyway, the user can add to this -- state (this is called the user state.) The parser ignores this user -- state so you can use it however you wish. If you do not need a user -- state, just make it the unit type (). -- -- The parser also includes the notion of failure. Any parser can fail; a -- failed parser affects the behavior of combinators such as combine. The -- failure type should be a instance of -- System.Console.MultiArg.Error.Error. This allows you to define your -- own type and use it for the failure type, which can be useful when -- combining MultiArg with your own program. -- -- The underlying monad is m. This makes ParserT into a monad -- transformer; you can layer it on top of other monads. For instance you -- might layer it on top of the IO monad so that your parser can perform -- IO (for example, by examining the disk to see if arguments that -- specify files are valid.) If you don't need a monad transformer, just -- layer ParserT on top of Identity. data ParserT s e m a -- | The simplest parser runner; has no user state, an underlying monad -- Identity, and error type SimpleError. parse :: [Text] -> Parser a -> Exceptional SimpleError a -- | Runs a parser that has no user state and an underlying monad of -- Identity and is parameterized on the error type. parseE :: [Text] -> ParserE e a -> Exceptional e a -- | Runs a parser that has a user state and an underlying monad Identity. parseSE :: s -> [Text] -> ParserSE s e a -> (Exceptional e a, s) -- | The most complex parser runner. Runs a parser with a user-defined -- state, error type, and underlying monad. Returns the final parse -- result and the final user state, inside of the underlying monad. parseT :: Monad m => s -> [Text] -> ParserT s e m a -> m (Exceptional e a, s) -- | 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 :: Monad m => (a -> b) -> ParserT s e m a -> ParserT s e m b -- | good a always succeeds without consuming any input and has -- result a. This provides the implementation for return and -- pure. good :: Monad m => a -> ParserT s e m 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 :: Monad m => ParserT s e m (a -> b) -> ParserT s e m a -> ParserT s e m 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 :: Monad m => ParserT s e m a -> ParserT s e m a -> ParserT s e m 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 :: Monad m => ParserT s e m a -> (a -> ParserT s e m b) -> ParserT s e m 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 :: Monad m => ParserT s e m a -> ParserT s e m 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 :: Monad m => ParserT s e m a -> ParserT s e m [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 :: Monad m => ParserT s e m a -> ParserT s e m end -> ParserT s e m [a] -- | feed runs in a recursive loop. Each loop starts with three variables: -- a function f that takes an input i and returns a -- parser p, a function g that takes an input -- i and returns a parser e that must succeed for the -- recursion to end, and an initial input i. This proceeds as -- follows: -- --
    --
  1. Apply g to i and run resulting parser -- e. If this parser succeeds, feed succeeds and returns a list -- of all successful runs of p. The result of e is not -- returned, but otherwise the parser returned reflects the updated -- internal parser state from the running of e. (If that is a -- problem, wrap e in lookAhead.) If e fails and -- consumes input, feed fails and returns a failed parser whose internal -- state reflects the state after e fails. If e fails -- without consuming any input, proceed with the following steps.
    2. --
  2. Apply function f to input i, yielding a parser -- p. Run parser p. If p fails, feed also -- fails. If p succeeds, it yields a new input, -- i'.
    3. --
  3. If p succeeded without consuming any input, an infinite -- loop will result, so apply error.
    4. --
  4. Repeat from step 1, but with the new input retured from -- p, i'.
    5. --
-- -- For the initial application of feed, you supply the function -- f, the end parser e, and the initial state -- i. -- -- This function is useful for running multiple times a parser that -- depends on the result of previous runs of the parser. You could -- implement something similar using the user state feature, but for -- various reasons sometimes it is more useful to use feed -- instead. feed :: Monad m => (a -> ParserT s e m a) -> (a -> ParserT s e m end) -> a -> ParserT s e m [a] -- | Lifts a computation of the underlying monad into the ParserT monad. -- This provides the implementation for lift. parserLift :: Monad m => m a -> ParserT s e m a -- | Lifts a computation from the IO monad into the ParserT monad. This -- provides the implementation for liftIO. parserIO :: (MonadIO m, Error e) => IO a -> ParserT s e m a -- | throw e always fails without consuming any input and returns a failed -- parser with error state e. throw :: Monad m => e -> ParserT s e m 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 :: (Error e, Monad m) => String -> ParserT s e m a -- | Fail with an unhelpful error message. Usually throw is more useful, -- but this is handy to implement some typeclass instances. genericThrow :: (Monad m, Error e) => ParserT s e m a -- | 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 changes the -- error using the function given. () :: Monad m => ParserT s e m a -> e -> ParserT s e m a -- | try p behaves just like p, but if p fails, try p will not consume any -- input. try :: Monad m => ParserT s e m a -> ParserT s e m 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; -- returns the short option parsed. pendingShortOpt :: (Monad m, Error e) => ShortOpt -> ParserT s e m ShortOpt -- | 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. Returns the short option parsed. nonPendingShortOpt :: (Error e, Monad m) => ShortOpt -> ParserT s e m ShortOpt -- | 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 text of the pending short option argument -- (this text cannot be empty). pendingShortOptArg :: (Error e, Monad m) => ParserT s e m Text -- | 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 :: (Error e, Monad m) => LongOpt -> ParserT s e m (LongOpt, Maybe Text) -- | 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. approxLongOpt :: (Error e, Monad m) => Set LongOpt -> ParserT s e m (Text, LongOpt, Maybe Text) -- | Parses a stopper - that is, a double dash. Changes the internal -- state of the parser to reflect that a stopper has been seen. stopper :: (Error e, Monad m) => ParserT s e m () -- | 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 :: (Error e, Monad m) => ParserT s e m Text -- | Returns the next string on the command line as long as there are no -- pendings and as long as the next string does not begin with a dash. If -- there has already been a stopper, then will return the next string -- even if it starts with a dash. nonOptionPosArg :: (Error e, Monad m) => ParserT s e m Text -- | Succeeds if there is no more input left. end :: (Error e, Monad m) => ParserT s e m () -- | Gets the user state. get :: Monad m => ParserT s e m s -- | Puts a new user state. put :: Monad m => s -> ParserT s e m () -- | Modify the user state. modify :: Monad m => (s -> s) -> ParserT s e m () instance Show s => Show (ParseSt s) instance Eq s => Eq (ParseSt s) instance (MonadIO m, Error e) => MonadIO (ParserT s e m) instance MonadTrans (ParserT s e) instance (Monad m, Error e) => MonadPlus (ParserT s e m) instance (Error e, Monad m) => Monad (ParserT s e m) instance (Monad m, Error e) => Alternative (ParserT s e m) instance (Monad m, Error e) => Monoid (ParserT s e m a) instance Monad m => Applicative (ParserT s e m) instance Monad m => Functor (ParserT s e m) -- | 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 -- | option x p runs parser p. If p fails without consuming any -- input, returns x. Otherwise, returns p. option :: (Error e, Monad m) => a -> ParserT s e m a -> ParserT s e m 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. optionMaybe :: (Error e, Monad m) => ParserT s e m a -> ParserT s e m (Maybe a) -- | 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 :: (Error e, Monad m) => ParserT s e m a -> ParserT s e m () -- | 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.) shortNoArg :: (Error e, Monad m) => ShortOpt -> ParserT s e m ShortOpt -- | 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). shortOptionalArg :: (Error e, Monad m) => ShortOpt -> ParserT s e m (ShortOpt, Maybe 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). shortOneArg :: (Error e, Monad m) => ShortOpt -> ParserT s e m (ShortOpt, 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. shortTwoArg :: (Error e, Monad m) => ShortOpt -> ParserT s e m (ShortOpt, Text, 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. shortVariableArg :: (Error e, Monad m) => ShortOpt -> ParserT s e m (ShortOpt, [Text]) -- | 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). nonGNUexactLongOpt :: (Error e, Monad m) => LongOpt -> ParserT s e m LongOpt -- | 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. matchApproxLongOpt :: (Error e, Monad m) => LongOpt -> Set LongOpt -> ParserT s e m (Text, LongOpt, Maybe Text) -- | Like matchApproxLongOpt but only parses non-GNU-style long options. matchNonGNUApproxLongOpt :: (Error e, Monad m) => LongOpt -> Set LongOpt -> ParserT s e m (Text, LongOpt) -- | Parses long options that do not take any argument. longNoArg :: (Error e, Monad m) => LongOpt -> ParserT s e m LongOpt -- | 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). longOptionalArg :: (Error e, Monad m) => LongOpt -> ParserT s e m (LongOpt, Maybe 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). longOneArg :: (Error e, Monad m) => LongOpt -> ParserT s e m (LongOpt, 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. longTwoArg :: (Error e, Monad m) => LongOpt -> ParserT s e m (LongOpt, Text, 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. longVariableArg :: (Error e, Monad m) => LongOpt -> ParserT s e m (LongOpt, [Text]) -- | Parses at least one long option and a variable number of short and -- long options that take no arguments. 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 an optional argument. mixedOptionalArg :: (Error e, Monad m) => LongOpt -> [LongOpt] -> [ShortOpt] -> ParserT s e m (Either ShortOpt LongOpt, Maybe Text) -- | Parses at least one long option and additional long and short options -- that take one argument. mixedOneArg :: (Error e, Monad m) => LongOpt -> [LongOpt] -> [ShortOpt] -> ParserT s e m (Either ShortOpt LongOpt, Text) -- | Parses at least one long option and additonal long and short options -- that take two arguments. mixedTwoArg :: (Error e, Monad m) => LongOpt -> [LongOpt] -> [ShortOpt] -> ParserT s e m (Either ShortOpt LongOpt, Text, Text) -- | Parses at least one long option and additional long and short options -- that take a variable number of arguments. mixedVariableArg :: (Error e, Monad m) => LongOpt -> [LongOpt] -> [ShortOpt] -> ParserT s e m (Either ShortOpt LongOpt, [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. matchApproxWord :: (Error e, Monad m) => Set Text -> ParserT s e m (Text, Text) -- | 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 -- SampleParser. module System.Console.MultiArg.SimpleParser -- | Specifies each option that your program accepts. data OptSpec OptSpec :: String -> [Char] -> [String] -> Args -> OptSpec -- | Each option must have at least one long option, which you specify -- here. Your program's users specify long options by preceding them with -- two dashes, such as --verbose. When writing your code you -- omit the dashes, so you would specify verbose here; including -- the dashes in your code results in a runtime error. longOpt :: OptSpec -> String -- | Additional, synonymous short options may be specified here. For -- instance if you want your users to be able to specify -v in -- addition to --verbose, include v in this list. shortOpts :: OptSpec -> [Char] -- | Additional synonymous long options may be specified here. For -- instance, if you specified quiet for longOpt, you -- might want to include silent in this list. longOpts :: OptSpec -> [String] -- | Specifies what arguments, if any, this option takes. argSpec :: OptSpec -> Args -- | 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 -- | Holds the result of command line parsing. Each option (along with its -- option arguments) or positional argument is assigned to its own -- Result. data Result PosArg :: String -> Result posArg :: Result -> String Stopper :: Result Option :: String -> Args -> Result -- | Each option must have at least one long option. So that you can -- distinguish one option from another, the name of that long option is -- returned here. label :: Result -> String args :: Result -> Args -- | This datatype does dual duty. When part of an OptSpec, you use -- it to specify how many arguments, if any, an option takes. When you -- use it for this purpose, it only matters which data constructor you -- use; the fields can be any value, even undefined. -- -- When part of a Result, Args indicates what arguments the user -- supplied to the option. data Args -- | This option takes no arguments NoArg :: Args -- | 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 -> Args oArg :: Args -> Maybe String -- | 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 -> Args sArg1 :: Args -> String -- | This option takes two arguments. Parsed similarly to OneArg. TwoArg :: String -> String -> Args tArg1 :: Args -> String tArg2 :: Args -> String -- | 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] -> Args vArgs :: Args -> [String] -- | Specify that this option takes no arguments. noArg :: Args -- | Specify that this option takes an optional argument. optionalArg :: Args -- | Specify that this option takes one argument. oneArg :: Args -- | Specify that this option takes two arguments. twoArg :: Args -- | Specify that this option takes a variable number of arguments. variableArg :: Args -- | A simple type that is already an instance of Error. data SimpleError -- | Computation getArgs returns a list of the program's command -- line arguments (not including the program name). getArgs :: IO [String] -- | Parse a command line. parse :: Intersperse -> [OptSpec] -> [String] -> Either SimpleError [Result] instance Show Args instance Show OptSpec instance Show Result -- | A combinator library for building command-line parsers. module System.Console.MultiArg -- | 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, there is a -- sample.hs file in the binaries directory of the -- multiarg archive that you can compile. module System.Console.MultiArg.SampleParser specs :: [OptSpec] sampleMain :: IO ()