This module supplies an argument parser.
Given a description of type [Arg
] of the legal
arguments to the program, a list of argument strings,
and a bit of extra information, the parseArgs
function
in this module returns an
Args
data structure suitable for querying using the
provided functions gotArg
, getArgString
, etc.
- data Argtype
- = ArgtypeString (Maybe String)
- | ArgtypeInteger (Maybe Integer)
- | ArgtypeInt (Maybe Int)
- | ArgtypeDouble (Maybe Double)
- | ArgtypeFloat (Maybe Float)
- data DataArg
- data Ord a => Arg a = Arg {}
- data ArgsComplete
- argDataRequired :: String -> (Maybe a -> Argtype) -> Maybe DataArg
- argDataOptional :: String -> (Maybe a -> Argtype) -> Maybe DataArg
- argDataDefaulted :: String -> (Maybe a -> Argtype) -> a -> Maybe DataArg
- data ArgRecord a
- data Ord a => Args a = Args {}
- parseArgs :: (Show a, Ord a) => ArgsComplete -> [Arg a] -> String -> [String] -> Args a
- parseArgsIO :: (Show a, Ord a) => ArgsComplete -> [Arg a] -> IO (Args a)
- gotArg :: Ord a => Args a -> a -> Bool
- getArgString :: (Show a, Ord a) => Args a -> a -> Maybe String
- getArgFile :: (Show a, Ord a) => Args a -> a -> IOMode -> IO (Maybe Handle)
- getArgStdio :: (Show a, Ord a) => Args a -> a -> IOMode -> IO Handle
- getArgInteger :: (Show a, Ord a) => Args a -> a -> Maybe Integer
- getArgInt :: (Show a, Ord a) => Args a -> a -> Maybe Int
- getArgDouble :: (Show a, Ord a) => Args a -> a -> Maybe Double
- getArgFloat :: (Show a, Ord a) => Args a -> a -> Maybe Float
- baseName :: String -> String
- usageError :: Ord a => Args a -> String -> b
- data IOMode
- = ReadMode
- | WriteMode
- | AppendMode
Describing allowed arguments
The argument parser requires a description of
the arguments that will be parsed. This is
supplied as a list of Arg
records, built up
using the functions described here.
The types of arguments carrying data; the constructor arguments are for default values.
The description of an argument, suitable for
messages and for parsing. The argData
field
is used both for flags with a data argument, and
for positional data arguments.
There are two cases:
- The argument is a flag, in which case at least
one of
argAbbr
andargName
is provided; - The argument is positional, in which case neither
argAbbr
norargName
are provided, butargData
is.
If none of argAbbr
, argName
, or argData
are
provided, this is an error. See also the
argDataRequired
, argDataOptional
, and
argDataDefaulted
functions below, which are used to
generate argData
.
data ArgsComplete Source
How "sloppy" the parse is.
ArgsComplete | Any extraneous arguments (unparseable from description) will cause the parser to fail. |
ArgsTrailing | Trailing extraneous arguments are permitted, and will be skipped, saved, and returned. |
ArgsInterspersed | All extraneous arguments are permitted, and will be skipped, saved, and returned. |
:: String | Datum print name. |
-> (Maybe a -> Argtype) | Type constructor for datum. |
-> Maybe DataArg | Result is |
Generate the argData
for the given non-optional argument.
:: String | Datum print name. |
-> (Maybe a -> Argtype) | Type constructor for datum. |
-> Maybe DataArg | Result is |
Generate the argData
for the given optional argument with no default.
:: String | Datum print name. |
-> (Maybe a -> Argtype) | Type constructor for datum. |
-> a | Datum default value. |
-> Maybe DataArg | Result is |
Generate the argData
for the given optional argument with the
given default.
Argument processing
The argument descriptions are used to parse the command line arguments, and the results of the parse can later be (efficiently) queried to determine program behavior.
Getting parse results
The argument parser returns an opaque map from argument index to parsed argument data (plus some convenience information).
:: (Show a, Ord a) | |
=> ArgsComplete | Degree of completeness of parse. |
-> [Arg a] | Argument descriptions. |
-> String | Full program pathname. |
-> [String] | Incoming program argument list. |
-> Args a | Outgoing argument parse results. |
Given a description of the arguments, parseArgs
produces
a map from the arguments to their "values" and some other
useful byproducts.
:: (Show a, Ord a) | |
=> ArgsComplete | Degree of completeness of parse. |
-> [Arg a] | Argument descriptions. |
-> IO (Args a) | Argument parse results. |
Most of the time, you just want the environment's
arguments and are willing to live in the IO monad.
This version of parseArgs
digs the pathname and arguments
out of the system directly.
Using parse results
Query functions permit checking for the existence and values of command-line arguments.
:: Ord a | |
=> Args a | Parsed arguments. |
-> a | Index of argument to be checked for. |
-> Bool | True if the arg was present. |
Check whether a given optional argument was supplied. Works on all types.
:: (Show a, Ord a) | |
=> Args a | Parsed arguments. |
-> a | Index of argument to be retrieved. |
-> Maybe String | Argument value if present. |
Return the String, if any, of the given argument.
:: (Show a, Ord a) | |
=> Args a | Parsed arguments. |
-> a | Index of argument to be retrieved. |
-> IOMode | IO mode the file should be opened in. |
-> IO (Maybe Handle) | Handle of opened file, if the argument was present. |
Treat the String
, if any, of the given argument as
a file handle and try to open it as requested.
:: (Show a, Ord a) | |
=> Args a | Parsed arguments. |
-> a | Index of argument to be retrieved. |
-> Maybe Integer | Argument value if present. |
Return the Integer, if any, of the given argument.
:: (Show a, Ord a) | |
=> Args a | Parsed arguments. |
-> a | Index of argument to be retrieved. |
-> Maybe Int | Argument value if present. |
Return the Int, if any, of the given argument.
:: (Show a, Ord a) | |
=> Args a | Parsed arguments. |
-> a | Index of argument to be retrieved. |
-> Maybe Double | Argument value if present. |
Return the Double, if any, of the given argument.
:: (Show a, Ord a) | |
=> Args a | Parsed arguments. |
-> a | Index of argument to be retrieved. |
-> Maybe Float | Argument value if present. |
Return the Float, if any, of the given argument.
Misc
Return the filename part of a pathname. Unnecessarily efficient implementation does a single tail-call traversal with no construction.
usageError :: Ord a => Args a -> String -> bSource
Generate a usage error with the given supplementary message string.