Package spew

* Pointers are dereferenced and followed
* Circular data structures are detected and handled properly
* Custom Stringer/error interfaces are optionally invoked, including
  on unexported types
* Custom types which only implement the Stringer/error interfaces via
  a pointer receiver are optionally invoked when passing non-pointer
  variables
* Byte arrays and slices are dumped like the hexdump -C command which
  includes offsets, byte values in hex, and ASCII output (only when using
  Dump style)

* Dump style which prints with newlines, customizable indentation,
  and additional debug information such as types and all pointer addresses
  used to indirect to the final value
* A custom Formatter interface that integrates cleanly with the standard fmt
  package and replaces %v, %+v, %#v, and %#+v to provide inline printing
  similar to the default %v while providing the additional functionality
  outlined above and passing unsupported format verbs such as %x and %q
  along to fmt

spew.Dump(myVar1, myVar2, ...)
spew.Fdump(someWriter, myVar1, myVar2, ...)
str := spew.Sdump(myVar1, myVar2, ...)

spew.Printf("myVar1: %v -- myVar2: %+v", myVar1, myVar2)
spew.Printf("myVar3: %#v -- myVar4: %#+v", myVar3, myVar4)
spew.Fprintf(someWriter, "myVar1: %v -- myVar2: %+v", myVar1, myVar2)
spew.Fprintf(someWriter, "myVar3: %#v -- myVar4: %#+v", myVar3, myVar4)

* Indent
	String to use for each indentation level for Dump functions.
	It is a single space by default.  A popular alternative is "\t".

* MaxDepth
	Maximum number of levels to descend into nested data structures.
	There is no limit by default.

* DisableMethods
	Disables invocation of error and Stringer interface methods.
	Method invocation is enabled by default.

* DisablePointerMethods
	Disables invocation of error and Stringer interface methods on types
	which only accept pointer receivers from non-pointer variables.
	Pointer method invocation is enabled by default.

* DisablePointerAddresses
	DisablePointerAddresses specifies whether to disable the printing of
	pointer addresses. This is useful when diffing data structures in tests.

* DisableCapacities
	DisableCapacities specifies whether to disable the printing of
	capacities for arrays, slices, maps and channels. This is useful when
	diffing data structures in tests.

* ContinueOnMethod
	Enables recursion into types after invoking error and Stringer interface
	methods. Recursion after method invocation is disabled by default.

* SortKeys
	Specifies map keys should be sorted before being printed. Use
	this to have a more deterministic, diffable output.  Note that
	only native types (bool, int, uint, floats, uintptr and string)
	and types which implement error or Stringer interfaces are
	supported with other types sorted according to the
	reflect.Value.String() output which guarantees display
	stability.  Natural map order is used by default.

* SpewKeys
	Specifies that, as a last resort attempt, map keys should be
	spewed to strings and sorted by those strings.  This is only
	considered if SortKeys is true.

spew.Dump(myVar1, myVar2, ...)

spew.Fdump(os.Stderr, myVar1, myVar2, ...)

str := spew.Sdump(myVar1, myVar2, ...)

(main.Foo) {
 unexportedField: (*main.Bar)(0xf84002e210)({
  flag: (main.Flag) flagTwo,
  data: (uintptr) <nil>
 }),
 ExportedField: (map[interface {}]interface {}) (len=1) {
  (string) (len=3) "one": (bool) true
 }
}

([]uint8) (len=32 cap=32) {
 00000000  11 12 13 14 15 16 17 18  19 1a 1b 1c 1d 1e 1f 20  |............... |
 00000010  21 22 23 24 25 26 27 28  29 2a 2b 2c 2d 2e 2f 30  |!"#$%&'()*+,-./0|
 00000020  31 32                                             |12|
}

