README.md 6.95 KB
Newer Older
Dave Collins's avatar
Dave Collins committed
1
2
3
go-spew
=======

4
5
6
[![Build Status](https://img.shields.io/travis/davecgh/go-spew.svg)](https://travis-ci.org/davecgh/go-spew)
[![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org)
[![Coverage Status](https://img.shields.io/coveralls/davecgh/go-spew.svg)](https://coveralls.io/r/davecgh/go-spew?branch=master)
7

Dave Collins's avatar
Dave Collins committed
8
Go-spew implements a deep pretty printer for Go data structures to aid in
Dave Collins's avatar
Dave Collins committed
9
10
11
12
debugging.  A comprehensive suite of tests with 100% test coverage is provided
to ensure proper functionality.  See `test_coverage.txt` for the gocov coverage
report.  Go-spew is licensed under the liberal ISC license, so it may be used in
open source or commercial projects.
Dave Collins's avatar
Dave Collins committed
13

Dave Collins's avatar
Dave Collins committed
14
If you're interested in reading about how this package came to life and some
Dave Collins's avatar
Dave Collins committed
15
of the challenges involved in providing a deep pretty printer, there is a blog
Dave Collins's avatar
Dave Collins committed
16
post about it
17
[here](https://web.archive.org/web/20160304013555/https://blog.cyphertite.com/go-spew-a-journey-into-dumping-go-data-structures/).
Dave Collins's avatar
Dave Collins committed
18

Dave Collins's avatar
Dave Collins committed
19
20
## Documentation

21
[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](http://godoc.org/github.com/davecgh/go-spew/spew)
22

Dave Collins's avatar
Dave Collins committed
23
24
25
26
27
28
29
30
31
32
33
Full `go doc` style documentation for the project can be viewed online without
installing this package by using the excellent GoDoc site here:
http://godoc.org/github.com/davecgh/go-spew/spew

You can also view the documentation locally once the package is installed with
the `godoc` tool by running `godoc -http=":6060"` and pointing your browser to
http://localhost:6060/pkg/github.com/davecgh/go-spew/spew

## Installation

```bash
34
$ go get -u github.com/davecgh/go-spew/spew
Dave Collins's avatar
Dave Collins committed
35
36
37
38
```

## Quick Start

39
40
41
Add this import line to the file you're working in:

```Go
Brian Dorsey's avatar
Brian Dorsey committed
42
import "github.com/davecgh/go-spew/spew"
43
44
```

Dave Collins's avatar
Dave Collins committed
45
To dump a variable with full newlines, indentation, type, and pointer
Dave Collins's avatar
Dave Collins committed
46
information use Dump, Fdump, or Sdump:
Dave Collins's avatar
Dave Collins committed
47
48
49
50

```Go
spew.Dump(myVar1, myVar2, ...)
spew.Fdump(someWriter, myVar1, myVar2, ...)
Dave Collins's avatar
Dave Collins committed
51
str := spew.Sdump(myVar1, myVar2, ...)
Dave Collins's avatar
Dave Collins committed
52
53
54
```

Alternatively, if you would prefer to use format strings with a compacted inline
Dave Collins's avatar
Dave Collins committed
55
56
57
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): 
Dave Collins's avatar
Dave Collins committed
58
59
60

```Go
spew.Printf("myVar1: %v -- myVar2: %+v", myVar1, myVar2)
Dave Collins's avatar
Dave Collins committed
61
spew.Printf("myVar3: %#v -- myVar4: %#+v", myVar3, myVar4)
Dave Collins's avatar
Dave Collins committed
62
spew.Fprintf(someWriter, "myVar1: %v -- myVar2: %+v", myVar1, myVar2)
Dave Collins's avatar
Dave Collins committed
63
spew.Fprintf(someWriter, "myVar3: %#v -- myVar4: %#+v", myVar3, myVar4)
Dave Collins's avatar
Dave Collins committed
64
65
```

66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
## Debugging a Web Application Example

Here is an example of how you can use `spew.Sdump()` to help debug a web application. Please be sure to wrap your output using the `html.EscapeString()` function for safety reasons. You should also only use this debugging technique in a development environment, never in production.

```Go
package main

import (
    "fmt"
    "html"
    "net/http"

    "github.com/davecgh/go-spew/spew"
)

func handler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "text/html")
    fmt.Fprintf(w, "Hi there, %s!", r.URL.Path[1:])
    fmt.Fprintf(w, "<!--\n" + html.EscapeString(spew.Sdump(w)) + "\n-->")
}

func main() {
    http.HandleFunc("/", handler)
    http.ListenAndServe(":8080", nil)
}
```

Dave Collins's avatar
Dave Collins committed
93
94
95
## Sample Dump Output

```
Dave Collins's avatar
Dave Collins committed
96
97
98
99
100
101
102
103
104
(main.Foo) {
 unexportedField: (*main.Bar)(0xf84002e210)({
  flag: (main.Flag) flagTwo,
  data: (uintptr) <nil>
 }),
 ExportedField: (map[interface {}]interface {}) {
  (string) "one": (bool) true
 }
}
105
([]uint8) {
Dave Collins's avatar
Dave Collins committed
106
107
108
109
 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|
}
Dave Collins's avatar
Dave Collins committed
110
111
112
113
```

## Sample Formatter Output

Dave Collins's avatar
Dave Collins committed
114
Double pointer to a uint8:
Dave Collins's avatar
Dave Collins committed
115
```
Dave Collins's avatar
Dave Collins committed
116
117
118
119
	  %v: <**>5
	 %+v: <**>(0xf8400420d0->0xf8400420c8)5
	 %#v: (**uint8)5
	%#+v: (**uint8)(0xf8400420d0->0xf8400420c8)5
Dave Collins's avatar
Dave Collins committed
120
121
```

Dave Collins's avatar
Dave Collins committed
122
Pointer to circular struct with a uint8 field and a pointer to itself:
Dave Collins's avatar
Dave Collins committed
123
```
Dave Collins's avatar
Dave Collins committed
124
125
126
127
	  %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>}
Dave Collins's avatar
Dave Collins committed
128
129
```

Dave Collins's avatar
Dave Collins committed
130
131
## Configuration Options

Dave Collins's avatar
Dave Collins committed
132
133
134
135
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.

Dave Collins's avatar
Dave Collins committed
136
It is also possible to create a ConfigState instance that provides methods
Dave Collins's avatar
Dave Collins committed
137
equivalent to the top-level functions. This allows concurrent configuration
Dave Collins's avatar
Dave Collins committed
138
options. See the ConfigState documentation for more details.
Dave Collins's avatar
Dave Collins committed
139

Dave Collins's avatar
Dave Collins committed
140
```
Dave Collins's avatar
Dave Collins committed
141
* Indent
Dave Collins's avatar
Dave Collins committed
142
143
144
	String to use for each indentation level for Dump functions.
	It is a single space by default.  A popular alternative is "\t".

Dave Collins's avatar
Dave Collins committed
145
146
147
148
* MaxDepth
	Maximum number of levels to descend into nested data structures.
	There is no limit by default.

Dave Collins's avatar
Dave Collins committed
149
* DisableMethods
Dave Collins's avatar
Dave Collins committed
150
151
152
	Disables invocation of error and Stringer interface methods.
	Method invocation is enabled by default.

Dave Collins's avatar
Dave Collins committed
153
* DisablePointerMethods
Dave Collins's avatar
Dave Collins committed
154
	Disables invocation of error and Stringer interface methods on types
155
156
157
	which only accept pointer receivers from non-pointer variables.  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
158
	App Engine or with the "safe" build tag specified.
Dave Collins's avatar
Dave Collins committed
159
	Pointer method invocation is enabled by default.
160

161
162
163
164
165
166
167
168
169
* 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.

170
171
172
* ContinueOnMethod
	Enables recursion into types after invoking error and Stringer interface
	methods. Recursion after method invocation is disabled by default.
173
174
175
176
177

* 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)
178
179
180
181
182
183
184
185
186
187
	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
	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.

Dave Collins's avatar
Dave Collins committed
188
189
```

190
191
192
193
194
## Unsafe Package Dependency

This package relies on the unsafe package to perform some of the more advanced
features, however it also supports a "limited" mode which allows it to work in
environments where the unsafe package is not available.  By default, it will
195
196
197
operate in this mode on Google App Engine and when compiled with GopherJS.  The
"safe" build tag may also be specified to force the package to build without
using the unsafe package.
198

Dave Collins's avatar
Dave Collins committed
199
200
## License

201
Go-spew is licensed under the [copyfree](http://copyfree.org) ISC License.