-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Command lines for options that take multiple arguments
--   
--   multiarg helps you build command-line parsers for programs with
--   options that take more than one argument. See the documentation in the
--   Multiarg module for details.
@package multiarg
@version 0.30.0.10


-- | 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.
--   
--   <a>Multiarg.Examples.Telly</a> provides an example parser for a
--   command that does not have modes; this is the sort of parser you build
--   with <a>Multiarg</a>. <a>Multiarg.Examples.Grover</a> provides an
--   example of a parser for multiple modes; you build this sort of parser
--   using <a>Multiarg.Mode</a>.
--   
--   To see these examples in action, compile the library using the
--   "programs" flag, like so:
--   
--   <pre>
--   cabal configure -fprograms
--   cabal build
--   </pre>
--   
--   This will create two programs, <tt>telly</tt> and <tt>grover</tt>. You
--   simply pass <i>words</i> to these programs just like an ordinary user
--   would, and the programs will print the results of what they parse. If
--   you entered <i>words</i> that parse correctly, you will see this
--   result; if there are any errors, you will see that instead. For
--   example:
--   
--   <pre>
--   &gt;&gt;&gt; dist/build/telly/telly --uno testarg filename
--   [Uno "testarg",PosArg "filename"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; dist/build/grover/grover --verbose 2 int --double 5 2
--   Right (ModeResult [Right (Verbose 2)] (Right (Ints [Right (Double 5 2)])))
--   </pre>
module Multiarg.Examples


-- | Types used throughout Multiarg, and associated functions. Ordinarily
--   you should not need this module; <a>Multiarg</a> and
--   <a>Multiarg.Mode</a> 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 <i>option arguments</i> an <i>option</i> takes.
data ArgSpec a

-- | This <i>option</i> takes no <i>option arguments</i>
ZeroArg :: a -> ArgSpec a

-- | This <i>option</i> takes one <i>option argument</i>
OneArg :: (String -> a) -> ArgSpec a

-- | This <i>option</i> takes two <i>option arguments</i>
TwoArg :: (String -> String -> a) -> ArgSpec a

-- | This <i>option</i> takes three <i>option arguments</i>
ThreeArg :: (String -> String -> String -> a) -> ArgSpec a

-- | Specifies an <i>option</i>. Typically you will use <a>optSpec</a> to
--   create an <a>OptSpec</a> rather than using the constructor directly.
--   Each <a>OptSpec</a> may contain mulitple <i>short option names</i> and
--   <i>long option names</i>; but each <a>OptSpec</a> contains only one
--   <a>ArgSpec</a>. Therefore, all <i>short option names</i> and <i>long
--   option names</i> specified in a single <a>OptSpec</a> are synonymous.
data OptSpec a
OptSpec :: [ShortName] -> [LongName] -> (ArgSpec a) -> OptSpec a

-- | Creates an <a>OptSpec</a>.
optSpec :: [Char] -> [String] -> ArgSpec a -> OptSpec a

-- | A <i>short option name</i>.
data ShortName
shortNameToChar :: ShortName -> Char

-- | Creates a <i>short option name</i>. Any character other than a single
--   hyphen will succeed.
shortName :: Char -> Maybe ShortName

-- | A <i>long option name</i>.
data LongName
longNameToString :: LongName -> String

-- | Creates a <i>long option name</i>. 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 <i>word</i> supplied by the user on the command line.
newtype Word
Word :: String -> Word

-- | The <i>name</i> of an <i>option</i> (either a <i>short option name</i>
--   or a <i>long option name</i>).
newtype OptName
OptName :: (Either ShortName LongName) -> OptName
optNameToString :: OptName -> String

-- | An <i>option argument</i>.
newtype OptArg
OptArg :: String -> OptArg
[optArgToString] :: OptArg -> String

-- | Characters after the first <i>short option name</i> in a <i>flag</i>
--   that specifies a <i>short option</i> instance, if the user supplies
--   <tt>-afoobar</tt>, then this will be <tt>foobar</tt>.
newtype ShortTail
ShortTail :: String -> ShortTail

-- | Is this <i>word</i> an input for a <i>long option</i>?
isLong :: Word -> Maybe (LongName, Maybe OptArg)

-- | Is this an input <i>word</i> for a <i>short argument</i>?
isShort :: Word -> Maybe (ShortName, ShortTail)
wordToOptArg :: Word -> OptArg

-- | If possible, splits a ShortTail into a <i>short option name</i> and a
--   remaining tail.
splitShortTail :: ShortTail -> Maybe (ShortName, ShortTail)
instance GHC.Show.Show Multiarg.Types.ShortTail
instance GHC.Classes.Ord Multiarg.Types.ShortTail
instance GHC.Classes.Eq Multiarg.Types.ShortTail
instance GHC.Show.Show Multiarg.Types.OptArg
instance GHC.Classes.Ord Multiarg.Types.OptArg
instance GHC.Classes.Eq Multiarg.Types.OptArg
instance GHC.Show.Show Multiarg.Types.Word
instance GHC.Classes.Ord Multiarg.Types.Word
instance GHC.Classes.Eq Multiarg.Types.Word
instance GHC.Show.Show Multiarg.Types.OptName
instance GHC.Classes.Ord Multiarg.Types.OptName
instance GHC.Classes.Eq Multiarg.Types.OptName
instance GHC.Show.Show (Multiarg.Types.OptSpec a)
instance GHC.Show.Show Multiarg.Types.LongName
instance GHC.Classes.Ord Multiarg.Types.LongName
instance GHC.Classes.Eq Multiarg.Types.LongName
instance GHC.Show.Show Multiarg.Types.ShortName
instance GHC.Classes.Ord Multiarg.Types.ShortName
instance GHC.Classes.Eq Multiarg.Types.ShortName
instance GHC.Base.Functor Multiarg.Types.OptSpec
instance GHC.Base.Functor Multiarg.Types.ArgSpec
instance GHC.Show.Show (Multiarg.Types.ArgSpec a)


-- | Maddash is a Mealy finite state machine that processes <i>options</i>.
--   Ordinarily you will not need this module; instead, see <a>Multiarg</a>
--   for most uses or <a>Multiarg.Mode</a> for commands that have more than
--   one mode.
--   
--   The machine consists of the following parts:
--   
--   <ul>
--   <li>The set of states, in <a>State</a></li>
--   <li>The start state, which is <a>Ready</a></li>
--   <li>The input alphabet, which is all <a>Word</a>s. A <a>Word</a> is an
--   input <i>word</i> from the command line.</li>
--   <li>The output alphabet, which is <a>Pallet</a>. A <a>Pallet</a>
--   indicates whether its input is not an option at all with
--   <a>NotAnOption</a>. This indicates that the input <a>Word</a> was not
--   a short option and was not a long option; that is, it was not a single
--   dash followed by a non-dash character and it was not a double dash
--   followed by another character. (Neither a single dash alone nor a
--   double dash alone is an option.) Anything else is an option and will
--   return <a>Full</a>, which is a list of <a>Output</a>. Each
--   <a>Output</a> indicates either an error or a good result.</li>
--   <li>The transition function and the output function are combined into
--   a single function, <a>processWord</a>.</li>
--   </ul>
module Multiarg.Maddash

-- | The <i>name</i> of an <i>option</i> (either a <i>short option name</i>
--   or a <i>long option name</i>).
newtype OptName
OptName :: (Either ShortName LongName) -> OptName

-- | Creates an <a>OptSpec</a>.
optSpec :: [Char] -> [String] -> ArgSpec a -> OptSpec a

-- | Specifies how many <i>option arguments</i> an <i>option</i> takes.
data ArgSpec a

-- | This <i>option</i> takes no <i>option arguments</i>
ZeroArg :: a -> ArgSpec a

-- | This <i>option</i> takes one <i>option argument</i>
OneArg :: (String -> a) -> ArgSpec a

-- | This <i>option</i> takes two <i>option arguments</i>
TwoArg :: (String -> String -> a) -> ArgSpec a

-- | This <i>option</i> takes three <i>option arguments</i>
ThreeArg :: (String -> String -> String -> a) -> ArgSpec a

-- | A <i>short option name</i>.
data ShortName

-- | A <i>long option name</i>.
data LongName

-- | Creates a <i>short option name</i>. Any character other than a single
--   hyphen will succeed.
shortName :: Char -> Maybe ShortName

-- | Creates a <i>long option name</i>. 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 <i>option</i>; 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 <i>words</i> in the machine. Processing ends with
--   the first <i>word</i> that is <a>NotAnOption</a>. This first
--   <i>word</i> that is <a>NotAnOption</a>, and all remaining
--   <i>words</i>, are returned in the result. A list of all lists of
--   <a>Output</a> are also returned, with one list for each input
--   <a>Word</a> that was processed. Each of these lists may be of any
--   length. For instance, if the input <i>word</i> is the <i>flag</i> for
--   a <i>long option</i> that takes two <i>option arguments</i>, the
--   corresponding list will be empty. If the input <i>word</i> is a
--   <i>flag</i> for a <i>short option</i>, 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 <i>option argument</i>.
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 GHC.Show.Show a => GHC.Show.Show (Multiarg.Maddash.Pallet a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Multiarg.Maddash.Pallet a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Multiarg.Maddash.Pallet a)
instance GHC.Show.Show a => GHC.Show.Show (Multiarg.Maddash.Output a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Multiarg.Maddash.Output a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Multiarg.Maddash.Output a)
instance GHC.Show.Show Multiarg.Maddash.OptionError
instance GHC.Classes.Ord Multiarg.Maddash.OptionError
instance GHC.Classes.Eq Multiarg.Maddash.OptionError
instance GHC.Base.Functor Multiarg.Maddash.Pallet
instance GHC.Base.Functor Multiarg.Maddash.State
instance GHC.Show.Show (Multiarg.Maddash.State a)
instance GHC.Base.Functor Multiarg.Maddash.Output


-- | Processes both <i>options</i> and <i>positional arguments</i>.
--   Functions here return both any successful results and any errors.
--   Ordinarily you will not need this module; instead, see <a>Multiarg</a>
--   for most uses or <a>Multiarg.Mode</a> for commands that have more than
--   one mode.
module Multiarg.Limeline
data PosArg a
PosArg :: a -> PosArg a

-- | Processes a command line where <i>options</i> are interspersed with
--   <i>positional arguments</i>. A <i>stopper</i> is not returned; all
--   <i>words</i> after a <i>stopper</i> are treated as <i>positional
--   arguments</i>.
interspersed :: [(ShortName, ArgSpec a)] -> [(LongName, ArgSpec a)] -> (String -> a) -> [Word] -> ([Either [Output a] (PosArg a)], Maybe OptName)
instance GHC.Show.Show a => GHC.Show.Show (Multiarg.Limeline.PosArg a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Multiarg.Limeline.PosArg a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Multiarg.Limeline.PosArg a)
instance GHC.Base.Functor Multiarg.Limeline.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 <a>OptSpec</a> into the short flags and long
--   flags.
splitOptSpecs :: [OptSpec a] -> ([(ShortName, ArgSpec a)], [(LongName, ArgSpec a)])

-- | Adds an option for <tt>h</tt> and <tt>help</tt>. The resulting
--   <a>ArgSpec</a> return <a>Nothing</a> if help was requested, or
--   <a>Just</a> 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 <a>Multiarg</a> module. You don't have
--   to worry about "breaking" anything by using this module. This module
--   is separate from <a>Multiarg</a> 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

-- | <tt>ParsedCommandLine a b</tt>, where:
--   
--   <tt>a</tt> is a list of errors and results, in the original order in
--   which they appeared on the command line.
--   
--   <tt>b</tt> is <tt>Just p</tt> if the user included an <i>option</i> at
--   the end of the command line and there were not enough following
--   <i>words</i> to provide the <i>option</i> with its necessary <i>option
--   arguments</i>, where <tt>p</tt> is the <i>name</i> of the
--   <i>option</i> with insufficient <i>option arguments</i>; otherwise
--   <a>Nothing</a>.
ParsedCommandLine :: [Either OptionError a] -> (Maybe OptName) -> ParsedCommandLine a

-- | Gets the results from a parsed command line. If there were errors,
--   returns a <a>Left</a> with an error message; otherwise, returns a
--   <a>Right</a> 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
--   <tt>parseCommandLineIO</tt>).
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:
--   
--   <ul>
--   <li>fetches the <i>words</i> on command line using <a>getArgs</a> and
--   the name of the program with <a>getProgName</a></li>
--   <li>prints help, if the user requested help, and exits
--   successfully</li>
--   <li>prints an error message and exits unsuccessfully, if the user
--   entered a bad command line (such as an unknown option)</li>
--   </ul>
--   
--   If you don't want this degree of automation or if you want a pure
--   function, see the <a>parseCommandLinePure</a> function in the
--   <a>Multiarg.Internal</a> module.
parseCommandLine :: (String -> String) -> [OptSpec a] -> (String -> a) -> IO [a]

-- | Automatically adds a <i>short option</i>, <tt>-h</tt>, and a <i>long
--   option</i>, <tt>--help</tt>. Intended primarily for use by the
--   <tt>parseCommandLineIO</tt> function.
parseCommandLineHelp :: [OptSpec a] -> (String -> a) -> [String] -> ParsedCommandLine (Maybe a)
instance GHC.Show.Show a => GHC.Show.Show (Multiarg.Internal.ParsedCommandLine a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Multiarg.Internal.ParsedCommandLine a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Multiarg.Internal.ParsedCommandLine a)
instance GHC.Base.Functor Multiarg.Internal.ParsedCommandLine


-- | Internal functions used by <a>Multiarg.Mode</a>. You don't have to
--   worry about "breaking" anything by using this module; it is separate
--   from <a>Multiarg.Mode</a> primarily to tidy up the documentation in
--   that module. The functions in <a>Multiarg.Mode</a> 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 <a>Mode</a> represents a single command line mode, such as
--   <tt>check</tt> for <tt>ghc-pkg check</tt>. It contains the name of the
--   mode, as well as a parser that handles all <i>options</i> and
--   <i>positional arguments</i> for the mode. Ordinarily you will create a
--   <a>Mode</a> using the <a>mode</a> 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 <a>Mode</a>.
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