spew.Printf("myVar1: %v -- myVar2: %+v", myVar1, myVar2)
spew.Printf("myVar3: %#v -- myVar4: %#+v", myVar3, myVar4)
spew.Println(myVar, myVar2)
spew.Fprintf(os.Stderr, "myVar1: %v -- myVar2: %+v", myVar1, myVar2)
spew.Fprintf(os.Stderr, "myVar3: %#v -- myVar4: %#+v", myVar3, myVar4)

  %v: <**>5
 %+v: <**>(0xf8400420d0->0xf8400420c8)5
 %#v: (**uint8)5
%#+v: (**uint8)(0xf8400420d0->0xf8400420c8)5

  %v: <*>{1 <*><shown>}
 %+v: <*>(0xf84003e260){ui8:1 c:<*>(0xf84003e260)<shown>}
 %#v: (*main.circular){ui8:(uint8)1 c:(*main.circular)<shown>}
%#+v: (*main.circular)(0xf84003e260){ui8:(uint8)1 c:(*main.circular)(0xf84003e260)<shown>}

Constants

const (
    // UnsafeDisabled is a build-time constant which specifies whether or
    // not access to the unsafe package is available.
    UnsafeDisabled = false
)

Variables

Config is the active configuration of the top-level functions. The configuration can be changed by modifying the contents of spew.Config.

var Config = ConfigState{Indent: " "}

func Dump ¶

func Dump(a ...interface{})

Dump displays the passed parameters to standard out with newlines, customizable indentation, and additional debug information such as complete types and all pointer addresses used to indirect to the final value. It provides the following features over the built-in printing facilities provided by the fmt package:

* Pointers are dereferenced and followed
* Circular data structures are detected and handled properly
* Custom Stringer/error interfaces are optionally invoked, including
  on unexported types
* Custom types which only implement the Stringer/error interfaces via
  a pointer receiver are optionally invoked when passing non-pointer
  variables
* Byte arrays and slices are dumped like the hexdump -C command which
  includes offsets, byte values in hex, and ASCII output

The configuration options are controlled by an exported package global, spew.Config. See ConfigState for options documentation.

See Fdump if you would prefer dumping to an arbitrary io.Writer or Sdump to get the formatted result as a string.

// The following package level declarations are assumed for this example:
/*
    type Flag int

    const (
        flagOne Flag = iota
        flagTwo
    )

    var flagStrings = map[Flag]string{
        flagOne: "flagOne",
        flagTwo: "flagTwo",
    }

    func (f Flag) String() string {
        if s, ok := flagStrings[f]; ok {
            return s
        }
        return fmt.Sprintf("Unknown flag (%d)", int(f))
    }

    type Bar struct {
        data uintptr
    }

    type Foo struct {
        unexportedField Bar
        ExportedField   map[interface{}]interface{}
    }
*/

// Setup some sample data structures for the example.
bar := Bar{uintptr(0)}
s1 := Foo{bar, map[interface{}]interface{}{"one": true}}
f := Flag(5)
b := []byte{
    0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18,
    0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20,
    0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28,
    0x29, 0x2a, 0x2b, 0x2c, 0x2d, 0x2e, 0x2f, 0x30,
    0x31, 0x32,
}

// Dump!
spew.Dump(s1, f, b)

(spew_test.Foo) {
 unexportedField: (spew_test.Bar) {
  data: (uintptr) <nil>
 },
 ExportedField: (map[interface {}]interface {}) (len=1) {
  (string) (len=3) "one": (bool) true
 }
}
(spew_test.Flag) Unknown flag (5)
([]uint8) (len=34 cap=34) {
 00000000  11 12 13 14 15 16 17 18  19 1a 1b 1c 1d 1e 1f 20  |............... |
 00000010  21 22 23 24 25 26 27 28  29 2a 2b 2c 2d 2e 2f 30  |!"#$%&'()*+,-./0|
 00000020  31 32                                             |12|
}

func Errorf ¶

func Errorf(format string, a ...interface{}) (err error)

Errorf is a wrapper for fmt.Errorf that treats each argument as if it were passed with a default Formatter interface returned by NewFormatter. It returns the formatted string as a value that satisfies error. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Errorf(format, spew.NewFormatter(a), spew.NewFormatter(b))

