stdaux.sh

Go to the documentation of this file.

##############################################################################
# @file  stdaux.sh
# @brief Standard auxiliary functions for BASH.
#
# @note The stdaux.sh module is automatically created by BASIS from the
#       template file stdaux.sh.in which is part of the BASIS installation.
#
# Copyright (c) 2011 University of Pennsylvania. All rights reserved.<br />
# See https://www.cbica.upenn.edu/sbia/software/license.html or COPYING file.
#
# Contact: SBIA Group <sbia-software at uphs.upenn.edu>
##############################################################################

# return if already loaded
[ "${_SBIA_STDAUX_STDAUX_INCLUDED:-0}" -eq 1 ] && return 0
_SBIA_STDAUX_STDAUX_INCLUDED=1


## @addtogroup BasisBashUtilities
#  @{


# ============================================================================
# version / contact
# ============================================================================

# ----------------------------------------------------------------------------
## @brief Print version information.
#
# @param [in] name      Name of program. Give a constant expression here,
#                       @b not the name of the executable as extracted from
#                       the first command-line argument or similar! By default,
#                       however, the executable name is extracted from the first
#                       command-line argument. This is @b not recommended.
# @param [in] copyright Copyright and license notice. Defaults to official
#                       SBIA software license.
#
# @returns Nothing.
function print_version
{
    local name=${1:-}
    local copyright=${2:-}
    if [ -z "${name}" ]; then
        echo "print_version(): Executable name not specified!" 1>&2
        exit 1
    fi
    if [ -z "${copyright}" ]; then
        copyright="Copyright (c) University of Pennsylvania. All rights reserved.\n\
See https://www.cbica.upenn.edu/sbia/software/license.html or COPYING file."
    fi
    echo "${name} (BASIS) version 1.2.3 (revision 2104)"
    echo -e "${copyright}"
}

# ----------------------------------------------------------------------------
## @brief Print contact information.
#
# @param [in] contact Contact name. Defaults to official software contact.
#                     Generally, it is @b not advised to use a contact different
#                     from the official one.
#
# @returns Nothing.
function print_contact
{
    echo "Contact:"
    if [ $# -gt 0 ]; then
        echo -e "  $1"
    else
        echo "  SBIA Group <sbia-software at uphs.upenn.edu>"
    fi
}

# ============================================================================
# command execution
# ============================================================================

# ----------------------------------------------------------------------------
## @brief Execute command as subprocess.
#
# This function is used to execute a subprocess within a BASH script.
#
# Example:
# @code
# # the next command will exit the current shell if it fails
# execute_process ls /not/existing
# # to prevent this, provide the --allow_fail option
# execute_process --allow_fail ls /not/existing
# # to make it explicit where the command-line to execute starts, use --
# execute_process --allow_fail -- ls /not/existing
# @endcode
#
# Note that the output of the command is not redirected by this function.
# In order to execute the command quietly, use this function as follows:
# @code
# execute_process ls / &> /dev/null
# @endcode
# Or to store the command output in a variable including error messages
# use it as follows:
# @code
# output=`execute_process ls / 2>&1`
# @endcode
# Note that in this case, the option --allow_fail has no effect as the
# calling shell will never be terminated. Only the subshell in which the
# command is executed will be terminated. Checking the exit code $? is
# in this case required.
#
# @param [in] options Function options as documented below.
# @param [in] cmd     Executable of command to run or corresponding build
#                     target name. This is assumed to be the first
#                     non-option argument or the argument that follows the
#                     special '--' argument.
# @param [in] args    All remaining arguments are passed as arguments to
#                     the given command.
# @par Options:
# <table border="0">
#   <tr>
#     @tp @b --allow_fail @endtp
#     <td>Allows the command to fail. By default, if the command
#         returns a non-zero exit code, the exit() function is
#         called to terminate the current shell.</td>
#   </tr>
#   <tr>
#     @tp <b>--verbose, -v</b> @endtp
#     <td>Print command-line to stdout before execution.</td>
#   </tr>
#   <tr>
#     @tp @b --simulate @endtp
#     <td>If this option is given, the command is not actually
#         executed, but the command-line printed to stdout only.</td>
#   </tr>
# </table>
#
# @returns Exit code of subprocess.
function execute_process
{
    # parse arguments
    local allow_fail='false'
    local simulate='false'
    local verbose=0
    while [ $# -gt 0 ]; do
        case "$1" in
            --allow_fail)
                allow_fail='true'
                ;;
            --verbose|-v)
                ((verbose++))
                ;;
            --simulate)
                simulate='true'
                ;;
            --)
                shift
                break
                ;;
            *)
                break
                ;;
        esac
        shift
    done
    # command to execute and its arguments
    local command="$1"; shift
    [ -n "${command}" ] || return 1
    # map build target name to file
    local exec_path && get_executable_path exec_path "${command}"
    if [ -z "${exec_path}" ]; then
        echo "${command}: Either unknown build target or command not found" 1>&2
        exit 1
    fi
    # some verbose output
    if [ ${verbose} -gt 0 ]; then
        local argsstr && basis_array_to_quoted_string args "$@"
        echo "\$ ${exec_path} ${argsstr}"
    fi
    # execute command
    [ "X${simulate}" == "Xtrue" ] || {
        "${exec_path}" "$@"
    }
    local status=$?
    # if command failed, exit
    [ ${status} -eq 0 -o "X${allow_fail}" == "Xtrue" ] || {
        echo "Command ${exec_path} ${argsstr} failed" 1>&2
        exit 1
    }
    # return exit code
    return ${status}
}


## @}
# end of Doxygen group