-- | <tt>ModeResult a b</tt> is a successfully parsed mode command line,
--   where:
--   
--   <tt>a</tt> is a list of all global options parsed; and
--   
--   <tt>b</tt> indicates the result of parsing the mode. It is <tt>Either
--   c d</tt>, where <tt>Left c</tt> indicates that no mode was parsed.
--   This arises under two circumstances. If the user did not include any
--   <i>words</i> after the global <i>options</i>, then <tt>c</tt> will be
--   the empty list, <tt>[]</tt>. If the user did include <i>words</i>
--   after the global options, but the first <i>word</i> was not recognized
--   as a mode, then this list will contain the first <i>word</i> and any
--   subsequent <i>words</i>. 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 <tt>b</tt> is <tt>Right d</tt>, this indicates that the user
--   entered a recognized mode, and the result is <tt>d</tt>.
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 (GHC.Show.Show r, GHC.Show.Show g) => GHC.Show.Show (Multiarg.Mode.Internal.ModeResult g r)
instance (GHC.Classes.Ord r, GHC.Classes.Ord g) => GHC.Classes.Ord (Multiarg.Mode.Internal.ModeResult g r)
instance (GHC.Classes.Eq r, GHC.Classes.Eq g) => GHC.Classes.Eq (Multiarg.Mode.Internal.ModeResult g r)
instance (GHC.Show.Show r, GHC.Show.Show g) => GHC.Show.Show (Multiarg.Mode.Internal.GlobalLocal g r)
instance (GHC.Classes.Ord r, GHC.Classes.Ord g) => GHC.Classes.Ord (Multiarg.Mode.Internal.GlobalLocal g r)
instance (GHC.Classes.Eq r, GHC.Classes.Eq g) => GHC.Classes.Eq (Multiarg.Mode.Internal.GlobalLocal g r)
instance GHC.Show.Show a => GHC.Show.Show (Multiarg.Mode.Internal.GlobalLocalEnd a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Multiarg.Mode.Internal.GlobalLocalEnd a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Multiarg.Mode.Internal.GlobalLocalEnd a)
instance GHC.Show.Show a => GHC.Show.Show (Multiarg.Mode.Internal.ParsedMode a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Multiarg.Mode.Internal.ParsedMode a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Multiarg.Mode.Internal.ParsedMode a)
instance GHC.Show.Show Multiarg.Mode.Internal.ModeName
instance GHC.Classes.Ord Multiarg.Mode.Internal.ModeName
instance GHC.Classes.Eq Multiarg.Mode.Internal.ModeName
instance GHC.Base.Functor Multiarg.Mode.Internal.Mode
instance GHC.Base.Functor Multiarg.Mode.Internal.ParsedMode


