parseargs-0.2.0.9: Parse command-line arguments

Copyright | (c) 2007 Bart Massey
License | BSD-style (see the file COPYING)
Maintainer | Bart Massey <bart.massey@gmail.com>
Stability | stable
Portability | portable
Safe Haskell | Safe
Language | Haskell98

System.Console.ParseArgs

Contents

- Describing allowed arguments
  - DataArg and its pseudo-constructors
- Argument processing
  - Getting parse results
  - Using parse results
- Misc

Description

`ParseArgs` is a full-featured command-line argument parsing library.

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`, `getArg`, etc.

Synopsis

- data Ord a => Arg a = Arg {
  - argIndex :: a
  - argAbbr :: Maybe Char
  - argName :: Maybe String
  - argData :: Maybe DataArg
  - argDesc :: String
  }
- data Argtype
  - = ArgtypeString (Maybe String)
  - | ArgtypeInteger (Maybe Integer)
  - | ArgtypeInt (Maybe Int)
  - | ArgtypeDouble (Maybe Double)
  - | ArgtypeFloat (Maybe Float)
- data ArgsComplete
  - = ArgsComplete
  - | ArgsTrailing String
  - | ArgsInterspersed
- data ArgsDash
  - = ArgsHardDash
  - | ArgsSoftDash
- class APCData a where
  - getAPCData :: a -> ArgsParseControl
- data ArgsParseControl = ArgsParseControl {
  - apcComplete :: ArgsComplete
  - apcDash :: ArgsDash
  }
- data DataArg
- argDataRequired :: String -> (Maybe a -> Argtype) -> Maybe DataArg
- argDataOptional :: String -> (Maybe a -> Argtype) -> Maybe DataArg
- argDataDefaulted :: String -> (Maybe a -> Argtype) -> a -> Maybe DataArg
- data Ord a => Args a = Args {
  - __args :: ArgRecord a
  - argsProgName :: String
  - argsUsage :: String
  - argsRest :: [String]
  }
- parseArgs :: (Show a, Ord a, APCData b) => b -> [Arg a] -> String -> [String] -> Args a
- parseArgsIO :: (Show a, Ord a, APCData b) => b -> [Arg a] -> IO (Args a)
- gotArg :: Ord a => Args a -> a -> Bool
- class ArgType b where
  - getArg :: (Show a, Ord a) => Args a -> a -> Maybe b
  - getRequiredArg :: (Show a, Ord a) => Args a -> a -> b
- 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
- newtype ArgFileOpener = ArgFileOpener {
  - argFileOpener :: IOMode -> IO Handle
  }
- data ParseArgsException = ParseArgsException String String
- baseName :: String -> String
- parseError :: String -> String -> a
- 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.

data Ord a => Arg a Source #

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:

1. The argument is a flag, in which case at least one of `argAbbr` and `argName` is provided;
2. 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 |

Fields

- 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 Argtype Source #

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 `argDataRequired`, `argDataOptional`, and `argDataDefaulted`, to which only the constructor function itself is passed.

Constructors

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

data ArgsComplete Source #

How "sloppy" the parse is.

Constructors

ArgsComplete | Any extraneous arguments (unparseable from description) will cause the parser to fail.
ArgsTrailing String | Trailing extraneous arguments are permitted, and will be skipped, saved, and returned. The constructor argument is the name of the args.
ArgsInterspersed | All extraneous arguments are permitted, and will be skipped, saved, and returned.

#### Instances

Instances details

APCData ArgsComplete Source # |
Instance details Defined in System.Console.ParseArgs Methods getAPCData :: ArgsComplete -> ArgsParseControl Source #

data ArgsDash Source #

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.

Constructors

ArgsHardDash | If an argument begins with a "-", it will always be treated as an error unless it corresponds to a flag description.
ArgsSoftDash | If an argument beginning with a "-" is unrecognized as a flag, treat it as a positional argument if possible. Otherwise it is an error.

#### Instances

Instances details

Eq ArgsDash Source # |
Instance details Defined in System.Console.ParseArgs Methods (==) :: ArgsDash -> ArgsDash -> Bool Source # (/=) :: ArgsDash -> ArgsDash -> Bool Source #

class APCData a where Source #

Class for building parse control information, for backward compatibility.

Methods

getAPCData Source #

Arguments

:: a |
-> ArgsParseControl | Build an `ArgsParseControl` structure from the given info.

#### Instances

Instances details

APCData ArgsComplete Source # |
Instance details Defined in System.Console.ParseArgs Methods getAPCData :: ArgsComplete -> ArgsParseControl Source #
APCData ArgsParseControl Source # |
Instance details Defined in System.Console.ParseArgs Methods getAPCData :: ArgsParseControl -> ArgsParseControl Source #

data ArgsParseControl Source #

Record containing the collective parse control information.

Constructors

ArgsParseControl |

Fields

- apcComplete :: ArgsComplete

  Level of completeness of parse.

- apcDash :: ArgsDash

  Handling of dashes in parse.

#### Instances

Instances details

APCData ArgsParseControl Source # |
Instance details Defined in System.Console.ParseArgs Methods getAPCData :: ArgsParseControl -> ArgsParseControl Source #

## DataArg and its pseudo-constructors

data DataArg Source #

Information specific to an argument carrying a datum. This is an opaque type, whose instances are constructed using the pseudo-constructors `argDataRequired`, `argDataOptional`, and `argDataDefaulted`.

argDataRequired Source #

Arguments

:: 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 Source #

Arguments

:: 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 Source #

Arguments

:: 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 Ord a => Args a Source #

The data structure `parseArgs` produces. There is a should-be-hidden field that describes the parse.

Constructors

Args |

Fields

- __args :: ArgRecord a

  The argument parse, only listed here to work around a Haddock bug. See https://github.com/haskell/haddock/issues/456.

- argsProgName :: String

  Basename of 0th argument.

- argsUsage :: String

  Full usage string.

- argsRest :: [String]

  Remaining unprocessed arguments.

parseArgs Source #

Arguments

:: (Show a, Ord a, APCData b) |
=> b | Configuration for 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. `parseArgs` requires that the argument descriptions occur in the order 1) flag arguments, then 2) positional arguments; otherwise a runtime error will be thrown.

parseArgsIO Source #

Arguments

:: (Show a, Ord a, APCData b) |
=> b | 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 Source #

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.

class ArgType b where Source #

Type of values that can be parsed by the argument parser.

Minimal complete definition

getArg

Methods

getArg Source #

Arguments

:: (Show a, Ord a) |
=> Args a | Parsed arguments.
-> a | Index of argument to be retrieved.
-> Maybe b | Argument value if present.

Fetch an argument's value if it is present.

getRequiredArg Source #

Arguments

:: (Show a, Ord a) |
=> Args a | Parsed arguments.
-> a | Index of argument to be retrieved.
-> b | Argument value.

Fetch the value of a required argument.

#### Instances

Instances details

ArgType ArgFileOpener Source # |
Instance details Defined in System.Console.ParseArgs Methods getArg :: (Show a, Ord a) => Args a -> a -> Maybe ArgFileOpener Source # getRequiredArg :: (Show a, Ord a) => Args a -> a -> ArgFileOpener Source #
ArgType Integer Source # |
Instance details Defined in System.Console.ParseArgs Methods getArg :: (Show a, Ord a) => Args a -> a -> Maybe Integer Source # getRequiredArg :: (Show a, Ord a) => Args a -> a -> Integer Source #
ArgType () Source # |
Instance details Defined in System.Console.ParseArgs Methods getArg :: (Show a, Ord a) => Args a -> a -> Maybe () Source # getRequiredArg :: (Show a, Ord a) => Args a -> a -> () Source #
ArgType Double Source # |
Instance details Defined in System.Console.ParseArgs Methods getArg :: (Show a, Ord a) => Args a -> a -> Maybe Double Source # getRequiredArg :: (Show a, Ord a) => Args a -> a -> Double Source #
ArgType Float Source # |
Instance details Defined in System.Console.ParseArgs Methods getArg :: (Show a, Ord a) => Args a -> a -> Maybe Float Source # getRequiredArg :: (Show a, Ord a) => Args a -> a -> Float Source #
ArgType Int Source # |
Instance details Defined in System.Console.ParseArgs Methods getArg :: (Show a, Ord a) => Args a -> a -> Maybe Int Source # getRequiredArg :: (Show a, Ord a) => Args a -> a -> Int Source #
ArgType [Char] Source # |
Instance details Defined in System.Console.ParseArgs Methods getArg :: (Show a, Ord a) => Args a -> a -> Maybe [Char] Source # getRequiredArg :: (Show a, Ord a) => Args a -> a -> [Char] Source #

getArgString Source #

Arguments

:: (Show a, Ord a) |
=> Args a | Parsed arguments.
-> a | Index of argument to be retrieved.
-> Maybe String | Argument value if present.

Deprecated
  Return the `String` value, if any, of the given argument.

getArgFile Source #

Arguments

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

Deprecated
  Treat the `String` value, if any, of the given argument as a file handle and try to open it as requested.

getArgStdio Source #

Arguments

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

getArgInteger Source #

Arguments

:: (Show a, Ord a) |
=> Args a | Parsed arguments.
-> a | Index of argument to be retrieved.
-> Maybe Integer | Argument value if present.

Deprecated
  Return the `Integer` value, if any, of the given argument.

getArgInt Source #

Arguments

:: (Show a, Ord a) |
=> Args a | Parsed arguments.
-> a | Index of argument to be retrieved.
-> Maybe Int | Argument value if present.

Deprecated
  Return the `Int` value, if any, of the given argument.

getArgDouble Source #

Arguments

:: (Show a, Ord a) |
=> Args a | Parsed arguments.
-> a | Index of argument to be retrieved.
-> Maybe Double | Argument value if present.

Deprecated
  Return the `Double` value, if any, of the given argument.

getArgFloat Source #

Arguments

:: (Show a, Ord a) |
=> Args a | Parsed arguments.
-> a | Index of argument to be retrieved.
-> Maybe Float | Argument value if present.

Deprecated
  Return the `Float` value, if any, of the given argument.

newtype ArgFileOpener Source #

`ArgType` instance for opening a file from its string name.

Constructors

ArgFileOpener |

Fields

- argFileOpener :: IOMode -> IO Handle

  Function to open the file

#### Instances

Instances details

ArgType ArgFileOpener Source # |
Instance details Defined in System.Console.ParseArgs Methods getArg :: (Show a, Ord a) => Args a -> a -> Maybe ArgFileOpener Source # getRequiredArg :: (Show a, Ord a) => Args a -> a -> ArgFileOpener Source #

# Misc

data ParseArgsException Source #

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.

Constructors

ParseArgsException String String |

#### Instances

Instances details

Exception ParseArgsException Source # |
Instance details Defined in System.Console.ParseArgs Methods toException :: ParseArgsException -> SomeException Source # fromException :: SomeException -> Maybe ParseArgsException Source # displayException :: ParseArgsException -> String Source # backtraceDesired :: ParseArgsException -> Bool Source #
Show ParseArgsException Source # |
Instance details Defined in System.Console.ParseArgs Methods showsPrec :: Int -> ParseArgsException -> ShowS Source # show :: ParseArgsException -> String Source # showList :: [ParseArgsException] -> ShowS Source #
Eq ParseArgsException Source # |
Instance details Defined in System.Console.ParseArgs Methods (==) :: ParseArgsException -> ParseArgsException -> Bool Source # (/=) :: ParseArgsException -> ParseArgsException -> Bool Source #

baseName Source #

Arguments

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

parseError Source #

Arguments

:: String | Usage message.
-> String | Specific error message.
-> a | Bogus polymorphic result.

Generate a usage error with the given supplementary message string.

usageError :: Ord a => Args a -> String -> b Source #

Generate a usage error with the given supplementary message string.

data IOMode Source #

See `openFile`

Constructors

ReadMode |
WriteMode |
AppendMode |

#### Instances

Instances details

Enum IOMode | Since: base-4.2.0.0

Instance details

Defined in GHC.Internal.IO.IOMode

Methods

succ :: IOMode -> IOMode Source #

pred :: IOMode -> IOMode Source #

toEnum :: Int -> IOMode Source #

fromEnum :: IOMode -> Int Source #

enumFrom :: IOMode -> [IOMode] Source #

enumFromThen :: IOMode -> IOMode -> [IOMode] Source #

enumFromTo :: IOMode -> IOMode -> [IOMode] Source #

enumFromThenTo :: IOMode -> IOMode -> IOMode -> [IOMode] Source #

Ix IOMode | Since: base-4.2.0.0
Instance details Defined in GHC.Internal.IO.IOMode Methods range :: (IOMode, IOMode) -> [IOMode] Source # index :: (IOMode, IOMode) -> IOMode -> Int Source # unsafeIndex :: (IOMode, IOMode) -> IOMode -> Int Source # inRange :: (IOMode, IOMode) -> IOMode -> Bool Source # rangeSize :: (IOMode, IOMode) -> Int Source # unsafeRangeSize :: (IOMode, IOMode) -> Int Source #
Read IOMode | Since: base-4.2.0.0
Instance details Defined in GHC.Internal.IO.IOMode Methods readsPrec :: Int -> ReadS IOMode Source # readList :: ReadS [IOMode] Source # readPrec :: ReadPrec IOMode Source # readListPrec :: ReadPrec [IOMode] Source #
Show IOMode | Since: base-4.2.0.0
Instance details Defined in GHC.Internal.IO.IOMode Methods showsPrec :: Int -> IOMode -> ShowS Source # show :: IOMode -> String Source # showList :: [IOMode] -> ShowS Source #
Eq IOMode | Since: base-4.2.0.0
Instance details Defined in GHC.Internal.IO.IOMode Methods (==) :: IOMode -> IOMode -> Bool Source # (/=) :: IOMode -> IOMode -> Bool Source #
Ord IOMode | Since: base-4.2.0.0
Instance details Defined in GHC.Internal.IO.IOMode Methods compare :: IOMode -> IOMode -> Ordering Source # (<) :: IOMode -> IOMode -> Bool Source # (<=) :: IOMode -> IOMode -> Bool Source # (>) :: IOMode -> IOMode -> Bool Source # (>=) :: IOMode -> IOMode -> Bool Source # max :: IOMode -> IOMode -> IOMode Source # min :: IOMode -> IOMode -> IOMode Source #