]>
Commit | Line | Data |
---|---|---|
bae9f6d2 JC |
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 |