vendor/github.com/davecgh/go-spew/README.md

   1 go-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
   8 Go-spew implements a deep pretty printer for Go data structures to aid in
   9 debugging.  A comprehensive suite of tests with 100% test coverage is provided
  10 to ensure proper functionality.  See `test_coverage.txt` for the gocov coverage
  11 report.  Go-spew is licensed under the liberal ISC license, so it may be used in
  12 open source or commercial projects.
  13
  14 If you're interested in reading about how this package came to life and some
  15 of the challenges involved in providing a deep pretty printer, there is a blog
  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/).
  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
  23 Full `go doc` style documentation for the project can be viewed online without
  24 installing this package by using the excellent GoDoc site here:
  25 http://godoc.org/github.com/davecgh/go-spew/spew
  26
  27 You can also view the documentation locally once the package is installed with
  28 the `godoc` tool by running `godoc -http=":6060"` and pointing your browser to
  29 http://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
  39 Add this import line to the file you're working in:
  40
  41 ```Go
  42 import "github.com/davecgh/go-spew/spew"
  43 ```
  44
  45 To dump a variable with full newlines, indentation, type, and pointer
  46 information use Dump, Fdump, or Sdump:
  47
  48 ```Go
  49 spew.Dump(myVar1, myVar2, ...)
  50 spew.Fdump(someWriter, myVar1, myVar2, ...)
  51 str := spew.Sdump(myVar1, myVar2, ...)
  52 ```
  53
  54 Alternatively, if you would prefer to use format strings with a compacted inline
  55 printing style, use the convenience wrappers Printf, Fprintf, etc with %v (most
  56 compact), %+v (adds pointer addresses), %#v (adds types), or %#+v (adds types
  57 and pointer addresses):
  58
  59 ```Go
  60 spew.Printf("myVar1: %v -- myVar2: %+v", myVar1, myVar2)
  61 spew.Printf("myVar3: %#v -- myVar4: %#+v", myVar3, myVar4)
  62 spew.Fprintf(someWriter, "myVar1: %v -- myVar2: %+v", myVar1, myVar2)
  63 spew.Fprintf(someWriter, "myVar3: %#v -- myVar4: %#+v", myVar3, myVar4)
  64 ```
  65
  66 ## Debugging a Web Application Example
  67
  68 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.
  69
  70 ```Go
  71 package main
  72
  73 import (
  74     "fmt"
  75     "html"
  76     "net/http"
  77
  78     "github.com/davecgh/go-spew/spew"
  79 )
  80
  81 func 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
  87 func 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
 114 Double 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
 122 Pointer 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
 132 Configuration of spew is handled by fields in the ConfigState type. For
 133 convenience, all of the top-level functions use a global state available via the
 134 spew.Config global.
 135
 136 It is also possible to create a ConfigState instance that provides methods
 137 equivalent to the top-level functions. This allows concurrent configuration
 138 options. 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
 192 This package relies on the unsafe package to perform some of the more advanced
 193 features, however it also supports a "limited" mode which allows it to work in
 194 environments where the unsafe package is not available.  By default, it will
 195 operate 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
 197 using the unsafe package.
 198
 199 ## License
 200
 201 Go-spew is licensed under the [copyfree](http://copyfree.org) ISC License.