getopts interface (Marco’s Bash Functions Library)

9.4 Interface functions

Every declared option should have a long switch, the brief switch can be omitted.

Function: mbfl_declare_option keyword default brief long hasarg description

Declare a new option. Arguments description follows.

keyword: A string identifying the option; internally it is used to build a function name and a variable name. It is safer to limit this string to the letters in the ranges a-z, A-Z and underscores.
default: The default value for the option. For an option with argument it can be anything; for an option with no argument: it must be yes or no.
brief: The brief option selector: a single character. It is safer to choose a single letter (lower or upper case) in the ASCII standard.
long: The long option selector: a string. It is safer to choose a sequence of letters in the ASCII standard, separated by underscores or dashes.
hasarg: Either witharg or noarg: declares if the option requires an argument or not.
description: A one–line string briefly describing the option.

Function: mbfl_getopts_parse

Parse a set of command line options. The options are handed to user defined functions. The global array ARGV1 and the global variable ARGC1 must hold the command line arguments and the number of command line arguments, the global variable ARG1ST must hold the index of the first element in ARGV1 that must be parsed. Non–option arguments are left in the global array ARGV, the global variable ARGC holds the number of elements in ARGV.

If successful return 0, else return 1.

Function: mbfl_getopts_islong string

Function: mbfl_getopts_islong string varname

Verify if a string has the format of a long option without argument. string is the string to validate. The optional varname is the name of a variable that this function will set to the option name from string, without the leading dashes.

Return with code zero if the string is a long option without argument, else returns with code one.

An option must be of the form --option, only characters in the ranges A-Z, a-z, 0-9 and the characters - and _ are allowed in the option name.

Usage examples:

mbfl_getopts_islong --option            ⇒ 0
mbfl_getopts_islong --option=123        ⇒ 1
mbfl_getopts_islong gasp                ⇒ 1

Function: mbfl_getopts_islong_with string

Function: mbfl_getopts_islong_with string optname varname

Verify if a string has the format of a long option with argument. Arguments:

string: The string to validate.
optname: Optional name of a variable that this function will set to the option name from string, without the leading dashes.
varname: Optional name of a variable that this function will set to the option value from string.

Return with code 0 if the string is a long option with argument. Return with code 1 if the string is not an option with argument.

An option must be of the form --option=value, only characters in the ranges A-Z, a-z, 0-9 and the characters - and _ are allowed in the option name.

If the argument is not an option with value, the variable names are ignored.

Usage examples:

mbfl_getopts_islong_with --option=one   ⇒ 0
mbfl_getopts_islong_with --option       ⇒ 1
mbfl_getopts_islong_with wappa          ⇒ 1
mbfl_getopts_islong_with --option=      ⇒ 1
mbfl_getopts_islong_with --=            ⇒ 1

Function: mbfl_getopts_isbrief string

Function: mbfl_getopts_isbrief string varname

Verify if a string has the format of a brief option without argument. string is the string to validate. The optional varname is the name of a variable that this function will set to the option name from string, without the leading dash.

Return with code zero if the argument is a brief option without argument, else return with code one.

A brief option must be of the form -a, only characters in the ranges A-Z, a-z, 0-9 are allowed as option letters.

Usage examples:

mbfl_getopts_isbrief -o         ⇒ 0
mbfl_getopts_isbrief -o123      ⇒ 1
mbfl_getopts_isbrief gasp       ⇒ 1

Function: mbfl_getopts_isbrief_with string

Function: mbfl_getopts_isbrief_with string optname valname

Verify if a string has the format of a brief option with argument. Arguments:

string: The string to validate.
optname: Optional name of a variable that this function will set to the option name from string, without the leading dashes.
valname: Optional name of a variable that this function will set to the option value.

Return with code zero if the argument is a brief option without argument, else return with code one.

A brief option must be of the form -aV (a is the option, V is the value), only characters in the ranges A-Z, a-z, 0-9 are allowed as option letters.

Usage examples:

mbfl_getopts_isbrief_with -o123         ⇒ 0
mbfl_getopts_isbrief_with -o            ⇒ 1
mbfl_getopts_isbrief_with --option      ⇒ 1
mbfl_getopts_isbrief_with wappa         ⇒ 1

Function: mbfl_wrong_num_args required present: Validate the number of arguments. required is the required number of arguments, present is the given number of arguments on the command line. If the number of arguments is different from the required one: print an error message and return with code one; else return with code zero.

Function: mbfl_wrong_num_args_range min_required max_required argc: Validate the number of arguments. argc must be between min_required and max_required, inclusive.

Function: exit_because_wrong_num_args
Function: return_because_wrong_num_args: Exit or return with code 98.

Function: mbfl_argv_from_stdin

If the ARGC global variable is set to zero: fills the global variable ARGV with lines read from stdin. If the global variable mbfl_option_NULL is set to yes: lines are read using the null character as terminator, else they are read using the standard newline as terminator.

This function may block waiting for input.

Function: mbfl_argv_all_files: Check that all the arguments in ARGV are file names of existent files. Return with code zero if no errors, else print an error message and return with code 1.

Function: mbfl_getopts_print_long_switches: Print all the long switches in a row, separated by spaces. This is useful to retrieve the option for Bash programmable completion.

Function: exit_because_invalid_option_declaration
Function: return_because_invalid_option_declaration: Exit or return with code 93.

Function: exit_because_invalid_option_argument
Function: return_because_invalid_option_argument: Exit or return with code 92.

This document describes version 3.0.0-devel.0 of Marcos Bash Functions Library.