-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Command lines for options that take multiple arguments -- @package multiarg @version 0.30.0.4 -- | Vocabulary used throughout Multiarg. -- -- Each time one of these words is used in the documentation, it is -- italicized (or, if you are viewing the source code directly -- rather than through Haddock, it is surrounded by slashes). -- -- module Multiarg.Vocabulary -- | These modules provide examples. Since they are live code, cabal -- compiles them, which ensures that the examples actually compile. In -- addition, the examples are used as fodder for the test cases; this -- provides assurance not only that the library is tested but also that -- the examples work as they should. -- -- Multiarg.Examples.Telly provides an example parser for a -- command that does not have modes; this is the sort of parser you build -- with Multiarg. Multiarg.Examples.Grover provides an -- example of a parser for multiple modes; you build this sort of parser -- using Multiarg.Mode. -- -- To see these examples in action, compile the library using the -- "programs" flag, like so: -- -- 
--   cabal configure -fprograms
--   cabal build
--
-- -- This will create two programs, telly and grover. You -- simply pass words to these programs just like an ordinary user -- would, and the programs will print the results of what they parse. If -- you entered words that parse correctly, you will see this -- result; if there are any errors, you will see that instead. For -- example: -- -- 
--   >>> dist/build/telly/telly --uno testarg filename
--   [Uno "testarg",PosArg "filename"]
--
-- -- 
--   >>> dist/build/grover/grover --verbose 2 int --double 5 2
--   Right (ModeResult [Right (Verbose 2)] (Right (Ints [Right (Double 5 2)])))
--
module Multiarg.Examples -- | Types used throughout Multiarg, and associated functions. Ordinarily -- you should not need this module; Multiarg and -- Multiarg.Mode export all the types and constructors you should -- ordinarily need. However, if you want more control than those modules -- afford, you can import this one. module Multiarg.Types -- | Specifies how many option arguments an option takes. data ArgSpec a -- | This option takes no option arguments ZeroArg :: a -> ArgSpec a -- | This option takes one option argument OneArg :: (String -> a) -> ArgSpec a -- | This option takes two option arguments TwoArg :: (String -> String -> a) -> ArgSpec a -- | This option takes three option arguments ThreeArg :: (String -> String -> String -> a) -> ArgSpec a -- | Specifies an option. Typically you will use optSpec to -- create an OptSpec rather than using the constructor directly. -- Each OptSpec may contain mulitple short option names and -- long option names; but each OptSpec contains only one -- ArgSpec. Therefore, all short option names and long -- option names specified in a single OptSpec are synonymous. data OptSpec a OptSpec :: [ShortName] -> [LongName] -> (ArgSpec a) -> OptSpec a -- | Creates an OptSpec. optSpec :: [Char] -> [String] -> ArgSpec a -> OptSpec a -- | A short option name. data ShortName shortNameToChar :: ShortName -> Char -- | Creates a short option name. Any character other than a single -- hyphen will succeed. shortName :: Char -> Maybe ShortName -- | A long option name. data LongName longNameToString :: LongName -> String -- | Creates a long option name. The string may not be empty, and -- the first character may not be a hyphen. In addition, no character may -- be an equal sign. longName :: String -> Maybe LongName -- | A word supplied by the user on the command line. newtype Word Word :: String -> Word -- | The name of an option (either a short option name -- or a long option name). newtype OptName OptName :: (Either ShortName LongName) -> OptName optNameToString :: OptName -> String -- | An option argument. newtype OptArg OptArg :: String -> OptArg optArgToString :: OptArg -> String -- | Characters after the first short option name in a flag -- that specifies a short option instance, if the user supplies -- -afoobar, then this will be foobar. newtype ShortTail ShortTail :: String -> ShortTail -- | Is this word an input for a long option? isLong :: Word -> Maybe (LongName, Maybe OptArg) -- | Is this an input word for a short argument? isShort :: Word -> Maybe (ShortName, ShortTail) wordToOptArg :: Word -> OptArg -- | If possible, splits a ShortTail into a short option name and a -- remaining tail. splitShortTail :: ShortTail -> Maybe (ShortName, ShortTail) instance Eq ShortName instance Ord ShortName instance Show ShortName instance Eq LongName instance Ord LongName instance Show LongName instance Show (OptSpec a) instance Eq OptName instance Ord OptName instance Show OptName instance Eq Word instance Ord Word instance Show Word instance Eq OptArg instance Ord OptArg instance Show OptArg instance Eq ShortTail instance Ord ShortTail instance Show ShortTail instance Functor OptSpec instance Show (ArgSpec a) instance Functor ArgSpec -- | Maddash is a Mealy finite state machine that processes options. -- Ordinarily you will not need this module; instead, see Multiarg -- for most uses or Multiarg.Mode for commands that have more than -- one mode. -- -- The machine consists of the following parts: -- -- module Multiarg.Maddash -- | The name of an option (either a short option name -- or a long option name). newtype OptName OptName :: (Either ShortName LongName) -> OptName -- | Creates an OptSpec. optSpec :: [Char] -> [String] -> ArgSpec a -> OptSpec a -- | Specifies how many option arguments an option takes. data ArgSpec a -- | This option takes no option arguments ZeroArg :: a -> ArgSpec a -- | This option takes one option argument OneArg :: (String -> a) -> ArgSpec a -- | This option takes two option arguments TwoArg :: (String -> String -> a) -> ArgSpec a -- | This option takes three option arguments ThreeArg :: (String -> String -> String -> a) -> ArgSpec a -- | A short option name. data ShortName -- | A long option name. data LongName -- | Creates a short option name. Any character other than a single -- hyphen will succeed. shortName :: Char -> Maybe ShortName -- | Creates a long option name. The string may not be empty, and -- the first character may not be a hyphen. In addition, no character may -- be an equal sign. longName :: String -> Maybe LongName shortNameToChar :: ShortName -> Char longNameToString :: LongName -> String data Output a Good :: a -> Output a OptionError :: OptionError -> Output a data Pallet a NotAnOption :: Pallet a Full :: [Output a] -> Pallet a data State a -- | Accepting new words Ready :: State a -- | In the middle of processing an option; this function will be -- applied to the next word to get a result Pending :: OptName -> (Word -> ([Output a], State a)) -> State a isReady :: State a -> Bool isPending :: State a -> Bool -- | Process a single word in the machine. processWord :: [(ShortName, ArgSpec a)] -> [(LongName, ArgSpec a)] -> State a -> Word -> (Pallet a, State a) -- | Processes multiple words in the machine. Processing ends with -- the first word that is NotAnOption. This first -- word that is NotAnOption, and all remaining -- words, are returned in the result. A list of all lists of -- Output are also returned, with one list for each input -- Word that was processed. Each of these lists may be of any -- length. For instance, if the input word is the flag for -- a long option that takes two option arguments, the -- corresponding list will be empty. If the input word is a -- flag for a short option, this list may have more than -- one element. processWords :: [(ShortName, ArgSpec a)] -> [(LongName, ArgSpec a)] -> [Word] -> ([[Output a]], Either (OptName, Word -> ([Output a], State a)) [Word]) -- | An option argument. newtype OptArg OptArg :: String -> OptArg optArgToString :: OptArg -> String data OptionError BadOption :: OptName -> OptionError -- | The user gave an argument for a long option that does not take an -- argument. LongArgumentForZeroArgumentOption :: LongName -> OptArg -> OptionError instance Eq OptionError instance Ord OptionError instance Show OptionError instance Eq a => Eq (Output a) instance Ord a => Ord (Output a) instance Show a => Show (Output a) instance Eq a => Eq (Pallet a) instance Ord a => Ord (Pallet a) instance Show a => Show (Pallet a) instance Show (State a) instance Functor State instance Functor Pallet instance Functor Output -- | Processes both options and positional arguments. -- Functions here return both any successful results and any errors. -- Ordinarily you will not need this module; instead, see Multiarg -- for most uses or Multiarg.Mode for commands that have more than -- one mode. module Multiarg.Limeline data PosArg a PosArg :: a -> PosArg a -- | Processes a command line where options are interspersed with -- positional arguments. A stopper is not returned; all -- words after a stopper are treated as positional -- arguments. interspersed :: [(ShortName, ArgSpec a)] -> [(LongName, ArgSpec a)] -> (String -> a) -> [Word] -> ([Either [Output a] (PosArg a)], Maybe OptName) instance Eq a => Eq (PosArg a) instance Ord a => Ord (PosArg a) instance Show a => Show (PosArg a) instance Functor PosArg -- | Grab bag of miscellaneous functions. module Multiarg.Util -- | Returns a list of the first items in a list and the last item, or -- Nothing if the list is empty. mayLast :: [a] -> Maybe ([a], a) -- | Partitions a list of OptSpec into the short flags and long -- flags. splitOptSpecs :: [OptSpec a] -> ([(ShortName, ArgSpec a)], [(LongName, ArgSpec a)]) -- | Adds an option for h and help. The resulting -- ArgSpec return Nothing if help was requested, or -- Just with the original argument for any other option. addHelpOption :: [OptSpec a] -> ([(ShortName, ArgSpec (Maybe a))], [(LongName, ArgSpec (Maybe a))]) -- | Functions and types used by the Multiarg module. You don't have -- to worry about "breaking" anything by using this module. This module -- is separate from Multiarg only because it makes the -- documentation in that module cleaner, as that module should satisfy -- most use cases. Use this module if you want more control over error -- handling, or if you want to process arguments using pure functions -- rather than IO functions. module Multiarg.Internal limelineOutputToParsedCommandLine :: ([Either [Output a] (PosArg a)], Maybe OptName) -> ParsedCommandLine a -- | Indicates the result of parsing a command line. data ParsedCommandLine a -- | ParsedCommandLine a b, where: -- -- a is a list of errors and results, in the original order in -- which they appeared on the command line. -- -- b is Just p if the user included an option at -- the end of the command line and there were not enough following -- words to provide the option with its necessary option -- arguments, where p is the name of the -- option with insufficient option arguments; otherwise -- Nothing. ParsedCommandLine :: [Either OptionError a] -> (Maybe OptName) -> ParsedCommandLine a -- | Gets the results from a parsed command line. If there were errors, -- returns a Left with an error message; otherwise, returns a -- Right with a list of the results. parsedResults :: ParsedCommandLine a -> Either (String, [String]) [a] insufficientOptArgs :: OptName -> String optError :: OptionError -> String -- | Parses a command line; a pure function (unlike -- parseCommandLineIO). parseCommandLinePure :: [OptSpec a] -> (String -> a) -> [String] -> ParsedCommandLine a -- | Parses a command line. Runs in the IO monad so that it can do some -- tedious things for you: -- -- -- -- If you don't want this degree of automation or if you want a pure -- function, see the parseCommandLinePure function in the -- Multiarg.Internal module. parseCommandLine :: (String -> String) -> [OptSpec a] -> (String -> a) -> IO [a] -- | Automatically adds a short option, -h, and a long -- option, --help. Intended primarily for use by the -- parseCommandLineIO function. parseCommandLineHelp :: [OptSpec a] -> (String -> a) -> [String] -> ParsedCommandLine (Maybe a) instance Eq a => Eq (ParsedCommandLine a) instance Ord a => Ord (ParsedCommandLine a) instance Show a => Show (ParsedCommandLine a) instance Functor ParsedCommandLine -- | Internal functions used by Multiarg.Mode. You don't have to -- worry about "breaking" anything by using this module; it is separate -- from Multiarg.Mode primarily to tidy up the documentation in -- that module. The functions in Multiarg.Mode should satisfy most -- use cases. However, if you want more control over error handling, you -- can use this module. module Multiarg.Mode.Internal newtype ModeName ModeName :: String -> ModeName data ParsedMode a ModeGood :: a -> ParsedMode a -- | There was an error. There may be zero or more initial OptionError. -- There must be at least one error, which is either an OptionError or -- the name of an option, if the error is that there were not enough -- words following the option to provide it with its necessary arguments. ModeError :: [OptionError] -> (Either OptionError OptName) -> ParsedMode a -- | A Mode represents a single command line mode, such as -- check for ghc-pkg check. It contains the name of the -- mode, as well as a parser that handles all options and -- positional arguments for the mode. Ordinarily you will create a -- Mode using the mode function rather than by using the -- constructor directly. data Mode r Mode :: ModeName -> ([Word] -> ParsedMode r) -> Mode r parsedCommandLineToParsedMode :: ([a] -> r) -> ParsedCommandLine a -> ParsedMode r -- | Creates a new Mode. mode :: String -> [OptSpec a] -> (String -> a) -> ([a] -> r) -> Mode r data GlobalLocalEnd a GlobalInsufficientOptArgs :: OptName -> GlobalLocalEnd a ModeNotFound :: String -> [String] -> GlobalLocalEnd a NoMode :: GlobalLocalEnd a ModeFound :: (ParsedMode a) -> GlobalLocalEnd a data GlobalLocal g r GlobalLocal :: [Either OptionError g] -> (GlobalLocalEnd r) -> GlobalLocal g r -- | The result of parsing a mode command line. data ModeResult g r -- | ModeResult a b is a successfully parsed mode command line, -- where: -- -- a is a list of all global options parsed; and -- -- b indicates the result of parsing the mode. It is Either -- c d, where Left c indicates that no mode was parsed. -- This arises under two circumstances. If the user did not include any -- words after the global options, then c will be -- the empty list, []. If the user did include words -- after the global options, but the first word was not recognized -- as a mode, then this list will contain the first word and any -- subsequent words. Therefore, note that if the user attempted to -- use a mode that does not exist (e.g. she misspelled it), this is not -- treated as an error. It's up to the client code to deal with this -- issue (for instance, your program might not view this situation as -- being an error.) -- -- If b is Right d, this indicates that the user -- entered a recognized mode, and the result is d. ModeResult :: [g] -> (Either [String] r) -> ModeResult g r getModeResult :: GlobalLocal g r -> Either (String, [String]) (ModeResult g r) combine :: Either (OptionError, [OptionError]) [g] -> Either (String, [String]) (Either [String] r) -> Either (String, [String]) (ModeResult g r) endToModeResult :: GlobalLocalEnd a -> Either (String, [String]) (Either [String] a) extractParsedMode :: ParsedMode a -> Either (String, [String]) (Either b a) globalOptErrorToString :: OptionError -> String modeOptErrorToString :: OptionError -> String optErrorToString :: String -> OptionError -> String eiToError :: Either OptionError OptName -> String labeledInsufficientOptArgs :: String -> OptName -> String -- | Parses a command line that may contain modes. parseModeLine :: [OptSpec g] -> [Mode r] -> [String] -> Either (String, [String]) (ModeResult g r) parseModeLineWithErrors :: [OptSpec g] -> [Mode r] -> [String] -> GlobalLocal g r -- | Takes a token and a list of all modes; returns the matching mode if -- there is one, or Nothing if there is no match. findExactMode :: Word -> [Mode a] -> Maybe (Mode a) instance Eq ModeName instance Ord ModeName instance Show ModeName instance Eq a => Eq (ParsedMode a) instance Ord a => Ord (ParsedMode a) instance Show a => Show (ParsedMode a) instance Eq a => Eq (GlobalLocalEnd a) instance Ord a => Ord (GlobalLocalEnd a) instance Show a => Show (GlobalLocalEnd a) instance (Eq g, Eq r) => Eq (GlobalLocal g r) instance (Ord g, Ord r) => Ord (GlobalLocal g r) instance (Show g, Show r) => Show (GlobalLocal g r) instance (Eq g, Eq r) => Eq (ModeResult g r) instance (Ord g, Ord r) => Ord (ModeResult g r) instance (Show g, Show r) => Show (ModeResult g r) instance Functor Mode instance Functor ParsedMode -- | Helps you build command-line parsers for programs that have more than -- one so-called mode; examples of such programs include -- git, darcs, and ghc-pkg. module Multiarg.Mode -- | Specifies how many option arguments an option takes. data ArgSpec a -- | This option takes no option arguments ZeroArg :: a -> ArgSpec a -- | This option takes one option argument OneArg :: (String -> a) -> ArgSpec a -- | This option takes two option arguments TwoArg :: (String -> String -> a) -> ArgSpec a -- | This option takes three option arguments ThreeArg :: (String -> String -> String -> a) -> ArgSpec a -- | Specifies an option. Typically you will use optSpec to -- create an OptSpec rather than using the constructor directly. -- Each OptSpec may contain mulitple short option names and -- long option names; but each OptSpec contains only one -- ArgSpec. Therefore, all short option names and long -- option names specified in a single OptSpec are synonymous. data OptSpec a -- | Creates an OptSpec. optSpec :: [Char] -> [String] -> ArgSpec a -> OptSpec a -- | A Mode represents a single command line mode, such as -- check for ghc-pkg check. It contains the name of the -- mode, as well as a parser that handles all options and -- positional arguments for the mode. Ordinarily you will create a -- Mode using the mode function rather than by using the -- constructor directly. data Mode r -- | Creates a new Mode. mode :: String -> [OptSpec a] -> (String -> a) -> ([a] -> r) -> Mode r -- | The result of parsing a mode command line. data ModeResult g r -- | ModeResult a b is a successfully parsed mode command line, -- where: -- -- a is a list of all global options parsed; and -- -- b indicates the result of parsing the mode. It is Either -- c d, where Left c indicates that no mode was parsed. -- This arises under two circumstances. If the user did not include any -- words after the global options, then c will be -- the empty list, []. If the user did include words -- after the global options, but the first word was not recognized -- as a mode, then this list will contain the first word and any -- subsequent words. Therefore, note that if the user attempted to -- use a mode that does not exist (e.g. she misspelled it), this is not -- treated as an error. It's up to the client code to deal with this -- issue (for instance, your program might not view this situation as -- being an error.) -- -- If b is Right d, this indicates that the user -- entered a recognized mode, and the result is d. ModeResult :: [g] -> (Either [String] r) -> ModeResult g r -- | Parses a command line that may contain modes. parseModeLine :: [OptSpec g] -> [Mode r] -> [String] -> Either (String, [String]) (ModeResult g r) -- | Grover is a simple example program that shows how to write a parser -- for commands with multiple modes. You build such parsers using -- Multiarg.Mode. It provides an example for the documentation, -- and it also provides fodder for the QuickCheck tests. You will want to -- look at the source code. -- -- Grover has three modes: int, string, and -- maybe. Each of these modes has three options: -z or -- --zero, which takes no arguments; -s or -- --single, which takes one argument; -d or -- --double, which takes two arguments; and -t or -- --triple, which takes three arguments. The type of the -- argument depends on the mode. For int, the argument or -- arguments must be an integer; for string the arguments can be -- any string; and for maybe the arguments must be a Maybe Int, -- such as Nothing or Just 5. -- -- Each mode also accepts any number of positional arguments, which can -- be any string. -- -- Grover handles simple errors right inside the parser by using the -- Either type as a return value. module Multiarg.Examples.Grover -- | Grover's global options. data Global Help :: Global -- | The Int would indicate, for example, the desired level of verbosity. Verbose :: Int -> Global Version :: Global -- | Handles all options and positional arguments for any Grover mode. data GroverOpt a Zero :: GroverOpt a Single :: a -> GroverOpt a Double :: a -> a -> GroverOpt a Triple :: a -> a -> a -> GroverOpt a PosArg :: String -> GroverOpt a -- | All of Grover's global options. The OptSpec is parameterized on -- an Either to allow for error handling. If the user enters a -- non-integer argument for the --verbose option, a -- Left with an error message is returned. globalOptSpecs :: [OptSpec (Either String Global)] -- | A list of OptSpec that works for any Mode. modeOptSpecs :: Read a => [OptSpec (Either String (GroverOpt a))] -- | Holds the results of parsing Grover's modes. data Result Ints :: [Either String (GroverOpt Int)] -> Result Strings :: [Either String (GroverOpt String)] -> Result Maybes :: [Either String (GroverOpt (Maybe Int))] -> Result -- | All Grover modes. modes :: [Mode Result] -- | Reads a value. If it cannot be read, returns an error message. readErr :: Read a => String -> Either String a -- | Parses all of Grover's options and modes. parseGrover :: [String] -> Either (String, [String]) (ModeResult (Either String Global) Result) instance Eq Global instance Ord Global instance Show Global instance Eq a => Eq (GroverOpt a) instance Ord a => Ord (GroverOpt a) instance Show a => Show (GroverOpt a) instance Eq Result instance Ord Result instance Show Result instance Functor GroverOpt -- | Parse command lines with options that might take multiple -- option arguments. -- -- I built this library could not find anything that would readily parse -- command lines where the options took more than one option -- argument. For example, for the tail command on GNU -- systems, the --lines option takes one option -- argument to specify how many lines you want to see. Well, what if -- you want to build a program with an option that takes two option -- arguments, like --foo bar baz? I found no such library so -- I built this one. -- -- Please consult the Multiarg.Vocabulary module to learn common -- vocabulary used throughout Multiarg and its documentation. Words that -- appear in italics are defined in Multiarg.Vocabulary. -- -- Use this module to build parsers for simple commands. The -- parseCommandLine function runs in the IO monad and will cause -- your program to exit unsuccessfully if there are any errors in the -- command line, printing an error message in the process. If you want -- more control over error handling, use the Multiarg.Internal -- module. -- -- To write parsers for commands with multiple modes (for instance, -- ghc-pkg has multiple modes, such as ghc-pkg list and -- ghc-pkg check) use the Multiarg.Mode module. -- -- You will find examples in Multiarg.Examples.Telly for non-mode -- parsers, and in Multiarg.Examples.Grover for mode parsers. module Multiarg -- | Specifies how many option arguments an option takes. data ArgSpec a -- | This option takes no option arguments ZeroArg :: a -> ArgSpec a -- | This option takes one option argument OneArg :: (String -> a) -> ArgSpec a -- | This option takes two option arguments TwoArg :: (String -> String -> a) -> ArgSpec a -- | This option takes three option arguments ThreeArg :: (String -> String -> String -> a) -> ArgSpec a -- | Specifies an option. Typically you will use optSpec to -- create an OptSpec rather than using the constructor directly. -- Each OptSpec may contain mulitple short option names and -- long option names; but each OptSpec contains only one -- ArgSpec. Therefore, all short option names and long -- option names specified in a single OptSpec are synonymous. data OptSpec a -- | Creates an OptSpec. optSpec :: [Char] -> [String] -> ArgSpec a -> OptSpec a -- | Parses a command line. Runs in the IO monad so that it can do some -- tedious things for you: -- -- -- -- If you don't want this degree of automation or if you want a pure -- function, see the parseCommandLinePure function in the -- Multiarg.Internal module. parseCommandLine :: (String -> String) -> [OptSpec a] -> (String -> a) -> IO [a] -- | Telly is a simple command-line program to test command-line parsers -- that do not have multiple modes. This includes most command-line -- programs; you build parsers like this using Multiarg. This -- module provides an example for documentation purposes; it also -- provides fodder for the QuickCheck test cases. You will want to look -- at the source code. module Multiarg.Examples.Telly -- | A data type to hold the result of command line parsing. data Telly -- | Positional argument PosArg :: String -> Telly -- | --empty, -e Empty :: Telly -- | --single, -s Single :: String -> Telly -- | --double, -d Double :: String -> String -> Telly -- | --triple, -t Triple :: String -> String -> String -> Telly -- | 
--   -0
--
Zero :: Telly -- | 
--   -1
--
One :: String -> Telly -- | 
--   -2
--
Two :: String -> String -> Telly -- | 
--   -3
--
Three :: String -> String -> String -> Telly -- | 
--   --cero
--
Cero :: Telly -- | 
--   --uno
--
Uno :: String -> Telly -- | 
--   --dos
--
Dos :: String -> String -> Telly -- | 
--   --tres
--
Tres :: String -> String -> String -> Telly optSpecs :: [OptSpec Telly] help :: String -> String parse :: IO [Telly] instance Eq Telly instance Ord Telly instance Show Telly