index Zimbu documentation

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

      Copyright 2009 Bram Moolenaar All Rights Reserved.

      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