MODULE ARG @public

summary

Methods for command line flags.

The list of all arguments is processed and flags (arguments starting with a dash) are separated from the others.

The flag objects can be created at the module level or in the SHARED section of a class. The command line is processed during startup, after which the flag values are available for use. See the @http://www.zimbu.org/documentation/startup-sequence@startup sequence@ for details.

For example, with these flags:

 ARG.Usage usage = NEW("Usage: %0% [flags] filename ...")
 ARG.Bool verbose = NEW("v", "verbose", FALSE, "verbose messages")
 ARG.Int number = NEW("n", "number", -1, "some number")
 ARG.String text = NEW("t", "text", "not set", "some text").enableRepeat()

These command lines could be used:

 prog -v -n123 -t foo -t bar someFile
 prog -n=999 someFile otherFile

To see all the flags and usage the --help flag is supported by default:

 prog --help
 Usage: prog [flags] filename ...
 Command line flags:
 --morehelp           show more verbose help
 -n {number} 
 --number {number}    some number
 -t {string} ...
 --text {string} ...  some text
 -v --verbose ...     verbose messages

Arguments after "--" are not recognized as a flag, even when they start with a dash. The "--" itself is not included. For example, using "--help" as a file name:

 prog -- --help

The dash by itself is handled like a non-flag argument. It is sometimes used for a file name to indicate stdin or stdout.

CLASS	Status @public	Dummy class, returned by methods that need to be invoked before command line flags are parsed.
CLASS	Usage @public	The Usage message to be displayed when there is a flag error and for --help.
CLASS	Flag @public	The abstract base class of all flags.
CLASS	Bool @public	A Flag that has no argument, it's presence is noted.
CLASS	Int @public	A Flag that has one number argument.
CLASS	String @public	A Flag that has one string argument.
CLASS	StringList @public	A Flag that includes all following arguments.

string	rawName @public	The executable name as given
string	exeName @public	The executable name with path and symbolic links resolved.

	Size() int @public	Return the number of arguments that are not flags.
	getList() list<string> @public	Return a list with arguments that are not flags.
	get(index) string @public	Return non-flag argument index.
	rawSize() int @public	Return the total number of arguments, including flags.
	getRawList() list<string> @public	Return a list with all arguments, including flags.
	replaceRawList(argList) @public	Replace the list with all arguments, including flags.
	getRaw(index) string @public	Return argument index. Includes flags.
	stopAtNonFlag(stop) ARG.Status @public	Set whether to stop looking for flags at the first non-flag argument.
	disable() ARG.Status @public	Disable procesing command line flags.
	disableHelp() ARG.Status @public	When on is TRUE display help and exit when the "--help" flag is found.
	disableCompact() ARG.Status @public	Disable the compact form of flag values.
	setExitValue(value) ARG.Status @public	Set the EXIT value used after displaying the flags for --help.
	getExeDir() string @public	Returns the directory of the executed program.

members (alphabetically)

string exeName @public

The executable name with path and symbolic links resolved.

Equivalent to IO.findExe(ARG.rawName). On MS-Windows backslashes are replaced with forward slashes.

string rawName @public

The executable name as given

Not necessarily valid utf-8.

FUNC Size() int @public

Return the number of arguments that are not flags.

Can only be used after EarlyInit(), when ARG.Ready is TRUE.

FUNC disable() ARG.Status @public

Disable procesing command line flags.

No Flag definitions are allowed.

This must be invoked in EarlyInit() or earlier.

The get(), getFlag() and getRaw() methods can still be used.

Returns a Status object, so that it can be used at the module level like this:

 ARG.Status argStatus = ARG.disable()

FUNC disableCompact() ARG.Status @public

Disable the compact form of flag values.

The compact form is giving a value to a flag without an "=". For example, when "-n" is a Int flag, "-n123" uses value "123".

The compact form is allowed by default. It can also be disabled for each individual flag.

Returns a Status object, so that it can be used at the module level like this:

 ARG.Status help = ARG.disableCompact()

FUNC disableHelp() ARG.Status @public

When on is TRUE display help and exit when the "--help" flag is found.

When FALSE the --help flag is not recognized.

Returns a Status object, so that it can be used at the module level like this:

 ARG.Status help = ARG.giveHelp(FALSE)

FUNC get(int index) string @public

Return non-flag argument index.

The first argument is at index zero. When index is out of range return NIL.

Can only be used after EarlyInit(), when ARG.Ready is TRUE.

FUNC getExeDir() string @public

Returns the directory of the executed program.

Equal to exeName with the program name and trailing slash removed. Can be used like this:

 configFile = ARG.getExeDir() .. "/prog.conf"

Returns "." when exeName does not have a directory.

FUNC getList() list<string> @public

Return a list with arguments that are not flags.

Can only be used after EarlyInit(), when ARG.Ready is TRUE.

FUNC getRaw(int index) string @public

Return argument index. Includes flags.

The first argument is at index zero. When index is out of range return NIL.

FUNC getRawList() list<string> @public

Return a list with all arguments, including flags.

FUNC rawSize() int @public

Return the total number of arguments, including flags.

PROC replaceRawList(list<string> argList) @public

Replace the list with all arguments, including flags.

Can be used to remove arguments that should not be parsed.

This must be invoked in EarlyInit() or earlier.

FUNC setExitValue(int value) ARG.Status @public

Set the EXIT value used after displaying the flags for --help.

The default EXIT value is 1.

Returns a Status object, so that it can be used at the module level like this:

 ARG.Status exitv = ARG.setExitValue(256)

FUNC stopAtNonFlag(bool stop) ARG.Status @public

Set whether to stop looking for flags at the first non-flag argument.

The default is FALSE: also find flags after a non-flag argument.

This must be invoked in EarlyInit() or earlier.

Returns a Status object, so that it can be used at the module level like this:

 ARG.Status stop = ARG.stopAtNonFlag(TRUE)

license

Licensed under the Apache License, Version 2.0. See the LICENSE file or obtain a copy at: http://www.apache.org/licenses/LICENSE-2.0