System.Console.CmdTheLine.Arg

Creating ArgInfos

optInfo :: [String] -> ArgInfo

Initialize an ArgInfo by providing a list of names. The fields argName(found at System.Console.CmdTheLine), argDoc(found at System.Console.CmdTheLine), and argSection(found at System.Console.CmdTheLine) can then be manipulated post-mortem, as in

 inf =(optInfo    [ "i", "insufflation" ])
     { argName    = "INSUFFERABLE"
     , argDoc     = "in the haunted house's harrow"
     , argSection = "NOT FOR AUGHT"
     }

Names of one character in length will be prefixed by - on the command line, while longer names will be prefixed by --.

This function is meant to be used with optional arguments produced by flag, opt, and friends-- not with positional arguments. Positional arguments provided with names will yield a run-time error, halting any and all program runs. Use posInfo for positional arguments.

Likewise, if an optional argument is created with an ArgInfo produced by passing an empty list of names to optInfo, a run-time error will occur. All optional arguments must have names.

posInfo :: ArgInfo

As optInfo but for positional arguments, which by virtue of their positions require no names. If a positional argument is created with a name, a run-time error will occur halting any and all program runs.

If you mean to create an optional argument, use optInfo, and be sure to give it a non-empty list of names to avoid these errors.

Optional arguments

An optional argument is specified on the command line by a name possibly followed by a value.

The name of an option can be short or long.

• A short name is a dash followed by a single alphanumeric character: -h, -q, -I.
• A long name is two dashes followed by alphanumeric characters and dashes: --help, --silent, --ignore-case.

More than one name may refer to the same optional argument. For example in a given program the names -q, --quiet, and --silent may all stand for the same boolean argument indicating the program to be quiet. Long names can be specified by any non-ambiguous prefix.

There are three ways to assign values to an optional argument on the command line.

• As the next token on the command line: -o a.out, --output a.out.
• Glued to a short name: -oa.out.
• Glued to a long name after an equal character: --output=a.out.

Glued forms are necessary if the value itself starts with a dash, as is the case for negative numbers, --min=-10.

Flag options

flag :: ArgInfo -> Term Bool

Create a command line flag that can appear at most once on the command line. Yields False in absence and True in presence.

flagAll :: ArgInfo -> Term [Bool]

As flag but may appear an infinity of times. Yields a list of Trues as long as the number of times present.

vFlag :: a -> [(a, ArgInfo)] -> Term a

vFlag v [ ( v1, ai1 ), ... ] is an argument that can be present at most once on the command line. It takes on the value vn when appearing as ain.

vFlagAll :: [a] -> [(a, ArgInfo)] -> Term [a]

vFlagAll vs assoc is as vFlag except that it can be present an infinity of times. In absence, vs is yielded. When present, each value is collected in the order they appear.

Assignable options

opt :: ArgVal a => a -> ArgInfo -> Term a

opt v ai is an optional argument that yields v in absence, or an assigned value in presence. If the option is present, but no value is assigned, it is considered a user-error and usage is printed on exit.

defaultOpt :: ArgVal a => a -> a -> ArgInfo -> Term a

defaultOpt def v ai is as opt except if it is present and no value is assigned on the command line, def is the result.

optAll :: (ArgVal a, Ord a) => [a] -> ArgInfo -> Term [a]

optAll vs ai is like opt except that it yields vs in absence and can appear an infinity of times. The values it is assigned on the command line are accumulated in the order they appear.

defaultOptAll :: (ArgVal a, Ord a) => a -> [a] -> ArgInfo -> Term [a]

defaultOptAll def vs ai is like optAll except that if it is present without being assigned a value, the value def takes its place in the list of results.

Positional arguments

Positional arguments are tokens on the command line that are not option names or the values being assigned to an optional argument.

Since positional arguments may be mistaken as the optional value of an optional argument or they may need to look like an optional name, anything that follows the special token --(with spaces on both sides) on the command line is considered to be a positional argument.

Positional arguments are listed in documentation sections iff they are assigned both an argName and an argDoc.

pos :: ArgVal a => Int -> a -> ArgInfo -> Term a

pos n v ai is an argument defined by the nth positional argument on the command line. If absent the value v is returned.

revPos :: ArgVal a => Int -> a -> ArgInfo -> Term a

revPos n v ai is as pos but counting from the end of the command line to the front.

posAny :: ArgVal a => [a] -> ArgInfo -> Term [a]

posAny vs ai yields a list of all positional arguments or vs if none are present.

posLeft :: ArgVal a => Int -> [a] -> ArgInfo -> Term [a]

posLeft n vs ai yield a list of all positional arguments to the left of the nth positional argument or vs if there are none.

posRight :: ArgVal a => Int -> [a] -> ArgInfo -> Term [a]

posRight n vs ai is as posLeft except yielding all values to the right of the nth positional argument.

revPosLeft :: ArgVal a => Int -> [a] -> ArgInfo -> Term [a]

revPosLeft n vs ai is as posLeft except n counts from the end of the command line to the front.

revPosRight :: ArgVal a => Int -> [a] -> ArgInfo -> Term [a]

revPosRight n vs ai is as posRight except n counts from the end of the command line to the front.

Constraining Terms

required :: Term (Maybe a) -> Term a

required term converts term so that it fails in the Nothing and yields a in the Just.

This is used for required positional arguments. There is nothing stopping you from using it with optional arguments, except that they would no longer be optional and it would be confusing from a user's perspective.

nonEmpty :: Term [a] -> Term [a]

nonEmpty term is a term that fails if its result is empty. Intended for non-empty lists of positional arguments.

lastOf :: Term [a] -> Term a

lastOf term is a term that fails if its result is empty and evaluates to the last element of the resulting list otherwise. Intended for lists of flags or options where the last takes precedence.