-- | Helps you build command-line parsers for programs that have more than
--   one so-called <i>mode</i>; examples of such programs include
--   <tt>git</tt>, <tt>darcs</tt>, and <tt>ghc-pkg</tt>.
module Multiarg.Mode

-- | Specifies how many <i>option arguments</i> an <i>option</i> takes.
data ArgSpec a

-- | This <i>option</i> takes no <i>option arguments</i>
ZeroArg :: a -> ArgSpec a

-- | This <i>option</i> takes one <i>option argument</i>
OneArg :: (String -> a) -> ArgSpec a

-- | This <i>option</i> takes two <i>option arguments</i>
TwoArg :: (String -> String -> a) -> ArgSpec a

-- | This <i>option</i> takes three <i>option arguments</i>
ThreeArg :: (String -> String -> String -> a) -> ArgSpec a

-- | Specifies an <i>option</i>. Typically you will use <a>optSpec</a> to
--   create an <a>OptSpec</a> rather than using the constructor directly.
--   Each <a>OptSpec</a> may contain mulitple <i>short option names</i> and
--   <i>long option names</i>; but each <a>OptSpec</a> contains only one
--   <a>ArgSpec</a>. Therefore, all <i>short option names</i> and <i>long
--   option names</i> specified in a single <a>OptSpec</a> are synonymous.
data OptSpec a