func Fdump ¶

func Fdump(w io.Writer, a ...interface{})

Fdump formats and displays the passed arguments to io.Writer w. It formats exactly the same as Dump.

func Fprint ¶

func Fprint(w io.Writer, a ...interface{}) (n int, err error)

Fprint is a wrapper for fmt.Fprint that treats each argument as if it were passed with a default Formatter interface returned by NewFormatter. It returns the number of bytes written and any write error encountered. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Fprint(w, spew.NewFormatter(a), spew.NewFormatter(b))

func Fprintf ¶

func Fprintf(w io.Writer, format string, a ...interface{}) (n int, err error)

Fprintf is a wrapper for fmt.Fprintf that treats each argument as if it were passed with a default Formatter interface returned by NewFormatter. It returns the number of bytes written and any write error encountered. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Fprintf(w, format, spew.NewFormatter(a), spew.NewFormatter(b))

func Fprintln ¶

func Fprintln(w io.Writer, a ...interface{}) (n int, err error)

Fprintln is a wrapper for fmt.Fprintln that treats each argument as if it passed with a default Formatter interface returned by NewFormatter. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Fprintln(w, spew.NewFormatter(a), spew.NewFormatter(b))

func NewFormatter ¶

func NewFormatter(v interface{}) fmt.Formatter

NewFormatter returns a custom formatter that satisfies the fmt.Formatter interface. As a result, it integrates cleanly with standard fmt package printing functions. The formatter is useful for inline printing of smaller data types similar to the standard %v format specifier.

The custom formatter only responds to the %v (most compact), %+v (adds pointer addresses), %#v (adds types), or %#+v (adds types and pointer addresses) verb combinations. Any other verbs such as %x and %q will be sent to the the standard fmt package for formatting. In addition, the custom formatter ignores the width and precision arguments (however they will still work on the format specifiers not handled by the custom formatter).

Typically this function shouldn't be called directly. It is much easier to make use of the custom formatter by calling one of the convenience functions such as Printf, Println, or Fprintf.

func Print ¶

func Print(a ...interface{}) (n int, err error)

Print is a wrapper for fmt.Print that treats each argument as if it were passed with a default Formatter interface returned by NewFormatter. It returns the number of bytes written and any write error encountered. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Print(spew.NewFormatter(a), spew.NewFormatter(b))

func Printf ¶

func Printf(format string, a ...interface{}) (n int, err error)

Printf is a wrapper for fmt.Printf that treats each argument as if it were passed with a default Formatter interface returned by NewFormatter. It returns the number of bytes written and any write error encountered. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Printf(format, spew.NewFormatter(a), spew.NewFormatter(b))

// Create a double pointer to a uint 8.
ui8 := uint8(5)
pui8 := &ui8
ppui8 := &pui8

// Create a circular data type.
type circular struct {
    ui8 uint8
    c   *circular
}
c := circular{ui8: 1}
c.c = &c

// Print!
spew.Printf("ppui8: %v\n", ppui8)
spew.Printf("circular: %v\n", c)

ppui8: <**>5
circular: {1 <*>{1 <*><shown>}}

func Println ¶

func Println(a ...interface{}) (n int, err error)

Println is a wrapper for fmt.Println that treats each argument as if it were passed with a default Formatter interface returned by NewFormatter. It returns the number of bytes written and any write error encountered. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Println(spew.NewFormatter(a), spew.NewFormatter(b))

func Sdump ¶

func Sdump(a ...interface{}) string

Sdump returns a string with the passed arguments formatted exactly the same as Dump.

func Sprint ¶

func Sprint(a ...interface{}) string

Sprint is a wrapper for fmt.Sprint that treats each argument as if it were passed with a default Formatter interface returned by NewFormatter. It returns the resulting string. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Sprint(spew.NewFormatter(a), spew.NewFormatter(b))

