Procedures for a getopt and getopt_long implementation to parse command-line parameters in Fortran. More...

Data Types
type	getopt_t
	Struct to define short and long options for getopt_long() More...

Functions/Subroutines
character function	getopt (optstr)
	Parse a command-line parameter and return short options and their arguments. A warning is printed to stderr if an argument is required but not present.

character function	getopt_long (longopts)
	Parse a command-line parameter and return short and/or long options and their arguments. A warning is printed to stderr if an argument is required but not present or vice versa.

subroutine	getopt_get_command ()
	Get the full command line in a string, split compound short options (e.g. "-abc" -> "-a -b -c") and set numberOfArguments.

integer function	getopt_command_argument_count ()
	Return the number of arguments on the command line (excluding the command).

subroutine	getopt_get_command_argument (argnr, arg)
	Returns the argNr-th command-line argument or option.

integer function	getopt_optarg_to_int (minvalue, maxvalue)
	Extract and return an integer value from the argument optArg. On error, report and abort.

real function	getopt_optarg_to_real (minvalue, maxvalue)
	Extract and return a real value from the argument optArg. On error, report and abort.

real(double) function	getopt_optarg_to_dbl (minvalue, maxvalue)
	Extract and return a double value from the argument optArg. On error, report and abort.

subroutine	getopt_split_short_options (cloptstr)
	Split combined short command-line options into several individual ones, e.g. "... -abc ..." -> "... -a -b -c ...".

subroutine	getopt_help (optstr, linebef, lineaft)
	Print a help list of all short options and their required arguments.

subroutine	getopt_long_help (longopts, linebef, lineaft)
	Print a help list of all short/long options, their required arguments and their descriptions.

Variables
character, dimension(9999)	commandline
	The full command line as a single string.

integer	numberofarguments = -1
	The number of arguments on the command line, excluding the command (= argc-1 in C)

character, dimension(999)	curarg
	The current argument or option (word)

character, dimension(999)	optarg
	The option's argument, if required and present.

character, dimension(longoptlen+2)	longoption
	The short or long option found, including leading dash(es)

integer, save	optcount = 0
	The current option count.

character, dimension(999)	getopthelpheader = ''
	The header line for the message printed by getopt(_long)_help()

character, dimension(999)	getopthelpsyntax = ''
	The syntax line for the message printed by getopt(_long)_help()

character, dimension(999)	getopthelpfooter = ''
	The footer line for the message printed by getopt(_long)_help()

Detailed Description

Procedures for a getopt and getopt_long implementation to parse command-line parameters in Fortran.

Getopt implementation in Fortran, similar but not identical to the GlibC implementation. Two possibilities are available:

function getopt(): parses short options only
function getopt_long(): parses short and long options

Both functions return the letter of the option (e.g. 'a' for -a) and set the variable optArg which contains the argument if required and present. In addition, getopt_long() sets the variable longOption which contains the full option found (e.g. "-a" or "--all"). Both functions and variables can be accessed through the SUFR_getopt module.

In addition, a quick help output can be generated (e.g. when no option, a help option or a non-existing option is given) using:

subroutine getopt_help(): prints a help list of all short options and their required arguments
subroutine getopt_long_help(): prints a help list of all short/long options, their required arguments and their descriptions

Remarks

This implementation of getopt was inspired by:

[1] GlibC getopt: man 3 getopt or https://www.gnu.org/software/libc/manual/html_node/Getopt.html
[2] The getopt_long_module by Joe Krahn: http://fortranwiki.org/fortran/show/getopt_long_module
[3] The getoptions module by Dominik Epple: http://www.dominik-epple.de/getoptions/

The general idea comes from [1] and [2], while I followed [3] for the return values indication an issue (>!.). Unlike [3], I wanted both short and long options, allow the argument to be glued to the option (e.g. -ffile.txt) and get a warning if a required argument is missing. Unlike [2] I thought a non-OOP solution might be simpler. In addition, I wanted to allow an equal sign in e.g. –file=file.txt, and to provide a short description for each option, in order to simplify the generation of an explanatory list of options, which is provided through getopt_help() and getopt_long_help().

Function/Subroutine Documentation

◆ getopt()

character function sufr_getopt::getopt ( character, dimension(*), intent(in) optstr )

Parse a command-line parameter and return short options and their arguments. A warning is printed to stderr if an argument is required but not present.

Parameters

optStr String defining the allowed short options. Characters followed by a colon have a required argument. Example: 'ab:c' for -a, -b <arg> and -c.

Return values

getopt

Either:

a '>' if no further command-line parameters were found
a '!' if an unidentified option was found
a '.' if a non-option argument was found
a single character identifying the short version of the option identified (without the leading dash)

The following 'global' variables are set (accessible through the module SUFR_getopt):

