README

![GoDoc](https://godoc.org/gopkg.in/stack.v0 ?status.svg) Build Status

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 v0 (the API is still baking, please file an issue if you have any suggestions), which is imported like so:

import "gopkg.in/stack.v0"

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)          // might log "source.go:10"
    log.Printf("%+v", c)  // might log "pkg/path/source.go:10"
    log.Printf("%n", c)   // might log "DoTheThing"

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

See the docs for all of the supported formatting options.

Expand ▾ Collapse ▴

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)
    Output:
    
    gopkg.in/stack.v0/format_test.go
    format_test.go:13   Example_callFormat()
    

    Index

    Examples

    Constants

    This section is empty.

    Variables

    This section is empty.

    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
          

          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) 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 or files under GOROOT as part of the runtime.