func Sprintf ¶

func Sprintf(format string, a ...interface{}) string

Sprintf is a wrapper for fmt.Sprintf that treats each argument as if it were passed with a default Formatter interface returned by NewFormatter. It returns the resulting string. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Sprintf(format, spew.NewFormatter(a), spew.NewFormatter(b))

func Sprintln ¶

func Sprintln(a ...interface{}) string

Sprintln is a wrapper for fmt.Sprintln that treats each argument as if it were passed with a default Formatter interface returned by NewFormatter. It returns the resulting string. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Sprintln(spew.NewFormatter(a), spew.NewFormatter(b))

type ConfigState ¶

ConfigState houses the configuration options used by spew to format and display values. There is a global instance, Config, that is used to control all top-level Formatter and Dump functionality. Each ConfigState instance provides methods equivalent to the top-level functions.

The zero value for ConfigState provides no indentation. You would typically want to set it to a space or a tab.

Alternatively, you can use NewDefaultConfig to get a ConfigState instance with default settings. See the documentation of NewDefaultConfig for default values.

type ConfigState struct {
    // Indent specifies the string to use for each indentation level.  The
    // global config instance that all top-level functions use set this to a
    // single space by default.  If you would like more indentation, you might
    // set this to a tab with "\t" or perhaps two spaces with "  ".
    Indent string

    // MaxDepth controls the maximum number of levels to descend into nested
    // data structures.  The default, 0, means there is no limit.
    //
    // NOTE: Circular data structures are properly detected, so it is not
    // necessary to set this value unless you specifically want to limit deeply
    // nested data structures.
    MaxDepth int

    // DisableMethods specifies whether or not error and Stringer interfaces are
    // invoked for types that implement them.
    DisableMethods bool

    // DisablePointerMethods specifies whether or not to check for and invoke
    // error and Stringer interfaces on types which only accept a pointer
    // receiver when the current type is not a pointer.
    //
    // NOTE: This might be an unsafe action since calling one of these methods
    // with a pointer receiver could technically mutate the value, however,
    // in practice, types which choose to satisify an error or Stringer
    // interface with a pointer receiver should not be mutating their state
    // inside these interface methods.  As a result, this option relies on
    // access to the unsafe package, so it will not have any effect when
    // running in environments without access to the unsafe package such as
    // Google App Engine or with the "safe" build tag specified.
    DisablePointerMethods bool

    // DisablePointerAddresses specifies whether to disable the printing of
    // pointer addresses. This is useful when diffing data structures in tests.
    DisablePointerAddresses bool

    // DisableCapacities specifies whether to disable the printing of capacities
    // for arrays, slices, maps and channels. This is useful when diffing
    // data structures in tests.
    DisableCapacities bool

    // ContinueOnMethod specifies whether or not recursion should continue once
    // a custom error or Stringer interface is invoked.  The default, false,
    // means it will print the results of invoking the custom error or Stringer
    // interface and return immediately instead of continuing to recurse into
    // the internals of the data type.
    //
    // NOTE: This flag does not have any effect if method invocation is disabled
    // via the DisableMethods or DisablePointerMethods options.
    ContinueOnMethod bool

    // SortKeys specifies map keys should be sorted before being printed. Use
    // this to have a more deterministic, diffable output.  Note that only
    // native types (bool, int, uint, floats, uintptr and string) and types
    // that support the error or Stringer interfaces (if methods are
    // enabled) are supported, with other types sorted according to the
    // reflect.Value.String() output which guarantees display stability.
    SortKeys bool

    // SpewKeys specifies that, as a last resort attempt, map keys should
    // be spewed to strings and sorted by those strings.  This is only
    // considered if SortKeys is true.
    SpewKeys bool
}

// Modify the indent level of the ConfigState only.  The global
// configuration is not modified.
scs := spew.ConfigState{Indent: "\t"}

// Output using the ConfigState instance.
v := map[string]int{"one": 1}
scs.Printf("v: %v\n", v)
scs.Dump(v)