commandLine: the full command line as a single string
curArg: the current argument or option
optArg: the argument, if required and present

Definition at line 95 of file getopt.f90.

References curarg, getopt(), getopt_command_argument_count(), getopt_get_command(), getopt_get_command_argument(), optarg, and optcount.

Referenced by getopt().

Here is the call graph for this function:

◆ getopt_command_argument_count()

integer function sufr_getopt::getopt_command_argument_count

Return the number of arguments on the command line (excluding the command).

Return values

getopt_command_argument_count Number of arguments excluding the command

Definition at line 336 of file getopt.f90.

References getopt_command_argument_count(), getopt_get_command(), and numberofarguments.

Referenced by getopt(), getopt_command_argument_count(), and getopt_long().

Here is the call graph for this function:

◆ getopt_get_command()

subroutine sufr_getopt::getopt_get_command

Get the full command line in a string, split compound short options (e.g. "-abc" -> "-a -b -c") and set numberOfArguments.

Definition at line 317 of file getopt.f90.

References commandline, sufr_text::count_substring(), getopt_split_short_options(), and numberofarguments.

Referenced by getopt(), getopt_command_argument_count(), getopt_get_command_argument(), and getopt_long().

Here is the call graph for this function:

◆ getopt_get_command_argument()

subroutine sufr_getopt::getopt_get_command_argument	(	integer, intent(in)	argnr,
		character, dimension(99), intent(out)	arg )

Returns the argNr-th command-line argument or option.

Parameters

argNr	Number of the desired argument
arg	Content of the desired argument (a word/string)

Definition at line 354 of file getopt.f90.

References commandline, getopt_get_command(), sufr_text::int2str(), numberofarguments, and sufr_system::quit_program_error().

Referenced by getopt(), and getopt_long().

Here is the call graph for this function:

◆ getopt_help()

subroutine sufr_getopt::getopt_help	(	character, dimension(*), intent(in)	optstr,
		integer, intent(in), optional	linebef,
		integer, intent(in), optional	lineaft )

Print a help list of all short options and their required arguments.

Parameters

optStr	Short-options string used for getopt()
lineBef	Number of lines to print before option list (default: 0)
lineAft	Number of lines to print after option list (default: 0)

Note: If the string variables getoptHelpHeader, getoptHelpSyntax or getoptHelpFooter are set, a header, syntax or footer line is printed in addition to the options. By default, the strings are empty and the lines are not printed.

Definition at line 573 of file getopt.f90.

References getopthelpfooter, getopthelpheader, getopthelpsyntax, and sufr_constants::program_name.

◆ getopt_long()

character function sufr_getopt::getopt_long ( type(getopt_t), dimension(:), intent(in) longopts )

Parse a command-line parameter and return short and/or long options and their arguments. A warning is printed to stderr if an argument is required but not present or vice versa.

Parameters

longopts

Long-options used for getopt_long(). This is an array of getopt_t structs, each of which contains:

short: the short option (single character, without the leading dash)
long: the long option (without the leading dashes, max 99 characters long)
reqArg: argument required? 0-no, 1-yes
descr: a (short) description (recommended: <1 screen width; max 999 characters) An example entry would be getopt_t('f','file',1,'Input file name').

Return values

getopt_long

Either:

a '>' if no further command-line parameters were found
a '!' if an unidentified option was found
a '.' if a non-option argument was found
a single character identifying the short version of the option identified (without the leading dash)

The following 'global' variables are set (accessible through the module SUFR_getopt):

commandLine: the full command line as a single string
curArg: the current argument or option
longOption: the short or long option found, including leading dash(es)
optArg: the option's argument, if required and found

Definition at line 194 of file getopt.f90.

References curarg, getopt_command_argument_count(), getopt_get_command(), getopt_get_command_argument(), getopt_long(), longoption, optarg, and optcount.

Referenced by getopt_long().

Here is the call graph for this function:

◆ getopt_long_help()

subroutine sufr_getopt::getopt_long_help	(	type(getopt_t), dimension(:), intent(in)	longopts,
		integer, intent(in), optional	linebef,
		integer, intent(in), optional	lineaft )

Print a help list of all short/long options, their required arguments and their descriptions.

Parameters

longopts	Long-options struct used for getopt_long()
lineBef	Number of lines to print before option list (default: 0)
lineAft	Number of lines to print after option list (default: 0)

Note: If the string variables getoptHelpHeader, getoptHelpSyntax or getoptHelpFooter are set, a header, syntax or footer line is printed in addition to the options. By default, the strings are empty and the lines are not printed.

Definition at line 642 of file getopt.f90.

References getopthelpfooter, getopthelpheader, getopthelpsyntax, and sufr_constants::program_name.