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:
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:
| Property | Data type | Description |
|---|---|---|
| All | String[] | Returns a copy of all arguments as a string array. |
| Count | Integer | Returns the number of arguments passed in the console. |
| Max | Integer | Returns Args Count - 1. |
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 class Args has these five methods:
| Method | Description |
|---|---|
| Static Sub Begin ([ Usage As String] | Starts the program argument analysis. Usage is an optional parameter that represents a program help text. |
| Static Function End () As String[] | Ends the program argument analysis and returns all arguments that cannot be interpreted as options in a string array. |
| Static Function Get (shortName As String, LongName As String, Description As String, ArgName As String) ) As String | The function defines an option of type String, whose parameter contains the name of the option (short and long format) and optionally a description of the option. |
| Static Function GetFloat (shortName As String, LongName As String[, Description As String, ArgName As String, Default As Float]) ) As Float | The function defines an option of the type Float, whose parameter contains the name of the option (short and long format) and optionally a description of the option as well as a default value. |
| Static Function GetInteger (shortName As String, LongName As String, Description As String, ArgName As String, Default As Integer] ) As Integer | The function defines an option of type Integer, whose parameter contains the name of the option (short and long format) and optionally a description of the option as well as a default value. |
| Static Function Has (ShortName As String, LongName As String[, Description As String]) As Boolean | The function defines an option without parameters. |
Table 5.8.1.3.1: Methods of the class Args
Hints:
Depending on the function parameters of the functions listed in the table above, the following description applies:
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 syntax of the following line is interesting:
hans@linux:~$ gbx3 $HOME/E/OSMapA -- --shape j -- 52.7904 1.0200 9
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:~$