// Package stackerr provides a lightweight library for panic recovery and error handling

// with customizable stack traces. It simplifies debugging by capturing clean, readable

// stack traces when panics occur or when errors are explicitly thrown.

package stackerr

import (

"bytes"

"fmt"

"io"

"os"

"runtime/debug"

"strings"

)

// Version is the current version of the library.

const Version = "v0.1.0"

// Configuration holds the configuration for the stackerr library.

type Configuration struct {

// StripSequences is a list of strings that, if found in a function name,

// will cause the function name to be truncated from that point.

// Default: []string{"(0", "({"}

StripSequences []string

// PathReplacements is a map of path prefixes to replace in the file path.

// Default: derived from GOPATH and GOROOT.

PathReplacements map[string]string

// MaxStackDepth is the maximum number of stack frames to include.

// Default: 10

MaxStackDepth int

// Output is the writer where panic recovery logs are written.

// If nil, no logging is done. Default: os.Stderr

Output io.Writer

}

// defaultStripSequences defines the default sequences to strip from function names.

var defaultStripSequences = []string{"(0", "({"}

// Config is the global configuration for the library.

// You can modify this variable directly to configure the library.

var Config = Configuration{

StripSequences: defaultStripSequences,

PathReplacements: GetDefaultPathReplacements(),

MaxStackDepth: 10,

Output: os.Stderr,

}

// callStackErr wraps an error with a stack trace.

type callStackErr struct {

Err error

Stack string

}

func (e callStackErr) Error() string {

return e.Err.Error()

}

func (e callStackErr) GetStack() string {

return e.Stack

}

func (e callStackErr) Unwrap() error {

return e.Err

}

// GetStack retrieves the stack trace from an error if it is a callStackErr.

// It returns an empty string if the error does not contain a stack trace.

func GetStack(err error) string {

if err == nil {

return ""

}

if cse, ok := err.(callStackErr); ok {

return cse.Stack

}

return ""

}

// formatStackTrace parses and cleans up the raw stack trace from debug.Stack().

func formatStackTrace(stack string) string {

lines := strings.Split(stack, "\n")

var frames []string

// Skip the first few lines which are usually the debug.Stack() call itself

for i := 1; i < len(lines)-1; i += 2 {

funcLine := strings.TrimSpace(lines[i])

fileLine := strings.TrimSpace(lines[i+1])

// Clean up function arguments to keep the output readable

for _, seq := range Config.StripSequences {

if idx := strings.Index(funcLine, seq); idx != -1 {

funcLine = funcLine[:idx]

break

}

}

parts := strings.SplitN(fileLine, ":", 2)

if len(parts) != 2 {

continue

}

filePath := strings.TrimSpace(parts[0])

lineInfo := strings.TrimSpace(parts[1])

lineParts := strings.Split(lineInfo, " ")

lineNumber := lineParts[0]

// Apply path replacements

for oldPath, newPath := range Config.PathReplacements {

if oldPath != "" && oldPath != newPath {

filePath = strings.Replace(filePath, oldPath, newPath, 1)

}

}

frame := fmt.Sprintf("File: %s:%s Func: %s", filePath, lineNumber, funcLine)

frames = append(frames, frame)

}

// Limit stack trace depth to avoid overly huge logs

depth := Config.MaxStackDepth

if depth <= 0 {

depth = 10 // Fallback safety

}

start := len(frames) - depth

if start < 0 {

start = 0

}

var buf bytes.Buffer

for i, frame := range frames[start:] {

buf.WriteString(frame)

if i < len(frames[start:])-1 {

buf.WriteString("\n")

}

}

return buf.String()

}

// Recover should be used in defer to handle panics and wrap errors with stack traces.

// Usage: defer stackerr.Recover(&err)

func Recover(err *error) {

// 1. Handle Panic

if r := recover(); r != nil {

var panicError error

var formattedStack string

// Check if it's already a callStackErr (from ThrowPanic)

if cse, ok := r.(callStackErr); ok {

panicError = cse.Err

formattedStack = cse.Stack

} else {

switch v := r.(type) {

case error:

panicError = v

case string:

panicError = fmt.Errorf("panic: %s", v)

default:

panicError = fmt.Errorf("panic: %v", v)

}

stack := string(debug.Stack())

formattedStack = formatStackTrace(stack)

}

// Assign the panic error to the return value

*err = callStackErr{

Err: panicError,

Stack: formattedStack,

}

// Logging

if Config.Output != nil {

fmt.Fprintf(Config.Output, "Recovered from panic: %v\nStack: %s\n", panicError, formattedStack)

}

return

}

// 2. Handle standard errors (wrap with stack if not already wrapped)

if err != nil && *err != nil {

if _, ok := (*err).(callStackErr); !ok {

stack := string(debug.Stack())

formattedStack := formatStackTrace(stack)

*err = callStackErr{

Err: *err,

Stack: formattedStack,

}

}

}

}

// ThrowPanic wraps an error with a stack trace and panics.

func ThrowPanic(err error) {

if err != nil {

message := err.Error()

stack := string(debug.Stack())

formattedStack := formatStackTrace(stack)

// Create the error first

wrappedErr := callStackErr{

Err: fmt.Errorf("%s", message),

Stack: formattedStack,

}

// Log and Panic

// If logging is desired before panic, we could do it here, but usually panic bubbles up to Recover.

// However, ThrowPanic explicitly panics with the wrapper.

panic(wrappedErr)

}

}

// GetDefaultPathReplacements initializes the default path replacements.

func GetDefaultPathReplacements() map[string]string {

replacements := map[string]string{}

if goroot := os.Getenv("GOROOT"); goroot != "" {

replacements[goroot] = "[GOROOT]"

}

if gopath := os.Getenv("GOPATH"); gopath != "" {

replacements[gopath+"/src/"] = "[Proj]"

replacements[gopath+"/pkg/"] = "[Lib]"

}

return replacements

}