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


-- | Command-line argument parsing library for Haskell programs
--   
--   Parse command-line arguments
@package parseargs
@version 0.1.3.1


-- | This module supplies an argument parser. Given a description of type
--   [<a>Arg</a>] of the legal arguments to the program, a list of argument
--   strings, and a bit of extra information, the <a>parseArgs</a> function
--   in this module returns an <a>Args</a> data structure suitable for
--   querying using the provided functions <a>gotArg</a>, <a>getArg</a>,
--   etc.
module System.Console.ParseArgs

-- | The description of an argument, suitable for messages and for parsing.
--   The <a>argData</a> field is used both for flags with a data argument,
--   and for positional data arguments.
--   
--   There are two cases:
--   
--   <ol>
--   <li>The argument is a flag, in which case at least one of
--   <a>argAbbr</a> and <a>argName</a> is provided;</li>
--   <li>The argument is positional, in which case neither <a>argAbbr</a>
--   nor <a>argName</a> are provided, but <a>argData</a> is.</li>
--   </ol>
--   
--   If none of <a>argAbbr</a>, <a>argName</a>, or <a>argData</a> are
--   provided, this is an error. See also the <a>argDataRequired</a>,
--   <a>argDataOptional</a>, and <a>argDataDefaulted</a> functions below,
--   which are used to generate <a>argData</a>.
data Ord a => Arg a
Arg :: a -> Maybe Char -> Maybe String -> Maybe DataArg -> String -> Arg a

-- | Connects the input description to the output argument.
argIndex :: Arg a -> a

-- | One-character flag name.
argAbbr :: Arg a -> Maybe Char

-- | "Long name" of flag.
argName :: Arg a -> Maybe String

-- | Datum description.
argData :: Arg a -> Maybe DataArg

-- | Documentation for the argument.
argDesc :: Arg a -> String

-- | The types of an argument carrying data. The constructor argument is
--   used to carry a default value.
--   
--   The constructor argument should really be hidden. Values of this type
--   are normally constructed within the pseudo-constructors
--   pseudo-constructors <a>argDataRequired</a>, <a>argDataOptional</a>,
--   and <a>argDataDefaulted</a>, to which only the constructor function
--   itself is passed.
data Argtype
ArgtypeString :: (Maybe String) -> Argtype
ArgtypeInteger :: (Maybe Integer) -> Argtype
ArgtypeInt :: (Maybe Int) -> Argtype
ArgtypeDouble :: (Maybe Double) -> Argtype
ArgtypeFloat :: (Maybe Float) -> Argtype

-- | How "sloppy" the parse is.
data ArgsComplete

-- | Any extraneous arguments (unparseable from description) will cause the
--   parser to fail.
ArgsComplete :: ArgsComplete

-- | Trailing extraneous arguments are permitted, and will be skipped,
--   saved, and returned. The constructor argument is the name of the args.
ArgsTrailing :: String -> ArgsComplete

-- | All extraneous arguments are permitted, and will be skipped, saved,
--   and returned.
ArgsInterspersed :: ArgsComplete

-- | Information specific to an argument carrying a datum. This is an
--   opaque type, whose instances are constructed using the
--   pseudo-constructors <a>argDataRequired</a>, <a>argDataOptional</a>,
--   and <a>argDataDefaulted</a>.
data DataArg

-- | Generate the <a>argData</a> for the given non-optional argument.
argDataRequired :: String -> (Maybe a -> Argtype) -> Maybe DataArg

-- | Generate the <a>argData</a> for the given optional argument with no
--   default.
argDataOptional :: String -> (Maybe a -> Argtype) -> Maybe DataArg

-- | Generate the <a>argData</a> for the given optional argument with the
--   given default.
argDataDefaulted :: String -> (Maybe a -> Argtype) -> a -> Maybe DataArg

-- | The type of the mapping from argument index to value.
data ArgRecord a

-- | The data structure <a>parseArgs</a> produces. The key element is the
--   <a>ArgRecord</a> <a>args</a>.
data Ord a => Args a
Args :: ArgRecord a -> String -> String -> [String] -> Args a

-- | The argument map.
args :: Args a -> ArgRecord a

-- | Basename of 0th argument.
argsProgName :: Args a -> String

-- | Full usage string.
argsUsage :: Args a -> String

