[Gambas-user] gb.args - a question

Sun Feb 17 02:03:19 CET 2013

On Sat, 2013-02-16 at 16:31 +0100, Willy Raets wrote:
> On Sat, 2013-02-16 at 14:51 +0100, Tobias Boege wrote:
> > On Sat, 16 Feb 2013, Willy Raets wrote:
> > > Okay Bruce,
> > > 
> > > Thanks again, you got me on the right track and I got it solved showing
> > > me about info without launching the application.
> > > 
> > > Here is how I did it:
> > > 
> > > Public Sub Main()
> > >   
> > >   Dim bAOption As Boolean
> > >   Args.Begin(Application.Name & " <options>")
> > >   bAOption = Args.Has("a", "about", "Display About")
> > >   Args.End()
> > >   If bAOption Then
> > >     Print "Application to test gb.args"
> > >   Else
> > >     FMain.Show
> > >   Endif
> > >   
> > > End
> > > 
> > > When doing <appname> -h it now correctly states "Display About" for help
> > > with -a and --about
> > > When doing <appname> -a it now correctly returns "Application to test
> > > gb.args" (without the GUI application getting launched)
> > > 
> > > Perfect, I think I'm slowly beginning to get a grasp at it.
> > > Public Sub Main()
> > >   
> > >   Dim bAOption As Boolean
> > >   Args.Begin(Application.Name & " <options>")
> > >   bAOption = Args.Has("a", "about", "Display About")
> > >   Args.End()
> > >   If bAOption Then
> > >     Print "Application to test gb.args"
> > >   Else
> > >     FMain.Show
> > >   Endif
> > >   
> > > End
> > > 
> > > Feel free to use this example in documentation if you like (or an
> > > adapted version for that matter). An example tells a whole lot more in
> > > way less time than studying the documentation, try, fail, study
> > > documentation, try, fail, study documentation, try, fail, search google,
> > > find nothing, post on mailing list, get answer, try, fail, study
> > > documentation, try, fail and so on... :)
> > > 
> > > Thanks again Bruce for the spark...
> > 
> > Since gb.args is written in Gambas and implements -V and -h, it is an
> > example itself. Look into comp/src/gb.args/.src/Args.module. It is done with
> > those options there the same way inside Args.End(). I _believe_ that you can
> > even save the bAOption variable by using: If Args.Has(...) Then Print "..."
> > before calling Args.End().
> > 
> > Regards,
> > Tobi
> 
> Thanks Tobi,
> 
> The If Args,Has() Then Print seems very interesting.
> I think I'll have to have a look at the source of gb.args
> Guess that will give more insight :)
> But an example in the documentation wouldn't harm.
> Don't think a lot of us would look in gb,args source code for a
> solution :)
> 

As Tobi says, you can use Args.Has (and the Args.Get's) directly in an
If statement.

However, I advocate not doing that for the following reasons.
a) maybe not now but a future requirement may introduce dependencies
between program options.  Since you have no control over the order in
which the user presents the options, the conditional code can get messy.
b) also, branching out of a single, linear Args.Begin...Args.End code
block may give rise to interpreter problems.

Your mileage may vary, but I believe that a single linear process for
detecting CLI options, setting local or global vars as necessary to be
"better".

