doc.go (8527B)
1 /* 2 * Copyright (c) 2013-2016 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 * DisablePointerAddresses 95 DisablePointerAddresses specifies whether to disable the printing of 96 pointer addresses. This is useful when diffing data structures in tests. 97 98 * DisableCapacities 99 DisableCapacities specifies whether to disable the printing of 100 capacities for arrays, slices, maps and channels. This is useful when 101 diffing data structures in tests. 102 103 * ContinueOnMethod 104 Enables recursion into types after invoking error and Stringer interface 105 methods. Recursion after method invocation is disabled by default. 106 107 * SortKeys 108 Specifies map keys should be sorted before being printed. Use 109 this to have a more deterministic, diffable output. Note that 110 only native types (bool, int, uint, floats, uintptr and string) 111 and types which implement error or Stringer interfaces are 112 supported with other types sorted according to the 113 reflect.Value.String() output which guarantees display 114 stability. Natural map order is used by default. 115 116 * SpewKeys 117 Specifies that, as a last resort attempt, map keys should be 118 spewed to strings and sorted by those strings. This is only 119 considered if SortKeys is true. 120 121 Dump Usage 122 123 Simply call spew.Dump with a list of variables you want to dump: 124 125 spew.Dump(myVar1, myVar2, ...) 126 127 You may also call spew.Fdump if you would prefer to output to an arbitrary 128 io.Writer. For example, to dump to standard error: 129 130 spew.Fdump(os.Stderr, myVar1, myVar2, ...) 131 132 A third option is to call spew.Sdump to get the formatted output as a string: 133 134 str := spew.Sdump(myVar1, myVar2, ...) 135 136 Sample Dump Output 137 138 See the Dump example for details on the setup of the types and variables being 139 shown here. 140 141 (main.Foo) { 142 unexportedField: (*main.Bar)(0xf84002e210)({ 143 flag: (main.Flag) flagTwo, 144 data: (uintptr) <nil> 145 }), 146 ExportedField: (map[interface {}]interface {}) (len=1) { 147 (string) (len=3) "one": (bool) true 148 } 149 } 150 151 Byte (and uint8) arrays and slices are displayed uniquely like the hexdump -C 152 command as shown. 153 ([]uint8) (len=32 cap=32) { 154 00000000 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 20 |............... | 155 00000010 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 30 |!"#$%&'()*+,-./0| 156 00000020 31 32 |12| 157 } 158 159 Custom Formatter 160 161 Spew provides a custom formatter that implements the fmt.Formatter interface 162 so that it integrates cleanly with standard fmt package printing functions. The 163 formatter is useful for inline printing of smaller data types similar to the 164 standard %v format specifier. 165 166 The custom formatter only responds to the %v (most compact), %+v (adds pointer 167 addresses), %#v (adds types), or %#+v (adds types and pointer addresses) verb 168 combinations. Any other verbs such as %x and %q will be sent to the the 169 standard fmt package for formatting. In addition, the custom formatter ignores 170 the width and precision arguments (however they will still work on the format 171 specifiers not handled by the custom formatter). 172 173 Custom Formatter Usage 174 175 The simplest way to make use of the spew custom formatter is to call one of the 176 convenience functions such as spew.Printf, spew.Println, or spew.Printf. The 177 functions have syntax you are most likely already familiar with: 178 179 spew.Printf("myVar1: %v -- myVar2: %+v", myVar1, myVar2) 180 spew.Printf("myVar3: %#v -- myVar4: %#+v", myVar3, myVar4) 181 spew.Println(myVar, myVar2) 182 spew.Fprintf(os.Stderr, "myVar1: %v -- myVar2: %+v", myVar1, myVar2) 183 spew.Fprintf(os.Stderr, "myVar3: %#v -- myVar4: %#+v", myVar3, myVar4) 184 185 See the Index for the full list convenience functions. 186 187 Sample Formatter Output 188 189 Double pointer to a uint8: 190 %v: <**>5 191 %+v: <**>(0xf8400420d0->0xf8400420c8)5 192 %#v: (**uint8)5 193 %#+v: (**uint8)(0xf8400420d0->0xf8400420c8)5 194 195 Pointer to circular struct with a uint8 field and a pointer to itself: 196 %v: <*>{1 <*><shown>} 197 %+v: <*>(0xf84003e260){ui8:1 c:<*>(0xf84003e260)<shown>} 198 %#v: (*main.circular){ui8:(uint8)1 c:(*main.circular)<shown>} 199 %#+v: (*main.circular)(0xf84003e260){ui8:(uint8)1 c:(*main.circular)(0xf84003e260)<shown>} 200 201 See the Printf example for details on the setup of variables being shown 202 here. 203 204 Errors 205 206 Since it is possible for custom Stringer/error interfaces to panic, spew 207 detects them and handles them internally by printing the panic information 208 inline with the output. Since spew is intended to provide deep pretty printing 209 capabilities on structures, it intentionally does not return any errors. 210 */ 211 package spew