User Tools

Site Tools


k5:k5.8:k5.8.1:start

5.8.1 Options and arguments for Gambas programs

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

5.8.1.1 Class Args

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] ' Programm-Name

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

PropertyData typeDescription
AllString[]Returns a copy of all arguments as a string array.
CountIntegerReturns the number of arguments passed in the console.
MaxIntegerReturns Args Count - 1.

Table 5.8.1.1.1.1: Properties of class Args (gb)

With these statements

Print "Anzahl der Array-Elemente = "; Args.Count
Print "Liste aller Argumente:"
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 
Anzahl der Array-Elemente = 4 
Liste aller Argumente: 
ColorSelectA2 | 50 | 120 | 30 
hans@linux:~$ 

5.8.1.2 Selected property of the Application class of the component gb

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.

5.8.1.3 Component Args

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:

MethodDescription
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 StringThe 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 FloatThe 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 BooleanThe function defines an option without parameters.

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.

5.8.1.4 Example

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 & "' mit 1 Option und 3 Argumenten" 
[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 der 'echten' Programm-Argumente  
[12] 
[13] *** 
[14]  
[15]   If Not sShape And aArguments.Count = 0 Then 
[16]      SetDefaultArguments() 
[17]   Else 
[18]      SetOptionAndArguments() ' Inklusive Analyse der Option und der 3 Argumente 
[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 &= "Führt ein Gambas-Programm aus, um Karten von OpenStreetMap anzuzeigen" & 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] (ohne °Einheit)" & gb.NewLine 
[35]   sUsage &= "gbx3 ProjektPfad -- --shape [j|n] [-- LAT LON ZOOM]" & gb.NewLine 
[36]   sUsage &= gb.NewLine 
[37]   sUsage &= "Format für die geografischen Koordinaten Breite (LAT) und Länge (LON)" & gb.NewLine 
[38]   sUsage &= "Dezimalgrad -90° < Breite° " & String.Chr(8804) & " +90°" 
[39]   sUsage &= " | -180° < Länge° " & String.Chr(8804) & " +180°" & gb.NewLine 
[40]   sUsage &= gb.NewLine 
[41]   sUsage &= "Beispiel 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 &= "Der Zoom-Faktor liegt im Intervall: 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*):

' Kontrolle:
  Print "Wert der Option 'Shape' = "; sShape
  For i = 0 To Args.End().Max
    Print i + 1; ". Argument: Wert = "; Args.End()[i]
  Next
  Print "-----------------------------"
  For Each sElement In aArguments
    Print "Wert des Arguments = "; 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"  → Alternativer Aufruf
Wert der Option 'Shape' = j 
1. Argument: Wert = 52.7904 
2. Argument: Wert = 1.0200 
3. Argument: Wert = 9 
----------------------------- 
Wert des Arguments = 52.7904 
Wert des Arguments = 1.0200 
Wert des Arguments = 9 
hans@linux:~$ 

To access the program help:

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

Führt ein Gambas-Programm aus, um Karten von OpenStreetMap anzuzeigen 

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

Syntax: 
gbx3 ProjektPfad -- -s [j|n] [-- LAT LON ZOOM] (ohne °Einheit) 
gbx3 ProjektPfad -- --shape [j|n] [-- LAT LON ZOOM] 

Format für die geografischen Koordinaten Breite (LAT) und Länge (LON) 
Dezimalgrad -90° < Breite° ≤ +90° | -180° < Länge° ≤ +180° 

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

Der Zoom-Faktor liegt im Intervall: 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 
Die Option 'shape' wird von 'nicht-definiert' auf j(a)  gesetzt. 
hans@linux:~$ 

Download

The website uses a temporary session cookie. This technically necessary cookie is deleted when the browser is closed. You can find information on cookies in our privacy policy.
k5/k5.8/k5.8.1/start.txt · Last modified: 04.01.2019 by honsek

Page Tools