-- 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.1.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.QuickCheckHelpers randText :: Gen Text randSet :: (Ord a, Arbitrary a) => Gen (Set a) newtype WText WText :: Text -> WText unWText :: WText -> Text instance Show WText instance CoArbitrary WText instance Arbitrary WText module System.Console.MultiArg.TextNonEmpty data TextNonEmpty TextNonEmpty :: Char -> Text -> TextNonEmpty instance Show TextNonEmpty instance Eq TextNonEmpty instance CoArbitrary TextNonEmpty instance Arbitrary 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 instance Arbitrary LongOpt instance Arbitrary ShortOpt -- | 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 -- System.Console.MultiArg.Prim.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 Arbitrary Saw instance Arbitrary Expecting instance Arbitrary SimpleError instance Error SimpleError -- | 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 Prelude.Functor.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 -- Control.Monad.Monad.return and -- Control.Applicative.Applicative.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 -- Control.Monad.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. 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] -- | 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 Control.Monad.Monad.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 -- System.Console.MultiArg.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 ()