#!/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.
# ------------------------------------------------------------------------------

# ------------------------------------------------------------------------------
# Display a backtrace
# Usage: backtrace
function 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
function error()
{
    local errcode=$?
    backtrace
    return $errcode
}

# ------------------------------------------------------------------------------
# Activate or deactivate error trapping to display backtrace
# Usage: settrace <--on|--off|--status>
settrace()
{
    local status="off"
    [[ $(trap -p ERR) ]] && status="on"
    #trap -p ERR

    local PARSED
    PARSED=$(getopt -oh --long help,on,off,status,force -- "$@")
    if [[ $? -ne 0 ]]; then
        disp E "Invalid options, use \"settrace --help\" to display usage."
        return 1
    fi
    eval set -- "$PARSED"
    local 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\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)
            if [[ ${status} == "on" ]] && [[ $force -eq 0 ]]; then
                disp E "ERR signal trap is already set. Use --force to replace it."
                return 1
            fi
            trap "error" ERR
            shift
            ;;
        --force)
            force=1
            shift
            ;;
        --off)
            if [[ ${status} != "on" ]]; then
                disp W "ERR signal trap is already unset!"
            fi
            trap - ERR
            shift
            ;;
        --status)
            disp i "Trap signal is ${status}."
            shift
            ;;
        --)
            shift
            break
            ;;
        *)
            disp E "Invalid options, use \"settrace --help\" to display usage."
            return 1
            ;; 
        esac
    done
    unset status force
}
export -f settrace
# ------------------------------------------------------------------------------


# EOF