libghc-parseargs-doc 0.2.0.8-1 / usr / share / doc / libghc-parseargs-doc / html / parseargs.txt

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


-- | Full-featured command-line argument parsing library.
--   
--   Parse command-line arguments
@package parseargs
@version 0.2.0.8


-- | <tt>ParseArgs</tt> is a full-featured command-line argument parsing
--   library.
--   
--   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

-- | Whether to always treat an unknown argument beginning with "-" as an
--   error, or to allow it to be used as a positional argument when
--   possible.
data ArgsDash

-- | If an argument begins with a "-", it will always be treated as an
--   error unless it corresponds to a flag description.
ArgsHardDash :: ArgsDash

-- | If an argument beginning with a "-" is unrecognized as a flag, treat
--   it as a positional argument if possible. Otherwise it is an error.
ArgsSoftDash :: ArgsDash

-- | Class for building parse control information, for backward
--   compatibility.
class APCData a
getAPCData :: APCData a => a -> ArgsParseControl

-- | Record containing the collective parse control information.
data ArgsParseControl
ArgsParseControl :: ArgsComplete -> ArgsDash -> ArgsParseControl

-- | Level of completeness of parse.
[apcComplete] :: ArgsParseControl -> ArgsComplete

-- | Handling of dashes in parse.
[apcDash] :: ArgsParseControl -> ArgsDash

-- | 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 data structure <a>parseArgs</a> produces. There is a
--   should-be-hidden field that describes the parse.
data (Ord a) => Args a
Args :: ArgRecord a -> String -> String -> [String] -> Args a

-- | The argument parse, only listed here to work around a Haddock bug. See
--   <a>https://github.com/haskell/haddock/issues/456</a>.
[__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, then 2) positional arguments; otherwise a
--   runtime error will be thrown.
parseArgs :: (Show a, Ord a, APCData b) => b -> [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, APCData b) => b -> [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 where getRequiredArg ads index = case getArg ads index of { Just v -> v Nothing -> error ("internal error: required argument " ++ show index ++ "not supplied") }

-- | Fetch an argument's value if it is present.
getArg :: (ArgType b, Show a, Ord a) => Args a -> a -> Maybe b

-- | Fetch the value of a required argument.
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 <a>openFile</a>
data IOMode :: *
ReadMode :: IOMode
WriteMode :: IOMode
AppendMode :: IOMode
instance GHC.Classes.Eq System.Console.ParseArgs.ArgsDash
instance GHC.Classes.Eq System.Console.ParseArgs.ParseArgsException
instance GHC.Exception.Exception System.Console.ParseArgs.ParseArgsException
instance GHC.Show.Show System.Console.ParseArgs.ParseArgsException
instance System.Console.ParseArgs.APCData System.Console.ParseArgs.ArgsParseControl
instance System.Console.ParseArgs.APCData System.Console.ParseArgs.ArgsComplete
instance System.Console.ParseArgs.ArgType ()
instance System.Console.ParseArgs.ArgType [GHC.Types.Char]
instance System.Console.ParseArgs.ArgType GHC.Integer.Type.Integer
instance System.Console.ParseArgs.ArgType GHC.Types.Int
instance System.Console.ParseArgs.ArgType GHC.Types.Double
instance System.Console.ParseArgs.ArgType GHC.Types.Float
instance System.Console.ParseArgs.ArgType System.Console.ParseArgs.ArgFileOpener