serrors

README

serrors

A Go library to create errors with stack traces.

Requirements

• Go 1.24+

Installation

go get github.com/Siroshun09/serrors

Usage

Creating errors

• With message: serrors.New("msg")
• With format and args: serrors.Errorf("msg: %s", "hello")
• Wrap an existing error: serrors.WithStackTrace(err)
  • If err is nil, it returns nil.
  • If err already has a stack trace from this package, it returns err as-is.

Getting stack traces

• serrors.GetStackTrace(err) returns a stack trace for err.
  • If err already has a stack trace attached (created by this package), it returns that.
  • Otherwise, it returns the current call site's stack trace.
  • If err is nil, it returns nil.
• serrors.GetAttachedStackTrace(err) returns the attached stack trace and a bool.
  • The bool indicates whether err had an attached stack trace.
• serrors.GetCurrentStackTrace() returns the current StackTrace.

Example

package main

import (
    "errors"
    "fmt"

    "github.com/Siroshun09/serrors"
)

func main() {
    base := errors.New("base error")

    // Wrap with stack trace
    err := serrors.WithStackTrace(base)

    // Retrieve the attached stack trace
    st, ok := serrors.GetAttachedStackTrace(err)
    if ok {
        fmt.Println("stack trace attached:")
        fmt.Println(st.String())
    }

    // Or always get a stack trace (attached or current)
    fmt.Println(serrors.GetStackTrace(err))
}

Interoperability

• The wrapped error implements Unwrap() error, so it works with errors.Is and errors.As.
• fmt.Errorf("...: %w", err) can be used in combination with these errors as usual.

License

This project is under the Apache License version 2.0. Please see LICENSE for more info.

Copyright © 2024-2025, Siroshun09

Documentation

Index

• func Errorf(format string, args ...any) error
• func GetStackTraces(err error) iter.Seq2[error, StackTrace]
• func New(msg string) error
• func WithStackTrace(err error) error
• type FuncInfo
  • func (s FuncInfo) String() string
• type StackTrace
  • func GetAttachedStackTrace(err error) (StackTrace, bool)
  • func GetCurrentStackTrace() StackTrace
  • func GetStackTrace(err error) StackTrace
  • func (s StackTrace) String() string

Functions

func Errorf

func Errorf(format string, args ...any) error

Errorf creates an error with a StackTrace.

func GetStackTraces

func GetStackTraces(err error) iter.Seq2[error, StackTrace]

GetStackTraces returns a sequence of errors and their associated StackTrace.

This function recursively returns errors and stack traces by repeating the following process:

1. If the given error has a StackTrace itself, this function returns the wrapped error and its StackTrace

• In this case, the iterator returns only one error.

2. If the given error has an Unwrap() error function, this function calls it and tries to process step 1 again 3. If the given error has an Unwrap() []error function, this function calls it and tries to process step 1 for each error in the returned slice

func New

func New(msg string) error

New creates an error with a StackTrace.

func WithStackTrace

func WithStackTrace(err error) error

WithStackTrace creates an error with a StackTrace.

If err already has a StackTrace, this function returns err as-is.

Also, if err is nil, this function returns nil.

Types

type FuncInfo

type FuncInfo struct {
	// Name is the name of the function.
	Name string
	// File is the source file where the function is defined.
	File string
	// Line is the line number in that file.
	Line int
}

FuncInfo contains values obtained from runtime.Func.

func (FuncInfo) String

func (s FuncInfo) String() string

String formats FuncInfo as "name (file:line)"

type StackTrace

type StackTrace []FuncInfo

StackTrace is an array of FuncInfo.

func GetAttachedStackTrace

func GetAttachedStackTrace(err error) (StackTrace, bool)

GetAttachedStackTrace returns the StackTrace if the given error has one.

The returned bool indicates whether the given error has a StackTrace.

func GetCurrentStackTrace

func GetCurrentStackTrace() StackTrace

GetCurrentStackTrace returns the current StackTrace.

func GetStackTrace

func GetStackTrace(err error) StackTrace

GetStackTrace returns a StackTrace for err.

If err does not have a StackTrace, this function creates the current StackTrace.

Also, if err is nil, this function returns nil.

func (StackTrace) String

func (s StackTrace) String() string

String formats StackTrace using FuncInfo.String.