FTN_Getopt Documentation

The module ftn_getopt supplies a method for handling command arguments in a manner similar to the getopt facility in C.

Author

R. Bader

General Description

Command line options are strings that can be interpreted as key-value pairs representing values of type logical, integer, real, or character string, respectively. A logical option takes its value from its presence on the command line, all other types require an additional string argument.

The following ways of specifying options on the command line are supported:

• --switch for a logical option (true if option appears)
• --switch <value> for an otherwise typed option
• --switch=<value> equivalent to the preceding

As an optional feature, it is also possible to add short option processing:

• -s for a logical option
• -stu same as -s -t -u
• -s <value> for an otherwise typed option

Only the first appearance of an option on the command line will be processed.

Inside a program unit, the sequence of processing is as follows:

1. invoke optinit() to create an option (a scalar or array of type opt_t)
2. invoke optarg() to extract the option(s) from the command line
3. invoke optval() to obtain the result object

An example of how this might look like is

USE ftn_getopt
TYPE(opt_t) :: option
INTEGER :: nopt

option = optinit('nopt', 'integer')
CALL optarg(option)
CALL optval(option, nopt)

The last procedure call will supply the value of the command line option --nopt <integer> to the variable nopt. If the option is not encountered, the variable's value will remain unchanged. If no integer value can be extracted, the program will terminate, although error handling can also be deferred to the programmer if the optional stat argument is added to the procedure invocation.

Addition interfacing is available for convenience:

• list of currently unprocessed command line items via optignored,
• check whether an option has been successfully set by optarg via optset(),
• obtain sequence index of a set option in the command line via optind(),
• obtain the length of a string-valued option via optlen().

The facilities supplied here are not thread-safe. All procedure calls should be executed from the initial master thread, or need to be mutexed against other threads (e.g. appear inside a critical region).

Acknowledgment: Some ideas for the implementation were taken from Arjen Markus' command_args module in his FLIBS project http://flibs.sourceforge.net/, but the code given here was written from scratch.