-- | Creates an <a>OptSpec</a>.
optSpec :: [Char] -> [String] -> ArgSpec a -> OptSpec a

-- | A <a>Mode</a> represents a single command line mode, such as
--   <tt>check</tt> for <tt>ghc-pkg check</tt>. It contains the name of the
--   mode, as well as a parser that handles all <i>options</i> and
--   <i>positional arguments</i> for the mode. Ordinarily you will create a
--   <a>Mode</a> using the <a>mode</a> function rather than by using the
--   constructor directly.
data Mode r

-- | Creates a new <a>Mode</a>.
mode :: String -> [OptSpec a] -> (String -> a) -> ([a] -> r) -> Mode r

-- | The result of parsing a mode command line.
data ModeResult g r

-- | <tt>ModeResult a b</tt> is a successfully parsed mode command line,
--   where:
--   
--   <tt>a</tt> is a list of all global options parsed; and
--   
--   <tt>b</tt> indicates the result of parsing the mode. It is <tt>Either
--   c d</tt>, where <tt>Left c</tt> indicates that no mode was parsed.
--   This arises under two circumstances. If the user did not include any
--   <i>words</i> after the global <i>options</i>, then <tt>c</tt> will be
--   the empty list, <tt>[]</tt>. If the user did include <i>words</i>
--   after the global options, but the first <i>word</i> was not recognized
--   as a mode, then this list will contain the first <i>word</i> and any
--   subsequent <i>words</i>. 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 <tt>b</tt> is <tt>Right d</tt>, this indicates that the user
--   entered a recognized mode, and the result is <tt>d</tt>.
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
--   <a>Multiarg.Mode</a>. 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: <tt>int</tt>, <tt>string</tt>, and
--   <tt>maybe</tt>. Each of these modes has three options: <tt>-z</tt> or
--   <tt>--zero</tt>, which takes no arguments; <tt>-s</tt> or
--   <tt>--single</tt>, which takes one argument; <tt>-d</tt> or
--   <tt>--double</tt>, which takes two arguments; and <tt>-t</tt> or
--   <tt>--triple</tt>, which takes three arguments. The type of the
--   argument depends on the mode. For <tt>int</tt>, the argument or
--   arguments must be an integer; for <tt>string</tt> the arguments can be
--   any string; and for <tt>maybe</tt> the arguments must be a Maybe Int,
--   such as <tt>Nothing</tt> or <tt>Just 5</tt>.
--   
--   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
--   <tt>Either</tt> 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 <a>OptSpec</a> is parameterized on
--   an <a>Either</a> to allow for error handling. If the user enters a
--   non-integer argument for the <tt>--verbose</tt> option, a
--   <tt>Left</tt> with an error message is returned.
globalOptSpecs :: [OptSpec (Either String Global)]