-- | Remaining unprocessed arguments.
argsRest :: Args a -> [String]

-- | Given a description of the arguments, <a>parseArgs</a> produces a map
--   from the arguments to their "values" and some other useful byproducts.
--   <a>parseArgs</a> requires that the argument descriptions occur in the
--   order 1) flag arguments, 2) required positional arguments, 3) optional
--   positional arguments; otherwise a runtime error will be thrown.
parseArgs :: (Show a, Ord a) => ArgsComplete -> [Arg a] -> String -> [String] -> Args a

-- | Most of the time, you just want the environment's arguments and are
--   willing to live in the IO monad. This version of <a>parseArgs</a> digs
--   the pathname and arguments out of the system directly.
parseArgsIO :: (Show a, Ord a) => ArgsComplete -> [Arg a] -> IO (Args a)

-- | Check whether a given optional argument was supplied. Works on all
--   types.
gotArg :: Ord a => Args a -> a -> Bool

-- | Type of values that can be parsed by the argument parser.
class ArgType b
getArg :: (ArgType b, Show a, Ord a) => Args a -> a -> Maybe b
getRequiredArg :: (ArgType b, Show a, Ord a) => Args a -> a -> b

-- | <ul>
--   <li><i>Deprecated</i> Return the <a>String</a> value, if any, of the
--   given argument.</li>
--   </ul>
getArgString :: (Show a, Ord a) => Args a -> a -> Maybe String

-- | <ul>
--   <li><i>Deprecated</i> Treat the <a>String</a> value, if any, of the
--   given argument as a file handle and try to open it as requested.</li>
--   </ul>
getArgFile :: (Show a, Ord a) => Args a -> a -> IOMode -> IO (Maybe Handle)

-- | Treat the <a>String</a> value, if any, of the given argument as a file
--   handle and try to open it as requested. If not present, substitute the
--   appropriate one of stdin or stdout as indicated by <a>IOMode</a>.
getArgStdio :: (Show a, Ord a) => Args a -> a -> IOMode -> IO Handle

-- | <ul>
--   <li><i>Deprecated</i> Return the <a>Integer</a> value, if any, of the
--   given argument.</li>
--   </ul>
getArgInteger :: (Show a, Ord a) => Args a -> a -> Maybe Integer

-- | <ul>
--   <li><i>Deprecated</i> Return the <a>Int</a> value, if any, of the
--   given argument.</li>
--   </ul>
getArgInt :: (Show a, Ord a) => Args a -> a -> Maybe Int

-- | <ul>
--   <li><i>Deprecated</i> Return the <a>Double</a> value, if any, of the
--   given argument.</li>
--   </ul>
getArgDouble :: (Show a, Ord a) => Args a -> a -> Maybe Double

-- | <ul>
--   <li><i>Deprecated</i> Return the <a>Float</a> value, if any, of the
--   given argument.</li>
--   </ul>
getArgFloat :: (Show a, Ord a) => Args a -> a -> Maybe Float

-- | <a>ArgType</a> instance for opening a file from its string name.
newtype ArgFileOpener
ArgFileOpener :: (IOMode -> IO Handle) -> ArgFileOpener

-- | Function to open the file
argFileOpener :: ArgFileOpener -> IOMode -> IO Handle

-- | This exception is raised with an appropriate error message when
--   argument parsing fails. The first argument is the usage message, the
--   second the actual error message from the parser.
data ParseArgsException
ParseArgsException :: String -> String -> ParseArgsException

-- | Return the filename part of a pathname. Unnecessarily efficient
--   implementation does a single tail-call traversal with no construction.
baseName :: String -> String

-- | Generate a usage error with the given supplementary message string.
parseError :: String -> String -> a

-- | Generate a usage error with the given supplementary message string.
usageError :: Ord a => Args a -> String -> b

-- | See <tt>System.IO.openFile</tt>
data IOMode :: *
ReadMode :: IOMode
WriteMode :: IOMode
AppendMode :: IOMode
instance Eq ParseArgsException
instance ArgType ArgFileOpener
instance ArgType Float
instance ArgType Double
instance ArgType Int
instance ArgType Integer
instance ArgType [Char]
instance Show ParseArgsException
instance Exception ParseArgsException
instance Typeable ParseArgsException