vendor/github.com/stretchr/testify/vendor/github.com/davecgh/go-spew/spew/doc.go

   1 /*
   2  * Copyright (c) 2013 Dave Collins <dave@davec.name>
   3  *
   4  * Permission to use, copy, modify, and distribute this software for any
   5  * purpose with or without fee is hereby granted, provided that the above
   6  * copyright notice and this permission notice appear in all copies.
   7  *
   8  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15  */
  16
  17 /*
  18 Package spew implements a deep pretty printer for Go data structures to aid in
  19 debugging.
  20
  21 A quick overview of the additional features spew provides over the built-in
  22 printing facilities for Go data types are as follows:
  23
  24         * Pointers are dereferenced and followed
  25         * Circular data structures are detected and handled properly
  26         * Custom Stringer/error interfaces are optionally invoked, including
  27           on unexported types
  28         * Custom types which only implement the Stringer/error interfaces via
  29           a pointer receiver are optionally invoked when passing non-pointer
  30           variables
  31         * Byte arrays and slices are dumped like the hexdump -C command which
  32           includes offsets, byte values in hex, and ASCII output (only when using
  33           Dump style)
  34
  35 There are two different approaches spew allows for dumping Go data structures:
  36
  37         * Dump style which prints with newlines, customizable indentation,
  38           and additional debug information such as types and all pointer addresses
  39           used to indirect to the final value
  40         * A custom Formatter interface that integrates cleanly with the standard fmt
  41           package and replaces %v, %+v, %#v, and %#+v to provide inline printing
  42           similar to the default %v while providing the additional functionality
  43           outlined above and passing unsupported format verbs such as %x and %q
  44           along to fmt
  45
  46 Quick Start
  47
  48 This section demonstrates how to quickly get started with spew.  See the
  49 sections below for further details on formatting and configuration options.
  50
  51 To dump a variable with full newlines, indentation, type, and pointer
  52 information use Dump, Fdump, or Sdump:
  53         spew.Dump(myVar1, myVar2, ...)
  54         spew.Fdump(someWriter, myVar1, myVar2, ...)
  55         str := spew.Sdump(myVar1, myVar2, ...)
  56
  57 Alternatively, if you would prefer to use format strings with a compacted inline
  58 printing style, use the convenience wrappers Printf, Fprintf, etc with
  59 %v (most compact), %+v (adds pointer addresses), %#v (adds types), or
  60 %#+v (adds types and pointer addresses):
  61         spew.Printf("myVar1: %v -- myVar2: %+v", myVar1, myVar2)
  62         spew.Printf("myVar3: %#v -- myVar4: %#+v", myVar3, myVar4)
  63         spew.Fprintf(someWriter, "myVar1: %v -- myVar2: %+v", myVar1, myVar2)
  64         spew.Fprintf(someWriter, "myVar3: %#v -- myVar4: %#+v", myVar3, myVar4)
  65
  66 Configuration Options
  67
  68 Configuration of spew is handled by fields in the ConfigState type.  For
  69 convenience, all of the top-level functions use a global state available
  70 via the spew.Config global.
  71
  72 It is also possible to create a ConfigState instance that provides methods
  73 equivalent to the top-level functions.  This allows concurrent configuration
  74 options.  See the ConfigState documentation for more details.
  75
  76 The following configuration options are available:
  77         * Indent
  78                 String to use for each indentation level for Dump functions.
  79                 It is a single space by default.  A popular alternative is "\t".
  80
  81         * MaxDepth
  82                 Maximum number of levels to descend into nested data structures.
  83                 There is no limit by default.
  84
  85         * DisableMethods
  86                 Disables invocation of error and Stringer interface methods.
  87                 Method invocation is enabled by default.
  88
  89         * DisablePointerMethods
  90                 Disables invocation of error and Stringer interface methods on types
  91                 which only accept pointer receivers from non-pointer variables.
  92                 Pointer method invocation is enabled by default.
  93
  94         * ContinueOnMethod
  95                 Enables recursion into types after invoking error and Stringer interface
  96                 methods. Recursion after method invocation is disabled by default.
  97
  98         * SortKeys
  99                 Specifies map keys should be sorted before being printed. Use
 100                 this to have a more deterministic, diffable output.  Note that
 101                 only native types (bool, int, uint, floats, uintptr and string)
 102                 and types which implement error or Stringer interfaces are
 103                 supported with other types sorted according to the
 104                 reflect.Value.String() output which guarantees display
 105                 stability.  Natural map order is used by default.
 106
 107         * SpewKeys
 108                 Specifies that, as a last resort attempt, map keys should be
 109                 spewed to strings and sorted by those strings.  This is only
 110                 considered if SortKeys is true.
 111
 112 Dump Usage
 113
 114 Simply call spew.Dump with a list of variables you want to dump:
 115
 116         spew.Dump(myVar1, myVar2, ...)
 117
 118 You may also call spew.Fdump if you would prefer to output to an arbitrary
 119 io.Writer.  For example, to dump to standard error:
 120
 121         spew.Fdump(os.Stderr, myVar1, myVar2, ...)
 122
 123 A third option is to call spew.Sdump to get the formatted output as a string:
 124
 125         str := spew.Sdump(myVar1, myVar2, ...)
 126
 127 Sample Dump Output
 128
 129 See the Dump example for details on the setup of the types and variables being
 130 shown here.
 131
 132         (main.Foo) {
 133          unexportedField: (*main.Bar)(0xf84002e210)({
 134           flag: (main.Flag) flagTwo,
 135           data: (uintptr) <nil>
 136          }),
 137          ExportedField: (map[interface {}]interface {}) (len=1) {
 138           (string) (len=3) "one": (bool) true
 139          }
 140         }
 141
 142 Byte (and uint8) arrays and slices are displayed uniquely like the hexdump -C
 143 command as shown.
 144         ([]uint8) (len=32 cap=32) {
 145          00000000  11 12 13 14 15 16 17 18  19 1a 1b 1c 1d 1e 1f 20  |............... |
 146          00000010  21 22 23 24 25 26 27 28  29 2a 2b 2c 2d 2e 2f 30  |!"#$%&'()*+,-./0|
 147          00000020  31 32                                             |12|
 148         }
 149
 150 Custom Formatter
 151
 152 Spew provides a custom formatter that implements the fmt.Formatter interface
 153 so that it integrates cleanly with standard fmt package printing functions. The
 154 formatter is useful for inline printing of smaller data types similar to the
 155 standard %v format specifier.
 156
 157 The custom formatter only responds to the %v (most compact), %+v (adds pointer
 158 addresses), %#v (adds types), or %#+v (adds types and pointer addresses) verb
 159 combinations.  Any other verbs such as %x and %q will be sent to the the
 160 standard fmt package for formatting.  In addition, the custom formatter ignores
 161 the width and precision arguments (however they will still work on the format
 162 specifiers not handled by the custom formatter).
 163
 164 Custom Formatter Usage
 165
 166 The simplest way to make use of the spew custom formatter is to call one of the
 167 convenience functions such as spew.Printf, spew.Println, or spew.Printf.  The
 168 functions have syntax you are most likely already familiar with:
 169
 170         spew.Printf("myVar1: %v -- myVar2: %+v", myVar1, myVar2)
 171         spew.Printf("myVar3: %#v -- myVar4: %#+v", myVar3, myVar4)
 172         spew.Println(myVar, myVar2)
 173         spew.Fprintf(os.Stderr, "myVar1: %v -- myVar2: %+v", myVar1, myVar2)
 174         spew.Fprintf(os.Stderr, "myVar3: %#v -- myVar4: %#+v", myVar3, myVar4)
 175
 176 See the Index for the full list convenience functions.
 177
 178 Sample Formatter Output
 179
 180 Double pointer to a uint8:
 181           %v: <**>5
 182          %+v: <**>(0xf8400420d0->0xf8400420c8)5
 183          %#v: (**uint8)5
 184         %#+v: (**uint8)(0xf8400420d0->0xf8400420c8)5
 185
 186 Pointer to circular struct with a uint8 field and a pointer to itself:
 187           %v: <*>{1 <*><shown>}
 188          %+v: <*>(0xf84003e260){ui8:1 c:<*>(0xf84003e260)<shown>}
 189          %#v: (*main.circular){ui8:(uint8)1 c:(*main.circular)<shown>}
 190         %#+v: (*main.circular)(0xf84003e260){ui8:(uint8)1 c:(*main.circular)(0xf84003e260)<shown>}
 191
 192 See the Printf example for details on the setup of variables being shown
 193 here.
 194
 195 Errors
 196
 197 Since it is possible for custom Stringer/error interfaces to panic, spew
 198 detects them and handles them internally by printing the panic information
 199 inline with the output.  Since spew is intended to provide deep pretty printing
 200 capabilities on structures, it intentionally does not return any errors.
 201 */
 202 package spew