GAMBAS-BOOK 3.19.5

Gambas provides special class properties, a class, and a component for working with options and arguments in Gambas programs that are passed to the gambas interpreter gbx3:

• Use of the three read-only properties (All, Count, Max) of the class Args (gb)
• Using the static property Application. Args (data type Args) of the class Application
• Use of the class Args in the component gb. args with five methods to implement a parser for program options and program arguments

This class Args (gb) implements an array containing the arguments passed to a Gambas program on the console. This class behaves like a static read-only array. The following For-Each control structure, for example, runs through all arguments in the argument list:

Dim sElement AS String
For Each sElement In Args
  Print sElement
Next

For example, you can determine the program name using the first element in the Args array (index = 0):

Dim sArgumentPN As String
sArgumentPN = Args[0] ' Program name

The native class Args of the component gb has only 3 properties:

Table 5.8.1.1.1.1: Properties of class Args (gb)

With these statements

Print "Number of array elements = "; Args.Count
Print "List of all arguments:"
Print Args.All.Join(" | ")

you will see these outputs in a console after starting the program:

hans@linux:~$ gbx3 $HOME/E/ColorSelectA2 -- 50 120 30
Number of array elements = 4
List of all arguments:
ColorSelectA2 | 50 | 120 | 30
hans@linux:~$

From the class Application only the property Application. Args, which returns an array of the data type Args (? chapter 5.8.1.1), which can only be read out, is of interest in connection with arguments for Gambas programs.

The component gb. args allows you to do this:

• the extraction of options,
• the access to all passed arguments in a string array and
• takes over the automatic processing of the options –version (-V)and –help (-h).

The class Args has these five methods:

Table 5.8.1.3.1: Methods of the class Args

Hints:

• With the Begin (…) method you start the analysis of the options and end this analysis with the End () method.
• If the optional parameter (data type string) is specified in the Begin ([ help text]-method, it should describe the program syntax and other program help.
• The program help is called with the –help or -h option (short form). If there is no optional help in the method call, a standard text is output.
• You can get the version number of the Gambas project via the option -V or –version.
• If gb. args finds an error in the command line passed, the Gambas program terminates with exit code 1. For example, if gb. args detects an undefined option' -x' in the command line, then this is an unknown option. However, an unknown option is an error and gb.args automatically terminates the gambas process with exit code 1, so it's good to know that the error code has a value of 1, because then you have good possibilities to find out - for example, for a shell script - why the gambas process was terminated.

Depending on the function parameters of the functions listed in the table above, the following description applies:

• ShortName is the short name of the option (without the hyphen).
• LongName is the full name of the option (without the exactly two hyphens).
• Description is an optional text describing the option. The text is displayed when the program help is requested via -h or –help.
• ArgName is an optional short description of the arguments of the option. The text is displayed when the program help is requested via -h or –help.
• Default is the default value returned when the option is noted without a floating point number or without an integer.

The following source code is an excerpt from the source code of a project, which is presented in chapter 5.8.3:

[1] Public sShape As String
[2] Public aArguments As Variant[]
[3]
[4] Public Sub Form_Open()
[5]   FMain.Center
[6]   FMain.Caption = "Gambas-Programm '" & Application.Name & "' with 1 option and 3 arguments".
[7]
[8]   Args.Begin(SetHelpContent())
[9]   ' Deklaration einer Gambas-Programm-Option: shape
[10]     sShape = Args.Get("s", "shape", "StartPunkt? (j)a oder (n)ein", "j|n")
[11]   aArguments = Args.End() ' Args.End() = Array of the 'real' programme arguments
[12]
[13] ***
[14]
[15]   If Not sShape And aArguments.Count = 0 Then
[16]      SetDefaultArguments()
[17]   Else
[18]      SetOptionAndArguments() ' Including analysis of the option and the 3 arguments
[19]   Endif
[20]
[21]   ShowMap()
[22] End ' Form_Open()
[23]
[24] Private Function SetHelpContent() As String
[25]   Dim sUsage As String
[26]
[27]   sUsage = gb.NewLine
[28]   sUsage &= "Runs a Gambas program to display maps from OpenStreetMap" & gb.NewLine
[29]   sUsage &= gb.NewLine
[30]   sUsage &= "Aufruf: " & "gbx3 ProjektPfad " & "-- [Optionen] [-- <Breite> <Länge> <Zoom>]"
[31]   sUsage &= "Usage : " & "gbx3 ProjectPath " & "-- [options]  [-- <latitude> <longitude> <zoom>]"
[32]   sUsage &= gb.NewLine
[33]   sUsage &= "Syntax:" & gb.NewLine
[34]   sUsage &= "gbx3 ProjektPfad -- -s [j|n] [-- LAT LON ZOOM] (without °unit)" & gb.NewLine
[35]   sUsage &= "gbx3 ProjektPfad -- --shape [j|n] [-- LAT LON ZOOM]" & gb.NewLine
[36]   sUsage &= gb.NewLine
[37]   sUsage &= "Format for the geographical coordinates latitude (LAT) and longitude (LON)" & gb.NewLine
[38]   sUsage &= "Decimal degree -90° < latitude " & String.Chr(8804) & " +90°"
[39]   sUsage &= " | -180° < Length° " & String.Chr(8804) & " +180°" & gb.NewLine
[40]   sUsage &= gb.NewLine
[41]   sUsage &= "Example 1: gbx3 $HOME/Map -- -s j -- 52,787969 11,752522 15" & gb.NewLine
[42]   sUsage &= "Example 2 : gbx3 $HOME/Map -- --shape n -- 0.02 -90.01 7" & gb.NewLine & gb.NewLine
[43]   sUsage &= "The zoom factor is in the interval: 1 " & String.Chr(8804) & " ZOOM " & \
[44]              String.Chr(8804) & " 18 ( ZOOM " & String.Chr(8714) & " Integer )."
[45]
[46]   Return sUsage
[47]
[48] End ' Function SetUsage()

For demonstration purposes, this source code section has been inserted at (3*):

' Control:
  Print "Option value 'Shape' = "; sShape
  For i = 0 To Args.End().Max
    Print i + 1; ". Argument: Value = "; Args.End()[i]
  Next
  Print "-----------------------------"
  For Each sElement In aArguments
    Print "Argument value = "; sElement
  Next

Comment:

• The program argument analysis starts in line 8. The procedure has been passed as a parameter the help text from lines 24 to 48.
• You can see how to define an option (complete) with two values of the data type string in line 10.
• The End () method terminates the analysis started in line 8. After that, the string array Args. End () contains all real program arguments.

The syntax of the following line is interesting:

hans@linux:~$ gbx3 $HOME/E/OSMapA -- --shape j -- 52.7904 1.0200 9

• The interpreter gbx3 expects the path to the project directory; here $HOME/E/OSMapA.
• The red double line tells the interpreter that everything following the Gambas process should be passed unchanged. gb. args operates on these data.
• After at least one blank character, the name of the option follows immediately after a double line, followed by the value of the option after at least one blank character.
• The list of options is followed by the blue double strokes that mark the beginning of the list of arguments. Note a space as a separator (at least) here, too.

These are the (alternative) calls and the output in the console:

hans@linux:~$ gbx3 $HOME/E/OSMapA -- -s j -- 52.7904 1.0200 9
hans@linux:~$ gbx3 $HOME/E/OSMapA -- -shape j -- "52.7904" "1.0200" "9"  → Alternative call
Option value 'Shape' = j
1. Argument: Value = 52.7904
2. Argument: Value = 1.0200
3. Argument: Value = 9
-----------------------------
Value of the argument = 52.7904
Value of the argument = 1.0200
Value of the argument = 9
hans@linux:~$

To access the program help:

hans@linux:~$ gbx3 $HOME/E/OSMapA -- --help
hans@linux:~$ gbx3 $HOME/E/OSMapA -- -h

Runs a Gambas programme to display maps from OpenStreetMap

Aufruf: gbx3 ProjektPfad -- [Optionen] [-- <Breite> <Länge> <Zoom>]
Usage : gbx3 ProjectPath -- [options]  [-- <latitude> <longitude> <zoom>]

Syntax:
gbx3 Project path -- -s [j|n] [-- LAT LON ZOOM] (without °unit)
gbx3 Project path -- --shape [j|n] [-- LAT LON ZOOM]

Format for the geographical coordinates latitude (LAT) and longitude (LON)
Decimal degree -90° < latitude° ≤ +90° | -180° < longitude° ≤ +180°

Example 1: gbx3 $HOME/Map -- -s j -- 52,787969 11,752522 15
Example 2 : gbx3 $HOME/Map -- --shape n -- 0.02 -90.01 7

The zoom factor is in the interval: 1 ≤ ZOOM ≤ 18 ( ZOOM ∊ Integer ).

Options:
 -s --shape <j|n>                       StartPunkt? (j)a oder (n)ein
 -V --version                           Display version
 -h --help                              Display this help
hans@linux:~$

Nothing more was to be expected after this call as an issue:

hans@linux:~$ gbx3 $HOME/E/OSMapA -- --version
0.1.28
hans@linux:~$

Two special features when entering options and program arguments are briefly discussed with examples.

Example 1:
Since all arguments are read in as a string, it is necessary to mask certain characters in the console within the string:

hans@linux:~$ gbx3 $HOME/E/OSMapB -- --modus s -- 52°47\'20\'\'N 11°45\'36\'\'E 13
hans@linux:~$ gbx3 $HOME/E/OSMapB -- --modus s -- "52°47'20''N" "11°45'36''E" "13"

Example 2:
If an option has been defined, you must enter the two double strokes before the list of options - even if you explicitly deal with the missing entry of an option in the source code:

hans@linux:~$ gbx3 $HOME/E/OSMapA -- -- 52.7904 1.0200 9
The option 'shape' is set from 'non-defined' to j(a).
hans@linux:~$