#!/usr/bin/env bash
# ------------------------------------------------------------------------------
# Copyright (c) 2013-2026 Geoffray Levasseur <fatalerrors@geoffray-levasseur.org>
# Protected by the BSD3 license. Please read bellow for details.
#
# * Redistribution and use in source and binary forms,
# * with or without modification, are permitted provided
# * that the following conditions are met:
# *
# *   Redistributions of source code must retain the above
# *   copyright notice, this list of conditions and the
# *   following disclaimer.
# *
# *   Redistributions in binary form must reproduce the above
# *   copyright notice, this list of conditions and the following
# *   disclaimer in the documentation and/or other materials
# *   provided with the distribution.
# *
# *   Neither the name of the copyright holder nor the names
# *   of any other contributors may be used to endorse or
# *   promote products derived from this software without
# *   specific prior written permission.
# *
# * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
# * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
# * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
# * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
# * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
# * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
# * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
# * OF SUCH DAMAGE.
# ------------------------------------------------------------------------------

load_conf "debug"

# ------------------------------------------------------------------------------
# Display a backtrace
# Usage: backtrace
backtrace()
{
    printf "========= Call stack =========\n"
    local i=1 # We begin at 1 to ignore backtrace itself
    while [[ $i -lt ${#FUNCNAME[@]} ]]; do
        printf '%15s() %s:%d\n' \
            "${FUNCNAME[$i]}" "${BASH_SOURCE[$i]}" "${BASH_LINENO[$(( i-1 ))]}"
        ((i++))
    done
    unset i
    printf "==============================\n"
}

# ------------------------------------------------------------------------------
# Function to be trapped for errors investigation
error()
{
    local errcode=$?
    backtrace
    return $errcode
}

# ------------------------------------------------------------------------------
# Activate or deactivate error trapping to display backtrace
# Usage: settrace <--on|--off|--status>
settrace()
{
    local PARSED
    PARSED=$(getopt -oh --long help,on,off,status,force -- "$@")
    # shellcheck disable=SC2181 # getopt return code is checked immediately after
    if [[ $? -ne 0 ]]; then
        disp E "Invalid options, use \"settrace --help\" to display usage."
        return 1
    fi
    local -a _pargs=()
    readarray -td '' _pargs < <(printf '%s' "$PARSED" | xargs printf '%s\0')
    set -- "${_pargs[@]}"

    # First pass: gather the requested action and flags. --on, --off and
    # --status are mutually exclusive; --force only modifies --on.
    local action="" force=0
    while true; do
        case $1 in
        -h|--help)
            printf "Try to activate backtrace display for script debugging.\n\n"
            printf "Options:\n"
            printf "\t--on\t\tActivate backtrace generation\n"
            printf "\t--force\t\tForce replacement of existing trap (use with --on)\n"
            printf "\t--off\t\tDeactivate backtrace generation\n"
            printf "\t--status\tDisplay whether the ERR trap is set\n\n"
            printf "That function active a trap event on error. If the script you want to\n"
            printf "debug overload the ERR bash trap, it will not work.\n"
            return 0
            ;;
        --on|--off|--status)
            if [[ -n $action ]]; then
                disp E "The --on, --off and --status options are mutually exclusive."
                return 1
            fi
            action="${1#--}"
            shift
            ;;
        --force)
            force=1
            shift
            ;;
        --)
            shift
            break
            ;;
        *)
            disp E "Invalid options, use \"settrace --help\" to display usage."
            return 1
            ;;
        esac
    done

    # Second pass: evaluate the current trap state, then apply the action.
    local status="off"
    [[ -n $(trap -p ERR) ]] && status="on"

    case $action in
    on)
        if [[ $status == "on" && $force -eq 0 ]]; then
            disp E "ERR signal trap is already set. Use --force to replace it."
            return 1
        fi
        set -o errtrace
        trap "error" ERR
        ;;
    off)
        [[ $status != "on" ]] && disp W "ERR signal trap is already unset!"
        trap - ERR
        set +o errtrace
        ;;
    status)
        disp I "Trap signal on error is ${status}."
        ;;
    "")
        disp E "No action specified, use \"settrace --help\" to display usage."
        return 1
        ;;
    esac
}
export -f settrace
# ------------------------------------------------------------------------------


# EOF