github.com/haraldrudell/parl@v0.4.176/pruntime/code-location.go

/*
© 2021–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/)
ISC License
*/

package pruntime

import (
	"errors"
	"fmt"
	"path/filepath"
	"runtime"
	"strconv"

	"github.com/haraldrudell/parl/pruntime/pruntimelib"
)

const (
	// counts [pruntime.NewCodeLocation]
	newCodeLocationStackFrames = 1
)

// CodeLocation represents an executing code location, ie. a code line in source code
//   - CodeLocation is similar to the location in [runtime.Frame], but
//     contains only basic types string and int
type CodeLocation struct {
	// File is absolute path to the Go source file
	//	- “/opt/foxyboy/sw/privates/parl/mains/executable.go”
	//	- may be “<autogenerated>” for tests
	File string
	// Line is the line number in the source file, eg. 35
	Line int
	// FuncName is the fully qualified Go package path,
	// a possible value or pointer receiver struct name,
	// and the function name
	//	- “github.com/haraldrudell/parl/mains.(*Executable).AddErr”
	//	- anonymous functions have names like “func1”
	FuncName string
}

// NewCodeLocation gets data for a single stack frame
//   - for stackFramesToSkip 0, NewCodeLocation returns data for
//     its immediate caller
func NewCodeLocation(stackFramesToSkip int) (cl *CodeLocation) {
	if stackFramesToSkip < 0 {
		stackFramesToSkip = 0
	}
	var c = CodeLocation{}

	// obtain code-location ifnrormation using [runtime.Caller]
	var pc uintptr
	var ok bool
	// pc: opaque
	// file: basename.go
	// line: int 25
	if pc, c.File, c.Line, ok = runtime.Caller(newCodeLocationStackFrames + stackFramesToSkip); !ok {
		panic(errors.New("runtime.Caller failed"))
	}

	// obtain the fully qualified function name using [runtime.FuncForPC]
	// rFunc: runtime.Func is all opaque fields. methods:
	// Entry() (uintptr)
	// FileLine(uintptr) (line string, line int) "/opt/foxyboy/sw/privates/parl/mains/executable.go"
	// Name(): github.com/haraldrudell/parl/mains.(*Executable).AddErr
	if rFunc := runtime.FuncForPC(pc); rFunc != nil {
		c.FuncName = rFunc.Name()
	}

	return &c
}

// CodeLocationFromFunc returns a code location value from a
// non-nil [runtime.Func] value
//   - Func values are return by [runtime.FuncForPC]
func CodeLocationFromFunc(runtimeFunc *runtime.Func) (cl *CodeLocation) {
	cl = &CodeLocation{FuncName: runtimeFunc.Name()}
	cl.File, cl.Line = runtimeFunc.FileLine(runtimeFunc.Entry())
	return
}

// FuncName returns function name, characters no space:
// “AddErr”
func (cl *CodeLocation) Name() (funcName string) {
	_, _, _, funcName = pruntimelib.SplitAbsoluteFunctionName(cl.FuncName)
	return
}

// Package return base package name, a single word of characters with no space:
// “mains”
func (cl *CodeLocation) Package() (packageName string) {
	_, packageName, _, _ = pruntimelib.SplitAbsoluteFunctionName(cl.FuncName)
	return
}

// PackFunc return base package name and function
// “mains.AddErr”
func (cl *CodeLocation) PackFunc() (packageDotFunction string) {
	_, packageName, _, funcName := pruntimelib.SplitAbsoluteFunctionName(cl.FuncName)
	return packageName + "." + funcName
}

// FuncIdentifier return the function name identifier
// “AddErr”
//   - anonymous function like “SomeFunc.func1”
func (cl *CodeLocation) FuncIdentifier() (funcIdentifier string) {
	_, _, _, funcIdentifier = pruntimelib.SplitAbsoluteFunctionName(cl.FuncName)
	return
}

// Base returns base package name, an optional type name and the function name:
// “mains.(*Executable).AddErr”
func (cl *CodeLocation) Base() (baseName string) {
	return filepath.Base(cl.FuncName)
}

// FuncLine retuns the fully qualified function name and its line number:
// “github.com/haraldrudell/parl/mains.(*Executable).AddErr:43”
func (cl *CodeLocation) FuncLine() (funcLine string) {
	return cl.FuncName + ":" + strconv.Itoa(cl.Line)
}

// Short returns base package name, an optional type name and
// the function name, base filename and line number:
// “mains.(*Executable).AddErr-executable.go:25”
func (cl *CodeLocation) Short() (funcName string) {
	return fmt.Sprintf("%s()-%s:%d", filepath.Base(cl.FuncName), filepath.Base(cl.File), cl.Line)
}

// Long returns full package path, an optional type name and
// the function name, base filename and line number:
// “github.com/haraldrudell/parl/mains.(*Executable).AddErr-executable.go:25”
func (cl *CodeLocation) Long() (funcName string) {
	return fmt.Sprintf("%s-%s:%d", cl.FuncName, cl.File, cl.Line)
}

// IsSet returns true if this CodeLocation has a value, ie. is not zero-value
func (cl *CodeLocation) IsSet() (isSet bool) { return cl.File != "" || cl.FuncName != "" }

// Dump outputs all values quoted for debug purposes:
//   - File: "/opt/homebrew/Cellar/go/1.20.4/libexec/src/testing/testing.go"
//   - Line: 1576
//   - FuncName: "github.com/haraldrudell/parl/mains.(*Executable).AddErr"
func (cl *CodeLocation) Dump() (s string) {
	return fmt.Sprintf("File: %q Line: %d FuncName: %q", cl.File, cl.Line, cl.FuncName)
}

// String returns a two-line string representation suitable for a multi-line stack trace.
// Typical output:
//   - “github.com/haraldrudell/parl/error116.(*TypeName).FuncName␤
//     ␠␠/opt/sw/privates/parl/error116/codelocation_test.go:20”
//   - indentation is two spaces, not tab characters
func (cl CodeLocation) String() string {
	return fmt.Sprintf("%s\n\x20\x20%s:%d", cl.FuncName, cl.File, cl.Line)
}