System.Console.ParseArgs

parseargs-0.1: Command-line argument parsing library for Haskell programs

System.Console.ParseArgs

Contents

Describing allowed arguments

Argument processing

Getting parse results
Using parse results

Description

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.

Synopsis

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 {

argAbbr :: Maybe Char

argName :: Maybe String

argData :: Maybe DataArg

argDesc :: String

}

data ArgsComplete

| ArgsInterspersed

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 {

args :: ArgRecord a

argsProgName :: String

argsUsage :: String

argsRest :: [String]

}

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

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.

data Argtype

The types of arguments carrying data; the constructor arguments are for default values.

Constructors

ArgtypeString (Maybe String)
ArgtypeInteger (Maybe Integer)
ArgtypeInt (Maybe Int)
ArgtypeDouble (Maybe Double)
ArgtypeFloat (Maybe Float)

data DataArg

Information specific to an argument carrying a datum.

data Ord a => Arg a

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 and argName is provided;
The argument is positional, in which case neither argAbbr nor argName are provided, but argData 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.

Constructors

Arg

argIndex :: a	Connects the input description to the output argument.
argAbbr :: Maybe Char	One-character flag name.
argName :: Maybe String	"Long name" of flag.
argData :: Maybe DataArg	Datum description.
argDesc :: String	Documentation for the argument.

data ArgsComplete

How "sloppy" the parse is.

Constructors

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.

argDataRequired

::
=> String	Datum print name.
-> Maybe a -> Argtype	Type constructor for datum.
-> Maybe DataArg	Result is `argData`-ready.
Generate the `argData` for the given non-optional argument.

argDataOptional

::
=> String	Datum print name.
-> Maybe a -> Argtype	Type constructor for datum.
-> Maybe DataArg	Result is `argData`-ready.
Generate the `argData` for the given optional argument with no default.

argDataDefaulted

::
=> String	Datum print name.
-> Maybe a -> Argtype	Type constructor for datum.
-> a	Datum default value.
-> Maybe DataArg	Result is `argData`-ready.
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).

data ArgRecord a

The type of the mapping from argument index to value.

data Ord a => Args a

The data structure parseArgs produces. The key element is the ArgRecord args.

Constructors

Args

args :: ArgRecord a	The argument map.
argsProgName :: String	Basename of 0th argument.
argsUsage :: String	Full usage string.
argsRest :: [String]	Remaining unprocessed arguments.

parseArgs

:: (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.

parseArgsIO

:: (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.

gotArg

:: 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.

getArgString

:: (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.

getArgFile

:: (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.

getArgStdio

:: (Show a, Ord a)
=> Args a	Parsed arguments.
-> a	Index of argument to be retrieved.
-> IOMode	IO mode the file should be opened in. Must not be `ReadWriteMode`.
-> IO Handle	Appropriate file handle.
Treat the `String`, 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 `IOMode`.

getArgInteger

:: (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.

getArgInt

:: (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.

getArgDouble

:: (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.

getArgFloat

:: (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.

baseName

:: String	Pathname.
-> String	Rightmost component of pathname.
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 -> b

Generate a usage error with the given supplementary message string.

Produced by Haddock version 2.1.0