Involved Source Filesbypass.gocommon.goconfig.go Package spew implements a deep pretty printer for Go data structures to aid in
debugging.
A quick overview of the additional features spew provides over the built-in
printing facilities for Go data types are as follows:
* 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)
There are two different approaches spew allows for dumping Go data structures:
* 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
Quick Start
This section demonstrates how to quickly get started with spew. See the
sections below for further details on formatting and configuration options.
To dump a variable with full newlines, indentation, type, and pointer
information use Dump, Fdump, or Sdump:
spew.Dump(myVar1, myVar2, ...)
spew.Fdump(someWriter, myVar1, myVar2, ...)
str := spew.Sdump(myVar1, myVar2, ...)
Alternatively, if you would prefer to use format strings with a compacted inline
printing style, use the convenience wrappers Printf, Fprintf, etc with
%v (most compact), %+v (adds pointer addresses), %#v (adds types), or
%#+v (adds types and pointer addresses):
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)
Configuration Options
Configuration of spew is handled by fields in the ConfigState type. For
convenience, all of the top-level functions use a global state available
via the spew.Config global.
It is also possible to create a ConfigState instance that provides methods
equivalent to the top-level functions. This allows concurrent configuration
options. See the ConfigState documentation for more details.
The following configuration options are available:
* 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.
Dump Usage
Simply call spew.Dump with a list of variables you want to dump:
spew.Dump(myVar1, myVar2, ...)
You may also call spew.Fdump if you would prefer to output to an arbitrary
io.Writer. For example, to dump to standard error:
spew.Fdump(os.Stderr, myVar1, myVar2, ...)
A third option is to call spew.Sdump to get the formatted output as a string:
str := spew.Sdump(myVar1, myVar2, ...)
Sample Dump Output
See the Dump example for details on the setup of the types and variables being
shown here.
(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
}
}
Byte (and uint8) arrays and slices are displayed uniquely like the hexdump -C
command as shown.
([]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|
}
Custom Formatter
Spew provides a custom formatter that implements the fmt.Formatter interface
so that 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).
Custom Formatter Usage
The simplest way to make use of the spew custom formatter is to call one of the
convenience functions such as spew.Printf, spew.Println, or spew.Printf. The
functions have syntax you are most likely already familiar with:
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)
See the Index for the full list convenience functions.
Sample Formatter Output
Double pointer to a uint8:
%v: <**>5
%+v: <**>(0xf8400420d0->0xf8400420c8)5
%#v: (**uint8)5
%#+v: (**uint8)(0xf8400420d0->0xf8400420c8)5
Pointer to circular struct with a uint8 field and a pointer to itself:
%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>}
See the Printf example for details on the setup of variables being shown
here.
Errors
Since it is possible for custom Stringer/error interfaces to panic, spew
detects them and handles them internally by printing the panic information
inline with the output. Since spew is intended to provide deep pretty printing
capabilities on structures, it intentionally does not return any errors.dump.goformat.gospew.go
Code Examples
package main
import (
"github.com/davecgh/go-spew/spew"
)
func main() {
// 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)
}
package main
import (
"github.com/davecgh/go-spew/spew"
)
type Bar struct {
data uintptr
}
type Foo struct {
unexportedField Bar
ExportedField map[interface{}]interface{}
}
func main() {
// 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)
}
package main
import (
"fmt"
"github.com/davecgh/go-spew/spew"
)
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))
}
func main() {
// 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)
}
package main
import (
"fmt"
"github.com/davecgh/go-spew/spew"
)
type Flag int
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{}
}
func main() {
// 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)
}
package main
import (
"github.com/davecgh/go-spew/spew"
)
func main() {
// 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)
}
Package-Level Type Names (only one)
/* sort by: | */
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. 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. DisableCapacities specifies whether to disable the printing of capacities
for arrays, slices, maps and channels. This is useful when diffing
data structures in tests. DisableMethods specifies whether or not error and Stringer interfaces are
invoked for types that implement them. DisablePointerAddresses specifies whether to disable the printing of
pointer addresses. This is useful when diffing data structures in tests. 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. 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 " ". 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. 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. 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. 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. 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)) Fdump formats and displays the passed arguments to io.Writer w. It formats
exactly the same as Dump. 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)) 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)) 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)) 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. 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)) 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)) 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)) Sdump returns a string with the passed arguments formatted exactly the same
as Dump. 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)) 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)) 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))
func NewDefaultConfig() *ConfigState
var Config
Package-Level Functions (total 15)
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.
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))
Fdump formats and displays the passed arguments to io.Writer w. It formats
exactly the same as Dump.
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))
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))
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))
NewDefaultConfig returns a ConfigState with the following default settings.
Indent: " "
MaxDepth: 0
DisableMethods: false
DisablePointerMethods: false
ContinueOnMethod: false
SortKeys: false
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.
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))
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))
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))
Sdump returns a string with the passed arguments formatted exactly the same
as Dump.
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))
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))
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))
Package-Level Variables (only one)
Config is the active configuration of the top-level functions.
The configuration can be changed by modifying the contents of spew.Config.
Package-Level Constants (only one)
UnsafeDisabled is a build-time constant which specifies whether or
not access to the unsafe package is available.
The pages are generated with Goldsv0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.