-- | A list of <a>OptSpec</a> that works for any <a>Mode</a>.
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 GHC.Show.Show Multiarg.Examples.Grover.Result
instance GHC.Classes.Ord Multiarg.Examples.Grover.Result
instance GHC.Classes.Eq Multiarg.Examples.Grover.Result
instance GHC.Show.Show a => GHC.Show.Show (Multiarg.Examples.Grover.GroverOpt a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Multiarg.Examples.Grover.GroverOpt a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Multiarg.Examples.Grover.GroverOpt a)
instance GHC.Show.Show Multiarg.Examples.Grover.Global
instance GHC.Classes.Ord Multiarg.Examples.Grover.Global
instance GHC.Classes.Eq Multiarg.Examples.Grover.Global
instance GHC.Base.Functor Multiarg.Examples.Grover.GroverOpt


-- | Parse command lines with <i>options</i> that might take multiple
--   <i>option arguments</i>.
--   
--   I built this library could not find anything that would readily parse
--   command lines where the <i>options</i> took more than one <i>option
--   argument</i>. For example, for the <tt>tail</tt> command on GNU
--   systems, the <tt>--lines</tt> <i>option</i> takes one <i>option
--   argument</i> to specify how many lines you want to see. Well, what if
--   you want to build a program with an option that takes two <i>option
--   arguments</i>, like <tt>--foo bar baz</tt>? I found no such library so
--   I built this one.
--   
--   Please consult the <a>Multiarg.Vocabulary</a> module to learn common
--   vocabulary used throughout Multiarg and its documentation. Words that
--   appear in <i>italics</i> are defined in <a>Multiarg.Vocabulary</a>.
--   
--   Use this module to build parsers for simple commands. The
--   <a>parseCommandLine</a> 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 <a>Multiarg.Internal</a>
--   module.
--   
--   To write parsers for commands with multiple modes (for instance,
--   <tt>ghc-pkg</tt> has multiple modes, such as <tt>ghc-pkg list</tt> and
--   <tt>ghc-pkg check</tt>) use the <a>Multiarg.Mode</a> module.
--   
--   You will find examples in <a>Multiarg.Examples.Telly</a> for non-mode
--   parsers, and in <a>Multiarg.Examples.Grover</a> for mode parsers.
module Multiarg

-- | Specifies how many <i>option arguments</i> an <i>option</i> takes.
data ArgSpec a

-- | This <i>option</i> takes no <i>option arguments</i>
ZeroArg :: a -> ArgSpec a

-- | This <i>option</i> takes one <i>option argument</i>
OneArg :: (String -> a) -> ArgSpec a

-- | This <i>option</i> takes two <i>option arguments</i>
TwoArg :: (String -> String -> a) -> ArgSpec a

-- | This <i>option</i> takes three <i>option arguments</i>
ThreeArg :: (String -> String -> String -> a) -> ArgSpec a

-- | Specifies an <i>option</i>. Typically you will use <a>optSpec</a> to
--   create an <a>OptSpec</a> rather than using the constructor directly.
--   Each <a>OptSpec</a> may contain mulitple <i>short option names</i> and
--   <i>long option names</i>; but each <a>OptSpec</a> contains only one
--   <a>ArgSpec</a>. Therefore, all <i>short option names</i> and <i>long
--   option names</i> specified in a single <a>OptSpec</a> are synonymous.
data OptSpec a

