Arguments in gambas programs

First off, the difference between OPTIONS and ARGUMENTS. I'll use something we all have as an example. In a virtual terminal type

You should get something like:

Compile Gambas projects into architecture-independent bytecode.

On the "Usage" line note that the program accepts optionally both OPTIONS and ARGUMENTS. In fact it uses 1 ARGUMENT the <project directory>, which is mandatory in almost all cases..

Below that line is a list of the OPTIONS that can be used.

Why is this important? Because the native Args class provided by the "gb" component considers the whole command line as a space delimited list of ARGUMENTS (no OPTIONS handling is done and it would be up to the program code to decipher each token and decide what it is and how to work with it.

Enter the "gb.args" component.

This component provides much more sophisticated handling of OPTIONS. The program ARGUMENTS are still returned as a read only array.

There are two types of OPTIONS. The first I'll call "flags". These are OPTIONS that stand alone. Their presence in the command line or absence signifies something by itself. Almost all the gbc3 OPTIONS are flags. In fact all but the -r/--root options are flags. The second type I'll call "value" options. The -r/--root option requires a value i.e. a string value. Other value options you may want in your program could be floats or integers.

But one final note. All the header lines in the above gbc3 -h output above the Options: line are "usage" comments.

So, what does gb.args provide?

It exposes one class, "Args" as explained in the help page that performs a lot of work for your CLI projects without having to code it yourself.

Firstly the simple one - the -V/--version OPTION is automatically handled, just by having the gb.args component included.

Secondly the -h/--help OPTION is handled automatically and also you can provide very sophisticated information about you program by using the gb.args "algorithm" below.

In your program startup module, i.e. the Main sub, (or a routine called by Main (to keep things nicely compartmentalised) we need to do the following:

1. Start the CLI options/arguments handler

2. Test for the presence of each of your program OPTIONS and where

applicable, get their values

1. Tell the handler to stop parsing and return THE REST of the CLI

input as a set of ARGUMENTS in a string array.

so, by way of examplle:

[gb.markdown].Markup.ProcessCode.1104: Cannot load component 'gb.highlight': cannot find component

Using only arguments

But it also takes a string argument that is the "usage" header printed when the -h option is included by the user on the command line. That is all you have to do to get your program to display as sophisticated a "usage" header as you require is to include it as a single string in the Args.Begin call. For example

[gb.markdown].Markup.ProcessCode.1104: Cannot load component 'gb.highlight': cannot find component

would result in a -h ouput usage header like:

[gb.markdown].Markup.ProcessCode.1104: Cannot load component 'gb.highlight': cannot find component

Now what sort of options do we want? Lets start with a simple "flag" that if present on the command line will cause you program to print out lots of debugging information as it runs. Let's say we are going to use -d/--debug. The way to test whether the user wants the debug output is to test for this flag using the Args.Has() function. So:

[gb.markdown].Markup.ProcessCode.1104: Cannot load component 'gb.highlight': cannot find component

Noting that Args.Has() returns a boolean (that we will set a global variable so we can use it later where necessary). You also see the ShortName, LongName and Description parameters populated such that the -h output will now show :

[gb.markdown].Markup.ProcessCode.1104: Cannot load component 'gb.highlight': cannot find component

Using arguments parameters and options

Let's change our mind and provide three different levels of debug output. This time we use an integer value option as follows:

[gb.markdown].Markup.ProcessCode.1104: Cannot load component 'gb.highlight': cannot find component

lotsheaps or tins of debugging information to the terminal", "level", 1)

With this, if the user species the -d/--debug pair on the command line the $debugLevel value will be set to that value. (if they only provide the option without a value then it will be set to 1 - automagically!

The -h output will now look like:

[gb.markdown].Markup.ProcessCode.1104: Cannot load component 'gb.highlight': cannot find component

Hmm, we can do better than that! Is 1 equal to "lots" or "tons"?

Lets try a string value option:

[gb.markdown].Markup.ProcessCode.1104: Cannot load component 'gb.highlight': cannot find component

If present then the $debugLevelStr value will be set to the value provided (NOTE! the gb.args Args.Get() function does NOT provide a default value!). And the -h output will look like:

[gb.markdown].Markup.ProcessCode.1104: Cannot load component 'gb.highlight': cannot find component

Args.GetFloat() acts similarly to Args,GetInteger.

Now there is only one thing left, the Args.End() call. This handles the program ARGUMENTS exactly as specified in the help page, So,

[gb.markdown].Markup.ProcessCode.1104: Cannot load component 'gb.highlight': cannot find component

It would be usual to indicate the ARGUMENTS in the usage header indicating whether they are optional and whether multiple values are handled. Say we need one or more file names as ARGUMENTS. Then something like

[gb.markdown].Markup.ProcessCode.1104: Cannot load component 'gb.highlight': cannot find component

would be appropriate.

When you consider the amount of code you would have to write to handle the above using the simple gb Args class, it's quite amazing actually.

See also

• https://lists.gambas-basic.org/pipermail/user/2019-October/068021.html