1go-spew 2======= 3 4[![Build Status](https://img.shields.io/travis/davecgh/go-spew.svg)](https://travis-ci.org/davecgh/go-spew) 5[![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org) 6[![Coverage Status](https://img.shields.io/coveralls/davecgh/go-spew.svg)](https://coveralls.io/r/davecgh/go-spew?branch=master) 7 8Go-spew implements a deep pretty printer for Go data structures to aid in 9debugging. A comprehensive suite of tests with 100% test coverage is provided 10to ensure proper functionality. See `test_coverage.txt` for the gocov coverage 11report. Go-spew is licensed under the liberal ISC license, so it may be used in 12open source or commercial projects. 13 14If you're interested in reading about how this package came to life and some 15of the challenges involved in providing a deep pretty printer, there is a blog 16post about it 17[here](https://web.archive.org/web/20160304013555/https://blog.cyphertite.com/go-spew-a-journey-into-dumping-go-data-structures/). 18 19## Documentation 20 21[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](http://godoc.org/github.com/davecgh/go-spew/spew) 22 23Full `go doc` style documentation for the project can be viewed online without 24installing this package by using the excellent GoDoc site here: 25http://godoc.org/github.com/davecgh/go-spew/spew 26 27You can also view the documentation locally once the package is installed with 28the `godoc` tool by running `godoc -http=":6060"` and pointing your browser to 29http://localhost:6060/pkg/github.com/davecgh/go-spew/spew 30 31## Installation 32 33```bash 34$ go get -u github.com/davecgh/go-spew/spew 35``` 36 37## Quick Start 38 39Add this import line to the file you're working in: 40 41```Go 42import "github.com/davecgh/go-spew/spew" 43``` 44 45To dump a variable with full newlines, indentation, type, and pointer 46information use Dump, Fdump, or Sdump: 47 48```Go 49spew.Dump(myVar1, myVar2, ...) 50spew.Fdump(someWriter, myVar1, myVar2, ...) 51str := spew.Sdump(myVar1, myVar2, ...) 52``` 53 54Alternatively, if you would prefer to use format strings with a compacted inline 55printing style, use the convenience wrappers Printf, Fprintf, etc with %v (most 56compact), %+v (adds pointer addresses), %#v (adds types), or %#+v (adds types 57and pointer addresses): 58 59```Go 60spew.Printf("myVar1: %v -- myVar2: %+v", myVar1, myVar2) 61spew.Printf("myVar3: %#v -- myVar4: %#+v", myVar3, myVar4) 62spew.Fprintf(someWriter, "myVar1: %v -- myVar2: %+v", myVar1, myVar2) 63spew.Fprintf(someWriter, "myVar3: %#v -- myVar4: %#+v", myVar3, myVar4) 64``` 65 66## Debugging a Web Application Example 67 68Here 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. 69 70```Go 71package main 72 73import ( 74 "fmt" 75 "html" 76 "net/http" 77 78 "github.com/davecgh/go-spew/spew" 79) 80 81func handler(w http.ResponseWriter, r *http.Request) { 82 w.Header().Set("Content-Type", "text/html") 83 fmt.Fprintf(w, "Hi there, %s!", r.URL.Path[1:]) 84 fmt.Fprintf(w, "<!--\n" + html.EscapeString(spew.Sdump(w)) + "\n-->") 85} 86 87func main() { 88 http.HandleFunc("/", handler) 89 http.ListenAndServe(":8080", nil) 90} 91``` 92 93## Sample Dump Output 94 95``` 96(main.Foo) { 97 unexportedField: (*main.Bar)(0xf84002e210)({ 98 flag: (main.Flag) flagTwo, 99 data: (uintptr) <nil> 100 }), 101 ExportedField: (map[interface {}]interface {}) { 102 (string) "one": (bool) true 103 } 104} 105([]uint8) { 106 00000000 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 20 |............... | 107 00000010 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 30 |!"#$%&'()*+,-./0| 108 00000020 31 32 |12| 109} 110``` 111 112## Sample Formatter Output 113 114Double pointer to a uint8: 115``` 116 %v: <**>5 117 %+v: <**>(0xf8400420d0->0xf8400420c8)5 118 %#v: (**uint8)5 119 %#+v: (**uint8)(0xf8400420d0->0xf8400420c8)5 120``` 121 122Pointer to circular struct with a uint8 field and a pointer to itself: 123``` 124 %v: <*>{1 <*><shown>} 125 %+v: <*>(0xf84003e260){ui8:1 c:<*>(0xf84003e260)<shown>} 126 %#v: (*main.circular){ui8:(uint8)1 c:(*main.circular)<shown>} 127 %#+v: (*main.circular)(0xf84003e260){ui8:(uint8)1 c:(*main.circular)(0xf84003e260)<shown>} 128``` 129 130## Configuration Options 131 132Configuration of spew is handled by fields in the ConfigState type. For 133convenience, all of the top-level functions use a global state available via the 134spew.Config global. 135 136It is also possible to create a ConfigState instance that provides methods 137equivalent to the top-level functions. This allows concurrent configuration 138options. See the ConfigState documentation for more details. 139 140``` 141* Indent 142 String to use for each indentation level for Dump functions. 143 It is a single space by default. A popular alternative is "\t". 144 145* MaxDepth 146 Maximum number of levels to descend into nested data structures. 147 There is no limit by default. 148 149* DisableMethods 150 Disables invocation of error and Stringer interface methods. 151 Method invocation is enabled by default. 152 153* DisablePointerMethods 154 Disables invocation of error and Stringer interface methods on types 155 which only accept pointer receivers from non-pointer variables. This option 156 relies on access to the unsafe package, so it will not have any effect when 157 running in environments without access to the unsafe package such as Google 158 App Engine or with the "safe" build tag specified. 159 Pointer method invocation is enabled by default. 160 161* DisablePointerAddresses 162 DisablePointerAddresses specifies whether to disable the printing of 163 pointer addresses. This is useful when diffing data structures in tests. 164 165* DisableCapacities 166 DisableCapacities specifies whether to disable the printing of capacities 167 for arrays, slices, maps and channels. This is useful when diffing data 168 structures in tests. 169 170* ContinueOnMethod 171 Enables recursion into types after invoking error and Stringer interface 172 methods. Recursion after method invocation is disabled by default. 173 174* SortKeys 175 Specifies map keys should be sorted before being printed. Use 176 this to have a more deterministic, diffable output. Note that 177 only native types (bool, int, uint, floats, uintptr and string) 178 and types which implement error or Stringer interfaces are supported, 179 with other types sorted according to the reflect.Value.String() output 180 which guarantees display stability. Natural map order is used by 181 default. 182 183* SpewKeys 184 SpewKeys specifies that, as a last resort attempt, map keys should be 185 spewed to strings and sorted by those strings. This is only considered 186 if SortKeys is true. 187 188``` 189 190## Unsafe Package Dependency 191 192This package relies on the unsafe package to perform some of the more advanced 193features, however it also supports a "limited" mode which allows it to work in 194environments where the unsafe package is not available. By default, it will 195operate in this mode on Google App Engine and when compiled with GopherJS. The 196"safe" build tag may also be specified to force the package to build without 197using the unsafe package. 198 199## License 200 201Go-spew is licensed under the [copyfree](http://copyfree.org) ISC License. 202