v: map[one:1]
(map[string]int) (len=1) {
	(string) (len=3) "one": (int) 1
}

func NewDefaultConfig ¶

func NewDefaultConfig() *ConfigState

NewDefaultConfig returns a ConfigState with the following default settings.

Indent: " "
MaxDepth: 0
DisableMethods: false
DisablePointerMethods: false
ContinueOnMethod: false
SortKeys: false

func (*ConfigState) Dump ¶

func (c *ConfigState) Dump(a ...interface{})

Dump displays the passed parameters to standard out with newlines, customizable indentation, and additional debug information such as complete types and all pointer addresses used to indirect to the final value. It provides the following features over the built-in printing facilities provided by the fmt package:

* Pointers are dereferenced and followed
* Circular data structures are detected and handled properly
* Custom Stringer/error interfaces are optionally invoked, including
  on unexported types
* Custom types which only implement the Stringer/error interfaces via
  a pointer receiver are optionally invoked when passing non-pointer
  variables
* Byte arrays and slices are dumped like the hexdump -C command which
  includes offsets, byte values in hex, and ASCII output

The configuration options are controlled by modifying the public members of c. See ConfigState for options documentation.

See Fdump if you would prefer dumping to an arbitrary io.Writer or Sdump to get the formatted result as a string.

// See the top-level Dump example for details on the types used in this
// example.

// Create two ConfigState instances with different indentation.
scs := spew.ConfigState{Indent: "\t"}
scs2 := spew.ConfigState{Indent: " "}

// Setup some sample data structures for the example.
bar := Bar{uintptr(0)}
s1 := Foo{bar, map[interface{}]interface{}{"one": true}}

// Dump using the ConfigState instances.
scs.Dump(s1)
scs2.Dump(s1)

(spew_test.Foo) {
	unexportedField: (spew_test.Bar) {
		data: (uintptr) <nil>
	},
	ExportedField: (map[interface {}]interface {}) (len=1) {
		(string) (len=3) "one": (bool) true
	}
}
(spew_test.Foo) {
 unexportedField: (spew_test.Bar) {
  data: (uintptr) <nil>
 },
 ExportedField: (map[interface {}]interface {}) (len=1) {
  (string) (len=3) "one": (bool) true
 }
}

func (*ConfigState) Errorf ¶

func (c *ConfigState) Errorf(format string, a ...interface{}) (err error)

Errorf is a wrapper for fmt.Errorf that treats each argument as if it were passed with a Formatter interface returned by c.NewFormatter. It returns the formatted string as a value that satisfies error. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Errorf(format, c.NewFormatter(a), c.NewFormatter(b))

func (*ConfigState) Fdump ¶

func (c *ConfigState) Fdump(w io.Writer, a ...interface{})

Fdump formats and displays the passed arguments to io.Writer w. It formats exactly the same as Dump.

func (*ConfigState) Fprint ¶

func (c *ConfigState) Fprint(w io.Writer, a ...interface{}) (n int, err error)

Fprint is a wrapper for fmt.Fprint that treats each argument as if it were passed with a Formatter interface returned by c.NewFormatter. It returns the number of bytes written and any write error encountered. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Fprint(w, c.NewFormatter(a), c.NewFormatter(b))

func (*ConfigState) Fprintf ¶

func (c *ConfigState) Fprintf(w io.Writer, format string, a ...interface{}) (n int, err error)

Fprintf is a wrapper for fmt.Fprintf that treats each argument as if it were passed with a Formatter interface returned by c.NewFormatter. It returns the number of bytes written and any write error encountered. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Fprintf(w, format, c.NewFormatter(a), c.NewFormatter(b))

func (*ConfigState) Fprintln ¶

func (c *ConfigState) Fprintln(w io.Writer, a ...interface{}) (n int, err error)

Fprintln is a wrapper for fmt.Fprintln that treats each argument as if it passed with a Formatter interface returned by c.NewFormatter. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Fprintln(w, c.NewFormatter(a), c.NewFormatter(b))

