parseargs-0.2.0.9: Parse command-line arguments

Copyright(c) 2007 Bart Massey
LicenseBSD-style (see the file COPYING)
MaintainerBart Massey <bart.massey@gmail.com>
Stabilitystable
Portabilityportable
Safe HaskellSafe
LanguageHaskell98

System.Console.ParseArgs

Contents

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

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

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.

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.

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
Eq ArgsDash Source # 
Instance details

Defined in System.Console.ParseArgs

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.

data ArgsParseControl Source #

Record containing the collective parse control information.

Constructors

ArgsParseControl 

Fields

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

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
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 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 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 [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

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

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 #

Constructors

ReadMode 
WriteMode 
AppendMode 
Instances
Enum IOMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.IOMode

Eq IOMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.IOMode

Methods

(==) :: IOMode -> IOMode -> Bool #

(/=) :: IOMode -> IOMode -> Bool #

Ord IOMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.IOMode

Read IOMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.IOMode

Show IOMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.IOMode

Ix IOMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.IOMode