---

22.2 Declaring the intention to use a program ¶

To make a script model simpler, we assume that the unavailability of a program at the time of its execution is a fatal error. So if we need to execute a program and the executable is not there, the script must be aborted on the spot.

Functions are provided to test the availability of a program, so we can try to locate an alternative or terminate the process under the script control. On a system where executables may vanish from one moment to another, no matter how we test a program’s existence, there’s always the possibility that the program is not “there” when we invoke it.

The vanishing of a program is a rare event: if it’s there when we look for it, probably it will be there also a few moments later when we invoke it. For this reason, MBFL proposes a set of functions with which we can declare the intention of a script to use a set of programs.

A command line option is predefined to let the user test the availability of all the declared programs before invoking the script; Predefined options.

Function: mbfl_declare_program PROGRAM ¶

Register PROGRAM as the name of a program required by the script; mbfl_program_find() is used to locate the program on the system. Checking programs existence.

If PROGRAM is a file name with no directory part (examples: sed, grep) the selected program is the full pathname of the file in one of the directories of PATH.

If PROGRAM is a relative pathname (examples: ../bin/sed, ./grep): the selected program is the full pathname of the file normalised by this function with respect to the current working directory (with a call to mbfl_file_normalise()).

If PROGRAM is an absolute pathname (examples: /bin/sed, /bin/grep): the selected program is the full pathname itself.

The return value is always zero.

Function: mbfl_program_validate_declared ¶

Validate the existence of all the declared programs. The return value is 0 if all the programs are found, 1 otherwise.

This function is invoked by mbfl_getopts_parse() when the --validate-programs option is used on the command line.

It may be a good idea to invoke this function at the beginning of a script, just before starting to do stuff, example:

mbfl_program_validate_declared || exit_because_program_not_found

If verbose messages are enabled: a brief summary is echoed to stderr.

Function: mbfl_program_found PROGRAM ¶

Function: mbfl_program_found_var _RV PROGRAM ¶

Print the pathname of the previously declared PROGRAM. Return zero if the program was found, otherwise print an error message and return by invoking return_because_program_not_found().

function program_wrapper () {
    mbfl_mandatory_parameter(PATHNAME, 1, argument)
    shift
    local PROGNAME FLAGS

    PROGNAME=$(mbfl_program_found myprog) || exit_because_program_not_found

    mbfl_option_verbose_program && FLAGS+=' --verbose'
    mbfl_program_exec "$PROGNAME" $FLAGS "$@" '--' "$PATHNAME"
}

Remember that we cannot use:

local PROGNAME=$(mbfl_program_found 'myprog') || exit_because_program_not_found

because local has exit status zero even if mbfl_program_found() fails, so the error will not be reported.

The function variant _var will store the result in _RV rather than printing it.

function program_wrapper () {
    mbfl_mandatory_parameter(PATHNAME, 1, argument)
    shift
    mbfl_declare_varref(PROGNAME)
    local FLAGS

    mbfl_program_found_var mbfl_datavar(PROGNAME) myprog || exit_because_program_not_found

    mbfl_option_verbose_program && FLAGS+=' --verbose'
    mbfl_program_exec "$PROGNAME" $FLAGS "$@" '--' "$PATHNAME"
}

Function: exit_because_program_not_found ¶

Alias: return_because_program_not_found ¶

Exit or return with code 99.