#===  FUNCTION  ================================================================
#         NAME: read_value
#  DESCRIPTION: Read a value from STDIN and handle errors.
#   PARAMETERS: 1 - Prompt string for the read
#               2 - Name of variable to receive the result
#               3 - Default value (optional)
#      RETURNS: 1 on error, otherwise 0
#===============================================================================
read_value () {
    local prompt="${1:?Usage: read_value prompt outputname [default]}"
    local outputname="${2:?Usage: read_value prompt outputname [default]}"
    local default="${3:-}"
    local var

    #
    # Make an option for the 'read' if there's a default
    #
    if [[ -n $default ]]; then
        default="-i '$default'"
    fi

    #
    # Read and handle CTRL-D (EOF). Use 'eval' to deal with the argument being
    # a variable
    #
    eval "read -r -e $default -p '$prompt' var"
    res="$?"
    if [[ $res -ne 0 ]]; then
        echo "Read aborted"
        return 1
    fi

    #
    # Return the value in the nominated variable
    #
    eval "$outputname='$var'"
    return 0
}