utilities.sh

Go to the documentation of this file.

# ============================================================================
# Copyright (c) 2011-2012 University of Pennsylvania
# Copyright (c) 2013-2016 Andreas Schuh
# All rights reserved.
#
# See COPYING file for license information or visit
# https://cmake-basis.github.io/download.html#license
# ============================================================================

##############################################################################
# @file  utilities.sh
# @brief Main module of project-independent BASIS utilities.
#
# This module defines the default BASIS utility functions. These default
# implementations are not project-specific, i.e., do not make use of particular
# project attributes such as the name or version of the project. The utility
# functions defined by this module are intended for use in Bash scripts that
# are not build as part of a particular BASIS project. Otherwise, the
# project-specific implementations should be used instead, i.e., those defined
# by the basis.sh module of the project which is automatically added to the
# project during the configuration of the build tree. This basis.sh module and
# the submodules used by it are generated from template modules which are
# customized for the particular project that is being build.
#
# Besides the utility functions which are common to all implementations for
# the different programming languages, does this module further provide
# fundamental functions for the development in Bash.
#
# @note In Bash, there is no concept of namespaces. Hence, the utility functions
#       are all defined by the utilities.sh module which is part of the BASIS
#       installation. By simply setting the constants to the project specific
#       values, these utility functions are customized for this particular
#       package. This, however, also means that the BASIS utilities of two
#       different packages cannot be used within a Bash script at the same
#       time in general. The order in which the basis.sh modules are sourced
#       matters. Therefore, in Bash, care must be taken which modules of a
#       BASIS-based package are being sourced and whether these in turn
#       source either the utilities.sh module of BASIS or the basis.sh module
#       which has been configured/customized for this particular package.
#       If all modules make only use of the utilities.sh module, there are
#       no conflicts. Thus, Bash should in general only be used for executable
#       scripts within a project, but not to provide library functions to
#       other developers. Therefore, consider the use of C++, Python, or Perl,
#       instead.
#
# @ingroup BasisBashUtilities
##############################################################################