func (*ConfigState) NewFormatter ¶

func (c *ConfigState) NewFormatter(v interface{}) fmt.Formatter

NewFormatter returns a custom formatter that satisfies the fmt.Formatter interface. As a result, it integrates cleanly with standard fmt package printing functions. The formatter is useful for inline printing of smaller data types similar to the standard %v format specifier.

The custom formatter only responds to the %v (most compact), %+v (adds pointer addresses), %#v (adds types), and %#+v (adds types and pointer addresses) verb combinations. Any other verbs such as %x and %q will be sent to the the standard fmt package for formatting. In addition, the custom formatter ignores the width and precision arguments (however they will still work on the format specifiers not handled by the custom formatter).

Typically this function shouldn't be called directly. It is much easier to make use of the custom formatter by calling one of the convenience functions such as c.Printf, c.Println, or c.Printf.

func (*ConfigState) Print ¶

func (c *ConfigState) Print(a ...interface{}) (n int, err error)

Print is a wrapper for fmt.Print that treats each argument as if it were passed with a Formatter interface returned by c.NewFormatter. It returns the number of bytes written and any write error encountered. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Print(c.NewFormatter(a), c.NewFormatter(b))

func (*ConfigState) Printf ¶

func (c *ConfigState) Printf(format string, a ...interface{}) (n int, err error)

Printf is a wrapper for fmt.Printf that treats each argument as if it were passed with a Formatter interface returned by c.NewFormatter. It returns the number of bytes written and any write error encountered. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Printf(format, c.NewFormatter(a), c.NewFormatter(b))

// See the top-level Dump example for details on the types used in this
// example.

// Create two ConfigState instances and modify the method handling of the
// first ConfigState only.
scs := spew.NewDefaultConfig()
scs2 := spew.NewDefaultConfig()
scs.DisableMethods = true

// Alternatively
// scs := spew.ConfigState{Indent: " ", DisableMethods: true}
// scs2 := spew.ConfigState{Indent: " "}

// This is of type Flag which implements a Stringer and has raw value 1.
f := flagTwo

// Dump using the ConfigState instances.
scs.Printf("f: %v\n", f)
scs2.Printf("f: %v\n", f)

f: 1
f: flagTwo

func (*ConfigState) Println ¶

func (c *ConfigState) Println(a ...interface{}) (n int, err error)

Println is a wrapper for fmt.Println that treats each argument as if it were passed with a Formatter interface returned by c.NewFormatter. It returns the number of bytes written and any write error encountered. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Println(c.NewFormatter(a), c.NewFormatter(b))

func (*ConfigState) Sdump ¶

func (c *ConfigState) Sdump(a ...interface{}) string

Sdump returns a string with the passed arguments formatted exactly the same as Dump.

func (*ConfigState) Sprint ¶

func (c *ConfigState) Sprint(a ...interface{}) string

Sprint is a wrapper for fmt.Sprint that treats each argument as if it were passed with a Formatter interface returned by c.NewFormatter. It returns the resulting string. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Sprint(c.NewFormatter(a), c.NewFormatter(b))

func (*ConfigState) Sprintf ¶

func (c *ConfigState) Sprintf(format string, a ...interface{}) string

Sprintf is a wrapper for fmt.Sprintf that treats each argument as if it were passed with a Formatter interface returned by c.NewFormatter. It returns the resulting string. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Sprintf(format, c.NewFormatter(a), c.NewFormatter(b))

func (*ConfigState) Sprintln ¶

func (c *ConfigState) Sprintln(a ...interface{}) string

Sprintln is a wrapper for fmt.Sprintln that treats each argument as if it were passed with a Formatter interface returned by c.NewFormatter. It returns the resulting string. See NewFormatter for formatting details.

This function is shorthand for the following syntax:

fmt.Sprintln(c.NewFormatter(a), c.NewFormatter(b))