envzn
0.8 · beta · not released

Library / System / Runtime / CommandLineArguments

CLASS

CommandLineArguments

Declare, parse and read a program's command-line arguments.

Constructors 1

INIT(REFERENCE String[] argv)

argv exactly as the program received it: argv[0] is the program itself (used in usage()), the rest are the words to parse.

Methods 24

MODIFY METHOD addFlag(REFERENCE String name, REFERENCE String shortName, REFERENCE String help) RETURNS void
modifies

A switch that is either present or absent: --verbose / -v. shortName is one letter, or "" for none.

MODIFY METHOD addTextOption(REFERENCE String name, REFERENCE String shortName, REFERENCE String defaultValue, REFERENCE String help) RETURNS void
modifies

An option carrying text: --output out.csv.

MODIFY METHOD addIntegerOption(REFERENCE String name, REFERENCE String shortName, int64 defaultValue, REFERENCE String help) RETURNS void
modifies

An option carrying a whole number: --jobs 8.

MODIFY METHOD addFloatOption(REFERENCE String name, REFERENCE String shortName, float64 defaultValue, REFERENCE String help) RETURNS void
modifies

An option carrying a floating-point number: --rate 0.25.

MODIFY METHOD require(REFERENCE String name) RETURNS void
modifies

Make a declared option mandatory: parse() fails if it is absent. With commands, the option of the scope being declared.

MODIFY METHOD addPositional(REFERENCE String name, REFERENCE String help) RETURNS void
modifies

A required word that is not an option, filled in declaration order.

MODIFY METHOD addOptionalPositional(REFERENCE String name, REFERENCE String help) RETURNS void
modifies

A word that may be absent, filled after every required positional. positional(name) returns "" when it was not given.

MODIFY METHOD addRemainingPositionals(REFERENCE String name, REFERENCE String help) RETURNS void
modifies

Zero or more trailing words, collected by remaining(). At most one declaration per scope, and only after every other positional of it.

MODIFY METHOD addCommand(REFERENCE String name, REFERENCE String help) RETURNS void
modifies

A command word: epm build. The first bare word on the command line chooses one; every word after it is read against that command.

MODIFY METHOD forCommand(REFERENCE String name) RETURNS void
modifies

Make the declarations that follow belong to the command name.

MODIFY METHOD forAllCommands() RETURNS void
modifies

Make the declarations that follow global again.

MODIFY METHOD collectAfterDoubleDash() RETURNS void
modifies

Keep every word after -- apart and untouched, for afterDoubleDash(), instead of reading them as positionals. A program that hands those words on to another program asks for this (program-entry design §3a); without it, -- keeps its standard meaning: everything after it is positional.

MODIFY METHOD parse() RETURNS | boolean
modifies

Read every word against the declarations. TRUE when every value is present and has the right kind; FAILURE's message ($!) names the first problem. After --help, parsing succeeds without enforcing required values.

METHOD command() RETURNS String
reads

The command word the command line chose; "" when the program has no commands, or none was given (only possible after --help).

METHOD afterDoubleDash() RETURNS String[]
reads

The words after --, untouched, when collectAfterDoubleDash was asked for.

METHOD spelledAsGiven(REFERENCE String[] names) RETURNS String[]
reads

The options among names that the user actually gave, as command-line words in the order given: each by its long name (-q is written --quiet), then its value unless it is a flag. An option left at its default is not spelled, so a program forwarding these never passes on a default as if it had been asked for.

METHOD helpRequested() RETURNS boolean
reads

TRUE if --help or -h was given.

METHOD isSet(REFERENCE String name) RETURNS boolean
reads

TRUE if the flag or option appeared on the command line.

METHOD textValue(REFERENCE String name) RETURNS String
reads

The option's text: what was given, or its default.

METHOD integerValue(REFERENCE String name) RETURNS int64
reads

An integer option's value: what was given, or its default.

METHOD floatValue(REFERENCE String name) RETURNS float64
reads

A float option's value: what was given, or its default.

METHOD positional(REFERENCE String name) RETURNS String
reads

A positional argument's word, by its declared name; "" for an optional one that was not given, or one of a command that was not chosen.

METHOD remaining() RETURNS String[]
reads

The words collected by addRemainingPositionals, in order; empty if none were given, or they belong to a command that was not chosen.

METHOD usage() RETURNS String
reads

The help text, generated from the declarations so it cannot drift from them. A program with commands gets the list of commands until one is chosen, then that command's own usage.