-- | Creates an <a>OptSpec</a>.
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:
--   
--   <ul>
--   <li>fetches the <i>words</i> on command line using <a>getArgs</a> and
--   the name of the program with <a>getProgName</a></li>
--   <li>prints help, if the user requested help, and exits
--   successfully</li>
--   <li>prints an error message and exits unsuccessfully, if the user
--   entered a bad command line (such as an unknown option)</li>
--   </ul>
--   
--   If you don't want this degree of automation or if you want a pure
--   function, see the <a>parseCommandLinePure</a> function in the
--   <a>Multiarg.Internal</a> 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 <a>Multiarg</a>. 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

-- | <tt>--empty</tt>, <tt>-e</tt>
Empty :: Telly

-- | <tt>--single</tt>, <tt>-s</tt>
Single :: String -> Telly

-- | <tt>--double</tt>, <tt>-d</tt>
Double :: String -> String -> Telly

-- | <tt>--triple</tt>, <tt>-t</tt>
Triple :: String -> String -> String -> Telly

-- | <pre>
--   -0
--   </pre>
Zero :: Telly

-- | <pre>
--   -1
--   </pre>
One :: String -> Telly

-- | <pre>
--   -2
--   </pre>
Two :: String -> String -> Telly

-- | <pre>
--   -3
--   </pre>
Three :: String -> String -> String -> Telly

-- | <pre>
--   --cero
--   </pre>
Cero :: Telly

-- | <pre>
--   --uno
--   </pre>
Uno :: String -> Telly

-- | <pre>
--   --dos
--   </pre>
Dos :: String -> String -> Telly

-- | <pre>
--   --tres
--   </pre>
Tres :: String -> String -> String -> Telly
optSpecs :: [OptSpec Telly]
help :: String -> String
parse :: IO [Telly]
instance GHC.Show.Show Multiarg.Examples.Telly.Telly
instance GHC.Classes.Ord Multiarg.Examples.Telly.Telly
instance GHC.Classes.Eq Multiarg.Examples.Telly.Telly


