stack

package
Version: v0.0.0-...-70f07a2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 6, 2016 License: Apache-2.0, MIT Imports: 8 Imported by: 0

README

GoDoc

stack

Package stack implements utilities to capture, manipulate, and format call stacks. It provides a simpler API than package runtime.

The implementation takes care of the minutia and special cases of interpreting the program counter (pc) values returned by runtime.Callers.

Versioning

Package stack publishes stable APIs via gopkg.in. The most recent is v1, which is imported like so:

import "gopkg.in/stack.v1"

Formatting

Package stack's types implement fmt.Formatter, which provides a simple and flexible way to declaratively configure formatting when used with logging or error tracking packages.

func DoTheThing() {
    c := stack.Caller(0)
    log.Print(c)          // "source.go:10"
    log.Printf("%+v", c)  // "pkg/path/source.go:10"
    log.Printf("%n", c)   // "DoTheThing"

    s := stack.Trace().TrimRuntime()
    log.Print(s)          // "[source.go:15 caller.go:42 main.go:14]"
}

See the docs for all of the supported formatting options.

Documentation

Overview

Package stack implements utilities to capture, manipulate, and format call stacks. It provides a simpler API than package runtime.

The implementation takes care of the minutia and special cases of interpreting the program counter (pc) values returned by runtime.Callers.

Package stack's types implement fmt.Formatter, which provides a simple and flexible way to declaratively configure formatting when used with logging or error tracking packages.

Example (CallFormat)
//go:build go1.2
// +build go1.2

package main

import (
	"fmt"

	"gopkg.in/stack.v1"
)

func main() {
	logCaller("%+s")
	logCaller("%v   %[1]n()")
}

func logCaller(format string) {
	fmt.Printf(format+"\n", stack.Caller(1))
}
Output:

gopkg.in/stack.v1/format_test.go
format_test.go:13   Example_callFormat()

Index

Examples

Constants

This section is empty.

Variables

View Source
var ErrNoFunc = errors.New("no call stack information")

ErrNoFunc means that the Call has a nil *runtime.Func. The most likely cause is a Call with the zero value.

Functions

This section is empty.

Types

type Call

type Call struct {
	// contains filtered or unexported fields
}

Call records a single function invocation from a goroutine stack.

func Caller

func Caller(skip int) Call

Caller returns a Call from the stack of the current goroutine. The argument skip is the number of stack frames to ascend, with 0 identifying the calling function.

func (Call) Format

func (c Call) Format(s fmt.State, verb rune)

Format implements fmt.Formatter with support for the following verbs.

%s    source file
%d    line number
%n    function name
%v    equivalent to %s:%d

It accepts the '+' and '#' flags for most of the verbs as follows.

%+s   path of source file relative to the compile time GOPATH
%#s   full path of source file
%+n   import path qualified function name
%+v   equivalent to %+s:%d
%#v   equivalent to %#s:%d

func (Call) MarshalText

func (c Call) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler. It formats the Call the same as fmt.Sprintf("%v", c).

func (Call) String

func (c Call) String() string

String implements fmt.Stinger. It is equivalent to fmt.Sprintf("%v", c).

type CallStack

type CallStack []Call

CallStack records a sequence of function invocations from a goroutine stack.

func Trace

func Trace() CallStack

Trace returns a CallStack for the current goroutine with element 0 identifying the calling function.

func (CallStack) Format

func (cs CallStack) Format(s fmt.State, verb rune)

Format implements fmt.Formatter by printing the CallStack as square brackes ([, ]) surrounding a space separated list of Calls each formatted with the supplied verb and options.

func (CallStack) MarshalText

func (cs CallStack) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler. It formats the CallStack the same as fmt.Sprintf("%v", cs).

func (CallStack) String

func (cs CallStack) String() string

String implements fmt.Stinger. It is equivalent to fmt.Sprintf("%v", cs).

func (CallStack) TrimAbove

func (cs CallStack) TrimAbove(c Call) CallStack

TrimAbove returns a slice of the CallStack with all entries above c removed.

func (CallStack) TrimBelow

func (cs CallStack) TrimBelow(c Call) CallStack

TrimBelow returns a slice of the CallStack with all entries below c removed.

func (CallStack) TrimRuntime

func (cs CallStack) TrimRuntime() CallStack

TrimRuntime returns a slice of the CallStack with the topmost entries from the go runtime removed. It considers any calls originating from unknown files, files under GOROOT, or _testmain.go as part of the runtime.

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL