Library / System / Runtime / CommandLineArguments
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 voidmodifies
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 voidmodifies
An option carrying text: --output out.csv.
MODIFY METHOD addIntegerOption(REFERENCE String name, REFERENCE String shortName, int64 defaultValue, REFERENCE String help) RETURNS voidmodifies
An option carrying a whole number: --jobs 8.
MODIFY METHOD addFloatOption(REFERENCE String name, REFERENCE String shortName, float64 defaultValue, REFERENCE String help) RETURNS voidmodifies
An option carrying a floating-point number: --rate 0.25.
MODIFY METHOD require(REFERENCE String name) RETURNS voidmodifies
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 voidmodifies
A required word that is not an option, filled in declaration order.
MODIFY METHOD addOptionalPositional(REFERENCE String name, REFERENCE String help) RETURNS voidmodifies
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 voidmodifies
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 voidmodifies
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 voidmodifies
Make the declarations that follow belong to the command name.
MODIFY METHOD forAllCommands() RETURNS voidmodifies
Make the declarations that follow global again.
MODIFY METHOD collectAfterDoubleDash() RETURNS voidmodifies
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 | booleanmodifies
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 Stringreads
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 booleanreads
TRUE if --help or -h was given.
METHOD isSet(REFERENCE String name) RETURNS booleanreads
TRUE if the flag or option appeared on the command line.
METHOD textValue(REFERENCE String name) RETURNS Stringreads
The option's text: what was given, or its default.
METHOD integerValue(REFERENCE String name) RETURNS int64reads
An integer option's value: what was given, or its default.
METHOD floatValue(REFERENCE String name) RETURNS float64reads
A float option's value: what was given, or its default.
METHOD positional(REFERENCE String name) RETURNS Stringreads
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 Stringreads
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.