-- | Vocabulary used throughout Multiarg.
--   
--   Each time one of these words is used in the documentation, it is
--   <i>italicized</i> (or, if you are viewing the source code directly
--   rather than through Haddock, it is <i>surrounded by slashes</i>).
--   
--   <ul>
--   <li><i><i>word</i></i> When you run your program from the Unix shell
--   prompt, your shell is responsible for splitting the command line into
--   <i>words</i>. Typically you separate <i>words</i> with spaces,
--   although quoting can affect this. multiarg parses lists of
--   <i>words</i>. Each <i>word</i> can consist of a single <i>long
--   option</i>, a single <i>long option</i> and an accompanying <i>option
--   argument</i>, a single <i>short option</i>, multiple <i>short
--   options</i>, and even one or more <i>short options</i> with the last
--   <i>short option</i> being accompanied by an <i>option argument</i>.
--   Or, a word can be a <i>positional argument</i> or a <i>stopper</i>.
--   All these are described below.</li>
--   <li><i><i>option</i></i> <i>Options</i> allow a user to specify ways
--   to tune the operation of a program. Typically <i>options</i> are
--   indeed optional, although some programs do sport "required options" (a
--   bit of an oxymoron). <i>Options</i> can be either <i>short options</i>
--   or <i>long options</i>. Also, <i>options</i> can take <i>option
--   arguments</i>. The option is specified on the command line with both
--   the <i>flag</i> that specifies the option and of any <i>option
--   arguments</i> that are included with the <i>option</i>. Therefore the
--   <i>option</i> might be specified on the command line using one
--   <i>word</i> or multiple <i>words</i>, and in the case of short
--   <i>options</i>, multiple <i>options</i> might be in one
--   <i>word</i>.</li>
--   <li><i><i>short option</i></i> An <i>option</i> that is specified on
--   the command line using a <i>flag</i> whose <i>word</i> begins with a
--   hyphen, and with a single letter. For example, for the program
--   <tt>tail(1)</tt>, possible short options include <tt>n</tt> and
--   <tt>v</tt>. Multiarg will parse <i>words</i> that contain mulitple
--   <i>short options</i>. For example, if a user wants to run
--   <tt>tail</tt> with two options, he might type <tt>tail -v -f</tt> or
--   he might type <tt>tail -vf</tt>.</li>
--   <li><i><i>flag</i></i> A <i>flag</i> uniquely specifies an
--   <i>option</i>. To specify an <i>option</i> on the command line, the
--   user must present both a <i>flag</i> and any <i>option arguments</i>.
--   In the case of a <i>long option</i>, the <i>flag</i> consists of one
--   or more characters (typically a mnemonic word), preceded by two
--   hyphens. In the case of a <i>short option</i>, the <i>flag</i>
--   consists of a single character, in a <i>word</i> that begins with a
--   single hyphen; the <i>word</i> might contain more than one <i>flag</i>
--   for multiple <i>short options</i>.</li>
--   <li><i><i>short option name</i></i> A short option is specified on the
--   command line using a <i>flag</i> and any <i>option arguments</i>. The
--   <i>flag</i> contains the <i>short option name</i>, which is a single
--   character. A <i>short option name</i> is never a single hyphen.</li>
--   <li><i><i>long option name</i></i> A long option is specified on the
--   command line using a <i>flag</i> and any <i>option arguments</i>. The
--   <i>flag</i> begins with two hyphens, followed by the <i>long option
--   name</i>, which must be at least one letter but typically is a
--   mnemonic word.</li>
--   <li><i><i>name</i></i> Either a <i>short option name</i> or <i>long
--   option name</i>, as appropriate.</li>
--   <li><i><i>long option</i></i> An option that is specified using two
--   hyphens and what is usually a mnemonic word, though it could be as
--   short as a single letter. For example, <tt>tail(1)</tt> has long
--   options including <tt>follow</tt> and <tt>verbose</tt>. The user would
--   specify these on the command line by typing <tt>tail --follow
--   --verbose</tt>. A long option is specified on the command line with a
--   <i>flag</i> and any <i>option arguments</i>.</li>
--   <li><i><i>option argument</i></i> An <i>option</i> may take anywhere
--   from zero to three <i>option arguments</i>. When using a <i>short
--   option</i>, the first <i>option argument</i> and the <i>flag</i> may
--   be contained in the same <i>word</i> by appending the <i>option
--   argument</i> immediately after the <i>flag</i> without an intervening
--   space. When using a <i>long option</i>, the first <i>option
--   argument</i> and the <i>flag</i> may be contained in the same word by
--   separating the <i>flag</i> and the /option argument with an equal
--   sign. In any case in which an <i>option argument</i> and a <i>flag</i>
--   are in the same <i>word</i>, the <i>option argument</i> must be the
--   last thing to appear in the <i>word</i>. When using either <i>short
--   options</i> or <i>long options</i>, the first <i>option argument</i>
--   may appear in the same <i>word</i> as the <i>flag</i> or in the
--   <i>word</i> following the <i>flag</i>; the second and third <i>option
--   arguments</i> (if applicable) must each appear in its own
--   <i>word</i>.</li>
--   <li><i><i>positional argument</i></i> A <i>word</i> on the command
--   line that does not contain a <i>flag</i>, is not a <i>stopper</i>, and
--   is not an <i>option argument</i>. For instance, with <tt>tail(1)</tt>,
--   you specify the files you want to see by using <i>positional
--   arguments</i>. In the command <tt>tail -n 10 myfile</tt>,
--   <tt>myfile</tt> is a <i>positional argument</i>.</li>
--   <li><i><i>stopper</i></i> A <i>word</i> consisting solely of two
--   hyphens, <tt>--</tt>. The user types this to indicate that all
--   subsequent words on the command line are <i>positional arguments</i>,
--   even if they begin with hyphens and therefore look like they might be
--   <i>options</i>.</li>
--   </ul>
module Multiarg.Vocabulary