[ "${_BASIS_UTILITIES_INCLUDED}" == 'true' ] || {
_BASIS_UTILITIES_INCLUDED='true'


# ============================================================================
# constants
# ============================================================================

BASIS_UTILITIES_DIR="`cd -P -- "\`dirname -- "${BASH_SOURCE}"\`" && pwd`"
readonly BASIS_UTILITIES_DIR

# ============================================================================
# source other modules
# ============================================================================

. "${BASIS_UTILITIES_DIR}/core.sh"  || exit 1 # core utilities, i.e., import()

import basis.config  # constants
import basis.os.path # file path manipulation
import basis.shflags # command-line parsing library

# ============================================================================
# configuration
# ============================================================================

# the following contanst are set by the basis.sh module, if not, because
# this module is used in a script which does not belong to a BASIS-based
# project, they are initialized to project-independent defaults here

## @brief Project name.
[ -n "${PROJECT}" ] || readonly PROJECT=''
## @brief Project version.
[ -n "${VERSION}" ] || readonly VERSION=''
## @brief Major project version.
[ -n "${VERSION_MAJOR}" ] || VERSION_MAJOR=''
## @brief Minor project version.
[ -n "${VERSION_MINOR}" ] || VERSION_MINOR=''
## @brief Project patch number.
[ -n "${VERSION_PATCH}" ] || VERSION_PATCH=''
## @brief Project release.
[ -n "${RELEASE}" ] || readonly RELEASE=''
## @brief Default copyright of executables.
[ -n "${COPYRIGHT}" ] || readonly COPYRIGHT='2011-12 University of Pennsylvania, 2013-14 Carnegie Mellon University, 2013-16 Andreas Schuh'
## @brief Default license of executables.
[ -n "${LICENSE}" ] || readonly LICENSE='See https://cmake-basis.github.io/download.html#license or COPYING file.'
## @brief Default contact to use for help output of executables.
[ -n "${CONTACT}" ] || readonly CONTACT='andreas.schuh.84@gmail.com'


# common prefix of target UIDs belonging to this project
[ -n "${_BASIS_TARGET_UID_PREFIX}" ] || _BASIS_TARGET_UID_PREFIX=''
# used to make relative paths in executable target information map absolute
[ -n "${_BASIS_EXECUTABLE_TARGETS_BASE}" ] || _BASIS_EXECUTABLE_TARGETS_BASE="${BASIS_UTILITIES_DIR}"

# declare constants as readonly
readonly PROJECT
readonly VERSION
readonly VERSION_MAJOR
readonly VERSION_MINOR
readonly VERSION_PATCH
readonly RELEASE
readonly COPYRIGHT
readonly LICENSE
readonly CONTACT

readonly _BASIS_TARGET_UID_PREFIX
readonly _BASIS_EXECUTABLE_TARGETS_BASE


## @addtogroup BasisBashUtilities
#  @{


# ============================================================================
# executable information
# ============================================================================

# ----------------------------------------------------------------------------
## @brief Print contact information.
#
# @param [in] contact Name of contact. Defaults to <tt>${CONTACT}</tt>.
#
# @returns Nothing.
print_contact()
{
    [ -n "$1" ] && echo -e "Contact:\n  $1" || echo -e "Contact:\n  ${CONTACT}"
}

# ----------------------------------------------------------------------------
## @brief Print version information including copyright and license notices.
#
# Example:
# @code
# print_version 'foo' '1.0'
# print_version 'foo' -v '1.0'
# print_version -v 1.0 -p BarStool 'foo'
# print_version 'foo' -v '1.2' -c '2012 University of Pennsylvania' \
#                              -l 'Apache License, Version 2.0'
# @endcode
#
# @param [in] options   Function options as documented below.
# @param [in] name      Name of executable. Should not be set programmatically
#                       to the first argument of the main script, but a string
#                       literal instead.
# @param [in] version   Version of executable. Defaults to <tt>${RELEASE}</tt>
#                       if defined, otherwise this argument is required.
# @par Options:
# <table border="0">
#   <tr>
#     @tp @b -v, @b --version &lt;version&gt; @endtp
#     <td>Version of executable. Can be either given as option or second
#         positional argument after the @p name.</td>
#   </tr>
#   <tr>
#     @tp @b -p,  @b --project &lt;name&gt; @endtp
#     <td>Name of project this executable belongs to.
#         Defaults to <tt>${PROJECT}</tt> if defined.
#         If 'none', no project information is printed.</td>
#   </tr>
#   <tr>
#     @tp @b -c  @b --copyright &lt;copyright&gt; @endtp
#     <td>The copyright notice. Defaults to <tt>${COPYRIGHT}</tt>.
#         If 'none', no copyright notice is printed.</td>
#   </tr>
#   <tr>
#     @tp @b -l  @b --license &lt;license&gt; @endtp
#     <td>Information regarding licensing. Defaults to <tt>${LICENSE}</tt>.
#         If 'none', no license information is printed.</td>
#   </tr>
# </table>
#
# @returns Nothing.
print_version()
{
    local _basis_pv_name=''
    local _basis_pv_version="${RELEASE}"
    local _basis_pv_project="${PROJECT}"
    local _basis_pv_copyright="${COPYRIGHT:-}"
    local _basis_pv_license="${LICENSE:-}"
    while [ $# -gt 0 ]; do
        case "$1" in
            -v|--version)
                if [ -n "${_basis_pv_version}" ]; then
                    echo "print_version(): Version specified twice!" 1>&2
                    return 1
                fi
                if [ $# -gt 1 ]; then
                    _basis_pv_version="$2"
                else
                    echo "print_version(): Option -v, --version is missing an argument!" 1>&2
                    return 1
                fi
                shift
                ;;
            -p|--project)
                if [ $# -gt 1 ]; then
                    _basis_pv_project="$2"
                else
                    echo "print_version(): Option -p, --project is missing an argument!" 1>&2
                    return 1
                fi
                shift
                ;;
            -c|--copyright)
                if [ $# -gt 1 ]; then
                    _basis_pv_copyright="$2"
                else
                    echo "print_version(): Option -c, --copyright is missing an argument!" 1>&2
                    return 1
                fi
                shift
                ;;
            -l|--license)
                if [ $# -gt 1 ]; then
                    _basis_pv_license="$2"
                else
                    echo "print_version(): Option -l, --license is missing an argument!" 1>&2
                    return 1
                fi
                shift
                ;;
            *)
                if   [ -z "${_basis_pv_name}" ]; then
                    _basis_pv_name=$1
                elif [ -z "${_basis_pv_version}" ]; then
                    _basis_pv_version=$1
                else
                    echo "print_version(): Too many arguments or invalid option: $1" 1>&2
                    return 1
                fi
                ;;
        esac
        shift
    done
    [ -n "${_basis_pv_name}"    ] || { echo "print_version(): Missing name argument"    1>&2; return 1; }
    [ -n "${_basis_pv_version}" ] || { echo "print_version(): Missing version argument" 1>&2; return 1; }
    echo -n "${_basis_pv_name}"
    [ -n "${_basis_pv_project}" ] && [ "${_basis_pv_project}" != 'none' ] && {
        echo -n " (${_basis_pv_project})"
    }
    echo " ${_basis_pv_version}"
    [ -n "${_basis_pv_copyright}" ] && [ "${_basis_pv_copyright}" != 'none' ] && {
        echo -e "Copyright (c) ${_basis_pv_copyright}. All rights reserved."
    }
    [ -n "${_basis_pv_license}"   ] && [ "${_basis_pv_license}"   != 'none' ] && {
        echo -e "${_basis_pv_license}"
    }
}

# ----------------------------------------------------------------------------
## @brief Get UID of build target.
#
# The UID of a build target is its name prepended by a namespace identifier
# which should be unique for each project.
#
# This function further initializes the dictionary storing the information
# about the executable targets upon the first invocation. Reason to do it
# here is that every access to the dictionaries first calls this function
# to get the UID of a build target. Moreover, also this function needs to
# have the already initialized dictionaries to ensure that an already valid
# target identifier is not modified. As Bash does not provide hash tables,
# dictionary data structures, the imitation of these is necessary which,
# however, results in many eval() calls with noticeable impact on running time.
# Therefore, to decrease the time required to source the BASIS utilities,
# the required dictionary structure is initialized only upon first use.
#
# @param [out] uid  UID of named build target.
# @param [in]  name Name of build target.
#
# @returns Nothing.
#
# @retval 0 On success.
# @retval 1 On failure.
targetuid()
{
    [ -n "$1" ] && [ $# -eq 2 ] || return 1
    local _basis_targetuid_target="$2"
    # initialize module if not done yet - this is only done here because
    # whenever information is looked up about an executable target, this
    # function is invoked first
    if [ "${_BASIS_EXECUTABLETARGETINFO_INITIALIZED}" != 'true' ]; then
        _basis_executabletargetinfo_initialize || return 1
    fi
    # empty string as input remains unchanged
    [ -z "${_basis_targetuid_target}" ] && local "$1" && upvar $1 '' && return 0
    # in case of a leading namespace separator, do not modify target name
    [ "${_basis_targetuid_target:0:1}" == '.' ] && local "$1" && upvar $1 "${_basis_targetuid_target}" && return 0
    # project namespace
    local _basis_targetuid_prefix="${_BASIS_TARGET_UID_PREFIX}.DUMMY"
    # try prepending namespace or parts of it until target is known
    local _basis_targetuid_path=''
    while [ "${_basis_targetuid_prefix/\.*/}" != "${_basis_targetuid_prefix}" ]; do
        _basis_targetuid_prefix="${_basis_targetuid_prefix%\.*}"
        _basis_executabletargetinfo_get _basis_targetuid_path "${_basis_targetuid_prefix}.${_basis_targetuid_target}" LOCATION
        if [ -n "${_basis_targetuid_path}" ]; then
            local "$1" && upvar $1 "${_basis_targetuid_prefix}.${_basis_targetuid_target}"
            return 0
        fi
    done
    # otherwise, return target name unchanged
    local "$1" && upvar $1 "${_basis_targetuid_target}"
}

# ----------------------------------------------------------------------------
## @brief Determine whether a given build target is known.
#
# @param [in] target Name of build target.
#
# @returns Whether the named target is a known executable target.
istarget()
{
    local _basis_istarget_uid && targetuid _basis_istarget_uid "$1"
    [ -n "${_basis_istarget_uid}" ] || return 1
    local _basis_istarget_path && _basis_executabletargetinfo_get _basis_istarget_path "${_basis_istarget_uid}" LOCATION
    [ -n "${_basis_istarget_path}" ]
}

# ----------------------------------------------------------------------------
## @brief Get absolute path of executable file.
#
# This function determines the absolute file path of an executable. If no
# arguments are given, the absolute path of this executable is returned.
# If the given argument is a known build target name, the absolute path
# of the executable built by this target is returned. Otherwise, the named
# command is searched in the system PATH and it's absolute path returned
# if found. If the given argument is neither the name of a known build target
# nor an executable found on the PATH, an empty string is returned and
# the return value is 1.
#
# @param [out] path   Absolute path of executable file.
# @param [in]  target Name/UID of build target. If no argument is given,
#                     the file path of the calling executable is returned.
#
# @returns Nothing.
#
# @retval 0 On success.
# @retval 1 On failure.
exepath()
{
    [ -n "$1" ] && [ $# -eq 1 -o $# -eq 2 ] || return 1
    local _basis_exepath_path=''
    # if no target name given, get path of this executable
    if [ -z "$2" ]; then
        _basis_exepath_path="`realpath "$0"`"
    # otherwise, get path of executable built by named target
    else
        # get UID of target
        local _basis_exepath_uid && targetuid _basis_exepath_uid "$2"
        [ "${_basis_exepath_uid:0:1}" == '.' ] && _basis_exepath_uid=${_basis_exepath_uid:1}
        if [ -n "${_basis_exepath_uid}" ]; then
            # get path relative to this module
            _basis_executabletargetinfo_get _basis_exepath_path "${_basis_exepath_uid}" LOCATION
            if [ -n "${_basis_exepath_path}" ]; then
                # replace IntDir when binary built from C++ with Xcode
                if [[ ${_basis_exepath_path/\$<CONFIG>} != ${_basis_exepath_path} ]]; then
                    local _basis_exepath_tmp='' 
                    local _basis_exepath_cfg=''
                    for _basis_exepath_cfg in 'Release' 'Debug' 'RelWithDebInfo' 'MinSizeRel'; do
                        _basis_exepath_tmp=${_basis_exepath_path/\$<CONFIG>/$_basis_exepath_cfg}
                        if [ -f "${_basis_exepath_tmp}" ]; then
                            _basis_exepath_path="${_basis_exepath_tmp}"
                            break
                        fi
                    done
                    _basis_exepath_path=${_basis_exepath_path/\$<CONFIG>}
                fi
                # make path absolute
                _basis_exepath_path=`abspath "${_BASIS_EXECUTABLE_TARGETS_BASE}" "${_basis_exepath_path}"`
                [ $? -eq 0 ] || return 1
            else
                _basis_exepath_path=`/usr/bin/which "$2" 2> /dev/null`
            fi
        else
            _basis_exepath_path=`/usr/bin/which "$2" 2> /dev/null`
        fi
    fi
    # return path
    local "$1" && upvar $1 "${_basis_exepath_path}"
    [ $? -eq 0 ] && [ -n "${_basis_exepath_path}" ]
}

# ----------------------------------------------------------------------------
## @brief Get name of executable file.
#
# @param [out] file Name of executable file or an empty string if not found.
#                   If @p name is not given, the name of this executable is returned.
# @param [in]  name Name of command or an empty string.
#
# @returns Whether or not the command was found.
#
# @retval 0 On success.
# @retval 1 On failure.
exename()
{
    [ -n "$1" ] && [ $# -eq 1 -o $# -eq 2 ] || return 1
    local _basis_exename_path && exepath _basis_exename_path "$2"
    [ $? -eq 0 ] || return 1
    local _basis_exename_name="`basename "${_basis_exename_path}"`"
    local "$1" && upvar $1 "${_basis_exename_name}"
}

# ----------------------------------------------------------------------------
## @brief Get directory of executable file.
#
# @param [out] dir  Directory of executable file or an empty string if not found.
#                   If @p name is not given, the directory of this executable is returned.
# @param [in]  name Name of command or an empty string.
#
# @returns Whether or not the command was found.
#
# @retval 0 On success.
# @retval 1 On failure.
exedir()
{
    [ -n "$1" ] && [ $# -eq 1 -o $# -eq 2 ] || return 1
    local _basis_exedir_path && exepath _basis_exedir_path "$2"
    [ $? -eq 0 ] || return 1
    local _basis_exedir_dir="`dirname "${_basis_exedir_path}"`"
    local "$1" && upvar $1 "${_basis_exedir_dir}"
}

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

# ----------------------------------------------------------------------------
## @brief Build quoted string from array.
#
# Example:
# @code
# tostring str 'this' "isn't" a 'simple example of "a quoted"' 'string'
# echo "${str}"
# @endcode
#
# @param [out] var      Name of result variable for quoted string.
# @param [in]  elements All remaining arguments are considered to be the
#                       elements of the array to convert.
#
# @returns Nothing.
tostring()
{
    local _basis_tostring_str=''
    local _basis_tostring_element=''
    # GNU bash, version 3.00.15(1)-release (x86_64-redhat-linux-gnu)
    # turns the array into a single string value if local is used
    if [ ${BASH_VERSION_MAJOR} -gt 3 ] || [ ${BASH_VERSION_MAJOR} -eq 3 -a ${BASH_VERSION_MINOR} -gt 0 ]; then
        local _basis_tostring_args=("$@")
    else
        _basis_tostring_args=("$@")
    fi
    local _basis_tostring_i=1 # first argument is name of return variable
    while [ $_basis_tostring_i -lt ${#_basis_tostring_args[@]} ]; do
        _basis_tostring_element="${_basis_tostring_args[$_basis_tostring_i]}"
        # escape double quotes
        _basis_tostring_element=`printf -- "${_basis_tostring_element}" | sed 's/\\"/\\\\"/g'`
        # surround element by double quotes if necessary
        match "${_basis_tostring_element}" "[' ]|^$" && _basis_tostring_element="\"${_basis_tostring_element}\""
        # append element
        [ -n "${_basis_tostring_str}" ] && _basis_tostring_str="${_basis_tostring_str} "
        _basis_tostring_str="${_basis_tostring_str}${_basis_tostring_element}"
        # next argument
        let _basis_tostring_i++
    done
    local "$1" && upvar $1 "${_basis_tostring_str}"
}

# ----------------------------------------------------------------------------
## @brief Split (quoted) string.
#
# This function can be used to split a (quoted) string into its elements.
#
# Example:
# @code
# str="'this' 'isn\'t' a \"simple example of \\\"a quoted\\\"\" 'string'"
# qsplit array "${str}"
# echo ${#array[@]}  # 5
# echo "${array[3]}" # simple example of "a quoted"
# @endcode
#
# @param [out] var Result variable for array.
# @param [in]  str Quoted string.
#
# @returns Nothing.
qsplit()
{
    [ $# -eq 2 ] || return 1
    # GNU bash, version 3.00.15(1)-release (x86_64-redhat-linux-gnu)
    # turns the array into a single string value if local is used
    if [ ${BASH_VERSION_MAJOR} -gt 3 ] || [ ${BASH_VERSION_MAJOR} -eq 3 -a ${BASH_VERSION_MINOR} -gt 0 ]; then
        local _basis_qsplit_array=()
    else
        _basis_qsplit_array=()
    fi
    local _basis_qsplit_str=$2
    # match arguments from left to right
    while match "${_basis_qsplit_str}" "[ ]*('([^']|\\\')*[^\\]'|\"([^\"]|\\\")*[^\\]\"|[^ ]+)(.*)"; do
        # matched element including quotes
        _basis_qsplit_element="${BASH_REMATCH[1]}"
        # remove quotes
        if [[ ${_basis_qsplit_element:0:1} == '"' && ${_basis_qsplit_element: -1} == '"' ]]; then
            _basis_qsplit_element="${_basis_qsplit_element:1}"
            _basis_qsplit_element="${_basis_qsplit_element%\"}"
        elif [[ ${_basis_qsplit_element:0:1} == "'" && ${_basis_qsplit_element: -1} == "'" ]]; then
            _basis_qsplit_element="${_basis_qsplit_element:1}"
            _basis_qsplit_element="${_basis_qsplit_element%\'}"
        fi
        # replace quoted quotes within argument by quotes
        _basis_qsplit_element=`printf -- "${_basis_qsplit_element}" | sed "s/[\\]'/'/g;s/[\\]\"/\"/g"`
        # add to resulting array
        _basis_qsplit_array[${#_basis_qsplit_array[@]}]="${_basis_qsplit_element}"
        # continue with residual command-line
        _basis_qsplit_str="${BASH_REMATCH[4]}"
    done
    # return
    local "$1" && upvar $1 "${_basis_qsplit_array[@]}"
}

# ----------------------------------------------------------------------------
## @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 ls /not/existing
# # to prevent this, provide the --allow_fail option
# execute --allow_fail ls /not/existing
# # to make it explicit where the command-line to execute starts, use --
# execute --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 ls / &> /dev/null
# @endcode
# Or to store the command output in a variable including error messages
# use it as follows:
# @code
# output=`execute 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>-f, --allow_fail</b> @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>-v, --verbose</b> [int] @endtp
#     <td>Print command-line to stdout before execution. Optionally, as it is
#         sometimes more convenient to pass in the value of another variable
#         which controls the verbosity of the parent process itself, a verbosity
#         value can be specified following the option flag. If this verbosity
#         less or equal to zero, the command-line of the subprocess is not
#         printed to stdout, otherwise it is.</td>
#   </tr>
#   <tr>
#     @tp <b>-s, --simulate</b> @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.
execute()
{
    # parse arguments
    local _basis_execute_allow_fail='false'
    local _basis_execute_simulate='false'
    local _basis_execute_verbose=0
    local _basis_execute_args=''
    while [ $# -gt 0 ]; do
        case "$1" in
            -f|--allow_fail) _basis_execute_allow_fail='true'; ;;
            -s|--simulate)   _basis_execute_simulate='true';   ;;
            -v|--verbose)
                match "$2" '^-?[0-9]+$'
                if [ $? -eq 0 ]; then
                    _basis_execute_verbose=$2
                    shift
                else
                    let _basis_execute_verbose++
                fi
                ;;
            --)              shift; break; ;;
            *)               break; ;;
        esac
        shift
    done
    # command to execute and its arguments
    local _basis_execute_command="$1"; shift
    [ -n "${_basis_execute_command}" ] || { echo "execute_process(): No command specified to execute" 1>&2; return 1; }
    # get absolute path of executable
    local _basis_execute_exec && exepath _basis_execute_exec "${_basis_execute_command}"
    [ -n "${_basis_execute_exec}" ] || { echo "${_basis_execute_command}: Command not found" 1>&2; exit 1; }
    # some verbose output
    if [ ${_basis_execute_verbose} -gt 0 ] || [ "${_basis_execute_simulate}" == 'true' ]; then
        tostring _basis_execute_args "$@"
        echo "\$ ${_basis_execute_exec} ${_basis_execute_args}"
    fi
    # execute command
    [ "${_basis_execute_simulate}" == 'true' ] || "${_basis_execute_exec}" "$@"
    local _basis_execute_status=$?
    # if command failed, exit
    [ ${_basis_execute_status} -eq 0 -o "${_basis_execute_allow_fail}" == 'true' ] || {
        [ -n "${_basis_execute_args}" ] || tostring _basis_execute_args "$@"
        echo
        echo "Command ${_basis_execute_exec} ${_basis_execute_args} failed" 1>&2
        exit 1
    }
    # return exit code
    return ${_basis_execute_status}
}


## @}
# end of Doxygen group

# ============================================================================
# private
# ============================================================================

# ----------------------------------------------------------------------------
# @brief Sanitize string for use in variable name.
#
# @param [out] out Sanitized string.
# @param [in]  str String to be sanitized.
#
# @returns Nothing.
#
# @retval 0 On success.
# @retval 1 On failure.
_basis_executabletargetinfo_sanitize()
{
    [ $# -eq 2 ] || return 1
    [ -n "$2" ] || {
        upvar $1 ''
        return 0
    }
    local sane="`printf -- "$2" | tr '[:space:]' '_' | tr -c '[:alnum:]' '_'`"
    [ -n "${sane}" ] || {
        echo "_basis_executabletargetinfo_sanitize(): Failed to sanitize string '$2'" 1>&2
        exit 1
    }
    local "$1" && upvar $1 "${sane}"
}

# ----------------------------------------------------------------------------
# @brief Add (key, value) pair to executable target info "hash".
#
# @param [in] key   Hash key.
# @param [in] name  Name of the hash table.
# @param [in] value Value associated with the given hash key.
#
# @returns Sets a readonly variable that represents the (key, value) entry.
#
# @sa _basis_executabletargetinfo_get()
_basis_executabletargetinfo_add()
{
    [ $# -eq 3 ] || return 1

    local key  && _basis_executabletargetinfo_sanitize key  "$1"
    local name && _basis_executabletargetinfo_sanitize name "$2"
    [ -n "${key}" ] && [ -n "${name}" ] || {
        if [ -z "${key}" ] && [ -z "${name}" ]; then
            echo "_basis_executabletargetinfo_add(): Neither lookup table nor key specified" 1>&2
        elif [ -z "${key}" ]; then
            echo "_basis_executabletargetinfo_add(): No key specified for addition to hash table '${name}'" 1>&2
        else
            echo "_basis_executabletargetinfo_add(): No lookup table given for addition of key '${key}'" 1>&2
        fi
        exit 1
    }
    eval "readonly __BASIS_EXECUTABLETARGETINFO_${name}_${key}='$3'"
    if [ $? -ne 0 ]; then
        echo "Failed to add ${name} of key ${key} to executable target info map!" 1>&2
        echo "This may be caused by two CMake build target names being converted to the same key." 1>&2
        exit 1
    fi
}

# ----------------------------------------------------------------------------
# @brief Get value from executable target info "hash".
#
# @param [out] value Value corresponding to given @p key
#                    or an empty string if key is unknown.
# @param [in]  key   Hash key.
# @param [in]  name  Name of the hash table.
#
# @returns Nothing.
#
# @retval 0 On success.
# @retval 1 On failure.
#
# @sa _basis_executabletargetinfo_add()
_basis_executabletargetinfo_get()
{
    [ $# -eq 3 ] || return 1

    local key  && _basis_executabletargetinfo_sanitize key  "$2"
    local name && _basis_executabletargetinfo_sanitize name "$3"
    [ -n "${key}" ] && [ -n "${name}" ] || {
        if [ -z "${key}" ] && [ -z "${name}" ]; then
            echo "_basis_executabletargetinfo_get(): Neither lookup table nor key specified" 1>&2
        elif [ -z "${key}" ]; then
            echo "_basis_executabletargetinfo_get(): No key specified for lookup in hash table '${name}'" 1>&2
        else
            echo "_basis_executabletargetinfo_get(): No lookup table given for lookup of key '${key}'" 1>&2
        fi
        exit 1
    }
    eval "local value=\${__BASIS_EXECUTABLETARGETINFO_${name}_${key}}"

    local "$1" && upvar $1 "${value}"
}

# initialize table of executable target information upon first use
# this function is redefined by the basis.sh module, see targetuid()
_basis_executabletargetinfo_initialize()
{
    [ $# -eq 0 ] || return 1
    _BASIS_EXECUTABLETARGETINFO_INITIALIZED='true'
    return 0
}


} # _BASIS_UTILITIES_INCLUDED