I have attached a "heavily documented" version of my demo_gbargs.
Someone may care to place it or its contents where they will do the most
good. (I have recently broken my access to both the wiki and the
sourceforge - at my end not yours, so I can't upload it anywhere but
here.

*** Correction - I tried to attach it, but for some reason I cannot make
a source archive for the project, so I have attached the source file.
Hope it is of some use.

regards
Bruce
-------------- next part --------------
' Gambas module file

''' Demonstrates the use of gb.args for command line option processing. 
''' Note: The code is documented as follows: 
''' An option is an optional token that can be entered by the user, it may be a simple
''' switch or a token that requires a value (the argument) 
''' Some further notes<ol>
''' <li>the token " -- " (note required spaces) delimits option processing. Any and all tokens
''' encountered on the command line after this token are treated as literal strings and are returned by
''' Args.End(). This makes it possible for the user to include literals begining with a "-". For example:
''' <pre>./demo_gbargs -t=3 -- Ahab Bhab -visual</pre>
''' Args.End will return ["Ahab","Bhab","-visual"]</li>
''' <li>Value argument for string options (Args.Get) containing spaces need to be single quoted by the user. If so they 
''' are handled properly by gb.args, for example:
''' <pre>./demo_gbargs -c 'A string with spaces'</pre>
''' Args.Get("c","compile") will return the single string "A string with spaces"</li>
''' <li>When using Project Properties Environment tab to provide command line options, any option that takes a value argument
''' must be entered as separate rows in the list. So, for this project, to specifiy -t add two entried in the Arguments list, the first being "t" 
''' and the second being its value</li>
''' </ol>

Public Sub Main()

  Dim bReconf As Boolean
  Dim iTimes As Integer ' = 1
  Dim fVal As Float
  Dim sTarget As String
  Dim aLeftovers As String[]

  ' The old way
  ' -----------
  ' For idx = 1 To Application.Args.Count - 1
  '   decide what the option is, whether it has an argument, process it accordingly...
  ' Next

  ' The gb.args way
  ' ---------------

    ' All CLI option processing must start with Args.Begin, which can contain an optional string parameter
    ' which is displayed at the beginning of the output when -h is present.

  Args.Begin("(c)2013 Paddys-Hill Dot Net\n\nThis program does nothing but demonstrate gb.args")

    ' Now process all the options (in the order you wish, i.e. no dependence on the order the user provided them!)
    ' 
    ' Args.Has returns a boolean value, True if the option is present on the command line.  This is used for simple
    ' program switches, i.e. they have no argument and are either present or absent.  Args.Has takes two required parameters,
    ' the short and long option strings, and an optional "help text" that is presented to the user when the program is invoked
    ' with the -h option.

  bReconf = Args.Has("r", "reconfigure", "Reconfigure the program")

    ' N.B. Args.Has can also be used directly, as in ...
    ' If Args.Has("a","all","text...")

    ' Args.GetInteger returns an integer value, if both the option and its argument are present on the command line!
      ' (If the user just specifies the option without the accompanying value, the program is halted with the error message:
      ' "argument missing for option -?" or "argument missing for option --?" (where ? is either the short or long option as
      ' specified by the user)
    ' Args.GetInteger takes 2 required parameters, the short and long option strings, and 3 optional parameters that specify:
    ' a) the "help text" (as per Args.Has)
    ' b) a string that is shown on the option help line, indicating the value argument required (for example, the option help
    '    line for the below is displayed as "-t --times <int>                       Requires an integer argument")
    ' c) a default value that will be used if the option and argument is not present on the command line.

  iTimes = Args.GetInteger("t", "times", "Requires an integer argument", "int", 21)

    ' Args.GetFloat returns a float value, if both the option and its argument are present on the command line!
      ' (If the user just specifies the option without tha accompanying value, the program is halted with the error 
      ' message as per Args.GetInteger.
    ' Args.GetFloat takes similar parameters to Args.GetInteger.

  fval = Args.GetFloat("v", "value", "Requires a float argument", "float", 3.1412)

    ' Args.Get returns a string value, if both the option and its argument are present on the command line!
      ' (If the user just specifies the option without tha accompanying value, the program is halted with the error 
      ' message as per Args.GetInteger.
    ' Args.GetInteger takes 2 required parameters, the short and long option strings, and 2 optional parameters that specify:
    ' a) the "help text" (as per Args.Has)
    ' b) a string that is shown on the option help line, indicating the value argument required (for example, the option help
    '    line for the below is displayed as "")
    ' N.B. There is no default value parameter!

  sTarget = Args.Get("c", "compile", "Another dummy argument", "Target")

    ' Finally, Args.End returns any leftover tokens on the command line as a string array. (Typically this might be
    ' a list of files to process.
    ' MORE IMPORTANTLY! The command line options processing must end with a call to Args.End
    ' Args.End takes no parameters.
  aLeftovers = Args.End()

    ' So now we have processed all the recognized options, we can go on with the program logic using those values.
  Print "count=" & Args.Count
  Print "reconfigure=" & bReconf
  Print "times=" & iTimes
  Print "value=" & fVal
  Print "compile=" & sTarget
  Print "other arguments=" & aleftovers.Join("|")

    ' Have fun!

End