Getopt module usage

The getopt.4gl module provides command line argument processing.

Features of getopt.4gl

The getopt.4gl module implements types, functions and methods to process command line arguments in a standard way.

Use this library to implement arguments processing, and provide a common command line option syntax for all your programs.

The options can be defined with a short name (like -c) and a long name (like --compare).

Partial option specification is supported. For example if --compare is defined, a command line argument --comp will match --compare. If the partial option matches several long option names, the error "ambiguous match" is displayed.

Options can have a mandatory or optional value to be provided with the --option-name=option-value form:

$ fglrun myprog --verbose --level=5

If an argument on the command line is in the form @filename, options will be read from the file:

$ fglrun myprog @myoptions

Options can start at a given index in the command line arguments, to support for example commands with verbs followed by options:

$ fglrun myprog capture --verbose --filename=file1
$ fglrun myprog duplicate --source=file1 --destination=file2

Command line arguments can end with a set of free arguments, to be processed after the options:

$ fglrun myprog capture --verbose file1 file2 file3

Steps to implement arguments processing

To implement command line arguments processing with getopt, do the following steps:

Import the getopt module:
```
IMPORT FGL getopt
```
Define a variable with the Getopt type:
```
    DEFINE g getopt.Getopt
```

Define a variable with the GetoptOptions type that will contain the definition of the options (fill this array of options with a variable initializer):

    DEFINE _options getopt.GetoptOptions
        = [(name: "version",
            description: "Version information",
            opt_char: 'v',
            arg_type: getopt.NONE),
           ...

Initialize the Getopt variable with the initialize() or initDefault() method, passing the GetoptOptions array as parameter:
```
    CALL g.initialize("myprog", getopt.copyArguments(2), _options)
```
If needed, use the copyArguments(index) function, to provide the second parameter of the initialize() method, to start command line argument parsing at a given index.

Use the getopt() method in a WHILE loop, to process all command line arguments that correspond to an option definition:

    WHILE g.getOpt() == getopt.SUCCESS
        CASE g.opt_char
            WHEN 'v'
                DISPLAY "Version 1.50"
                EXIT PROGRAM 0
            WHEN 'h'
                CALL g.displayUsage("file ...")
                EXIT PROGRAM 0
            WHEN 'o'
                LET outfile = g.opt_arg
        END CASE
    END WHILE

Additionally, the isEof() method can be used to check if all possible options are processed.

After the WHILE loop, check for the processing status with the methods invalidOptionSeen() or isSuccess():

    IF g.invalidOptionSeen() THEN
        CALL g.displayUsage("file ...")
        EXIT PROGRAM 1
    END IF

If additional arguments are possible, use the getMoreArgumentCount() and getMoreArgument() methods, to process these non-option arguments:

        LET cnt = g.getMoreArgumentCount()
        IF cnt == 0 THEN
            DISPLAY "ERROR: No files were provided..."
            EXIT PROGRAM 1
        ELSE
            FOR ind = 1 TO cnt
                DISPLAY SFMT("File to process: %1", g.getMoreArgument(ind))
            END FOR
        END IF

For a complete example, see getopt().