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 package spew
18 19 import (
20 "bytes"
21 "encoding/hex"
22 "fmt"
23 "io"
24 "os"
25 "reflect"
26 "regexp"
27 "strconv"
28 "strings"
29 )
30 31 var (
32 // uint8Type is a reflect.Type representing a uint8. It is used to
33 // convert cgo types to uint8 slices for hexdumping.
34 uint8Type = reflect.TypeOf(uint8(0))
35 36 // cCharRE is a regular expression that matches a cgo char.
37 // It is used to detect character arrays to hexdump them.
38 cCharRE = regexp.MustCompile(`^.*\._Ctype_char$`)
39 40 // cUnsignedCharRE is a regular expression that matches a cgo unsigned
41 // char. It is used to detect unsigned character arrays to hexdump
42 // them.
43 cUnsignedCharRE = regexp.MustCompile(`^.*\._Ctype_unsignedchar$`)
44 45 // cUint8tCharRE is a regular expression that matches a cgo uint8_t.
46 // It is used to detect uint8_t arrays to hexdump them.
47 cUint8tCharRE = regexp.MustCompile(`^.*\._Ctype_uint8_t$`)
48 )
49 50 // dumpState contains information about the state of a dump operation.
51 type dumpState struct {
52 w io.Writer
53 depth int
54 pointers map[uintptr]int
55 ignoreNextType bool
56 ignoreNextIndent bool
57 cs *ConfigState
58 }
59 60 // indent performs indentation according to the depth level and cs.Indent
61 // option.
62 func (d *dumpState) indent() {
63 if d.ignoreNextIndent {
64 d.ignoreNextIndent = false
65 return
66 }
67 d.w.Write(bytes.Repeat([]byte(d.cs.Indent), d.depth))
68 }
69 70 // unpackValue returns values inside of non-nil interfaces when possible.
71 // This is useful for data types like structs, arrays, slices, and maps which
72 // can contain varying types packed inside an interface.
73 func (d *dumpState) unpackValue(v reflect.Value) reflect.Value {
74 if v.Kind() == reflect.Interface && !v.IsNil() {
75 v = v.Elem()
76 }
77 return v
78 }
79 80 // dumpPtr handles formatting of pointers by indirecting them as necessary.
81 func (d *dumpState) dumpPtr(v reflect.Value) {
82 // Remove pointers at or below the current depth from map used to detect
83 // circular refs.
84 for k, depth := range d.pointers {
85 if depth >= d.depth {
86 delete(d.pointers, k)
87 }
88 }
89 90 // Keep list of all dereferenced pointers to show later.
91 pointerChain := make([]uintptr, 0)
92 93 // Figure out how many levels of indirection there are by dereferencing
94 // pointers and unpacking interfaces down the chain while detecting circular
95 // references.
96 nilFound := false
97 cycleFound := false
98 indirects := 0
99 ve := v
100 for ve.Kind() == reflect.Ptr {
101 if ve.IsNil() {
102 nilFound = true
103 break
104 }
105 indirects++
106 addr := ve.Pointer()
107 pointerChain = append(pointerChain, addr)
108 if pd, ok := d.pointers[addr]; ok && pd < d.depth {
109 cycleFound = true
110 indirects--
111 break
112 }
113 d.pointers[addr] = d.depth
114 115 ve = ve.Elem()
116 if ve.Kind() == reflect.Interface {
117 if ve.IsNil() {
118 nilFound = true
119 break
120 }
121 ve = ve.Elem()
122 }
123 }
124 125 // Display type information.
126 d.w.Write(openParenBytes)
127 d.w.Write(bytes.Repeat(asteriskBytes, indirects))
128 d.w.Write([]byte(ve.Type().String()))
129 d.w.Write(closeParenBytes)
130 131 // Display pointer information.
132 if !d.cs.DisablePointerAddresses && len(pointerChain) > 0 {
133 d.w.Write(openParenBytes)
134 for i, addr := range pointerChain {
135 if i > 0 {
136 d.w.Write(pointerChainBytes)
137 }
138 printHexPtr(d.w, addr)
139 }
140 d.w.Write(closeParenBytes)
141 }
142 143 // Display dereferenced value.
144 d.w.Write(openParenBytes)
145 switch {
146 case nilFound:
147 d.w.Write(nilAngleBytes)
148 149 case cycleFound:
150 d.w.Write(circularBytes)
151 152 default:
153 d.ignoreNextType = true
154 d.dump(ve)
155 }
156 d.w.Write(closeParenBytes)
157 }
158 159 // dumpSlice handles formatting of arrays and slices. Byte (uint8 under
160 // reflection) arrays and slices are dumped in hexdump -C fashion.
161 func (d *dumpState) dumpSlice(v reflect.Value) {
162 // Determine whether this type should be hex dumped or not. Also,
163 // for types which should be hexdumped, try to use the underlying data
164 // first, then fall back to trying to convert them to a uint8 slice.
165 var buf []uint8
166 doConvert := false
167 doHexDump := false
168 numEntries := v.Len()
169 if numEntries > 0 {
170 vt := v.Index(0).Type()
171 vts := vt.String()
172 switch {
173 // C types that need to be converted.
174 case cCharRE.MatchString(vts):
175 fallthrough
176 case cUnsignedCharRE.MatchString(vts):
177 fallthrough
178 case cUint8tCharRE.MatchString(vts):
179 doConvert = true
180 181 // Try to use existing uint8 slices and fall back to converting
182 // and copying if that fails.
183 case vt.Kind() == reflect.Uint8:
184 // We need an addressable interface to convert the type
185 // to a byte slice. However, the reflect package won't
186 // give us an interface on certain things like
187 // unexported struct fields in order to enforce
188 // visibility rules. We use unsafe, when available, to
189 // bypass these restrictions since this package does not
190 // mutate the values.
191 vs := v
192 if !vs.CanInterface() || !vs.CanAddr() {
193 vs = unsafeReflectValue(vs)
194 }
195 if !UnsafeDisabled {
196 vs = vs.Slice(0, numEntries)
197 198 // Use the existing uint8 slice if it can be
199 // type asserted.
200 iface := vs.Interface()
201 if slice, ok := iface.([]uint8); ok {
202 buf = slice
203 doHexDump = true
204 break
205 }
206 }
207 208 // The underlying data needs to be converted if it can't
209 // be type asserted to a uint8 slice.
210 doConvert = true
211 }
212 213 // Copy and convert the underlying type if needed.
214 if doConvert && vt.ConvertibleTo(uint8Type) {
215 // Convert and copy each element into a uint8 byte
216 // slice.
217 buf = make([]uint8, numEntries)
218 for i := 0; i < numEntries; i++ {
219 vv := v.Index(i)
220 buf[i] = uint8(vv.Convert(uint8Type).Uint())
221 }
222 doHexDump = true
223 }
224 }
225 226 // Hexdump the entire slice as needed.
227 if doHexDump {
228 indent := strings.Repeat(d.cs.Indent, d.depth)
229 str := indent + hex.Dump(buf)
230 str = strings.Replace(str, "\n", "\n"+indent, -1)
231 str = strings.TrimRight(str, d.cs.Indent)
232 d.w.Write([]byte(str))
233 return
234 }
235 236 // Recursively call dump for each item.
237 for i := 0; i < numEntries; i++ {
238 d.dump(d.unpackValue(v.Index(i)))
239 if i < (numEntries - 1) {
240 d.w.Write(commaNewlineBytes)
241 } else {
242 d.w.Write(newlineBytes)
243 }
244 }
245 }
246 247 // dump is the main workhorse for dumping a value. It uses the passed reflect
248 // value to figure out what kind of object we are dealing with and formats it
249 // appropriately. It is a recursive function, however circular data structures
250 // are detected and handled properly.
251 func (d *dumpState) dump(v reflect.Value) {
252 // Handle invalid reflect values immediately.
253 kind := v.Kind()
254 if kind == reflect.Invalid {
255 d.w.Write(invalidAngleBytes)
256 return
257 }
258 259 // Handle pointers specially.
260 if kind == reflect.Ptr {
261 d.indent()
262 d.dumpPtr(v)
263 return
264 }
265 266 // Print type information unless already handled elsewhere.
267 if !d.ignoreNextType {
268 d.indent()
269 d.w.Write(openParenBytes)
270 d.w.Write([]byte(v.Type().String()))
271 d.w.Write(closeParenBytes)
272 d.w.Write(spaceBytes)
273 }
274 d.ignoreNextType = false
275 276 // Display length and capacity if the built-in len and cap functions
277 // work with the value's kind and the len/cap itself is non-zero.
278 valueLen, valueCap := 0, 0
279 switch v.Kind() {
280 case reflect.Array, reflect.Slice, reflect.Chan:
281 valueLen, valueCap = v.Len(), v.Cap()
282 case reflect.Map, reflect.String:
283 valueLen = v.Len()
284 }
285 if valueLen != 0 || !d.cs.DisableCapacities && valueCap != 0 {
286 d.w.Write(openParenBytes)
287 if valueLen != 0 {
288 d.w.Write(lenEqualsBytes)
289 printInt(d.w, int64(valueLen), 10)
290 }
291 if !d.cs.DisableCapacities && valueCap != 0 {
292 if valueLen != 0 {
293 d.w.Write(spaceBytes)
294 }
295 d.w.Write(capEqualsBytes)
296 printInt(d.w, int64(valueCap), 10)
297 }
298 d.w.Write(closeParenBytes)
299 d.w.Write(spaceBytes)
300 }
301 302 // Call Stringer/error interfaces if they exist and the handle methods flag
303 // is enabled
304 if !d.cs.DisableMethods {
305 if (kind != reflect.Invalid) && (kind != reflect.Interface) {
306 if handled := handleMethods(d.cs, d.w, v); handled {
307 return
308 }
309 }
310 }
311 312 switch kind {
313 case reflect.Invalid:
314 // Do nothing. We should never get here since invalid has already
315 // been handled above.
316 317 case reflect.Bool:
318 printBool(d.w, v.Bool())
319 320 case reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64, reflect.Int:
321 printInt(d.w, v.Int(), 10)
322 323 case reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uint:
324 printUint(d.w, v.Uint(), 10)
325 326 case reflect.Float32:
327 printFloat(d.w, v.Float(), 32)
328 329 case reflect.Float64:
330 printFloat(d.w, v.Float(), 64)
331 332 case reflect.Complex64:
333 printComplex(d.w, v.Complex(), 32)
334 335 case reflect.Complex128:
336 printComplex(d.w, v.Complex(), 64)
337 338 case reflect.Slice:
339 if v.IsNil() {
340 d.w.Write(nilAngleBytes)
341 break
342 }
343 fallthrough
344 345 case reflect.Array:
346 d.w.Write(openBraceNewlineBytes)
347 d.depth++
348 if (d.cs.MaxDepth != 0) && (d.depth > d.cs.MaxDepth) {
349 d.indent()
350 d.w.Write(maxNewlineBytes)
351 } else {
352 d.dumpSlice(v)
353 }
354 d.depth--
355 d.indent()
356 d.w.Write(closeBraceBytes)
357 358 case reflect.String:
359 d.w.Write([]byte(strconv.Quote(v.String())))
360 361 case reflect.Interface:
362 // The only time we should get here is for nil interfaces due to
363 // unpackValue calls.
364 if v.IsNil() {
365 d.w.Write(nilAngleBytes)
366 }
367 368 case reflect.Ptr:
369 // Do nothing. We should never get here since pointers have already
370 // been handled above.
371 372 case reflect.Map:
373 // nil maps should be indicated as different than empty maps
374 if v.IsNil() {
375 d.w.Write(nilAngleBytes)
376 break
377 }
378 379 d.w.Write(openBraceNewlineBytes)
380 d.depth++
381 if (d.cs.MaxDepth != 0) && (d.depth > d.cs.MaxDepth) {
382 d.indent()
383 d.w.Write(maxNewlineBytes)
384 } else {
385 numEntries := v.Len()
386 keys := v.MapKeys()
387 if d.cs.SortKeys {
388 sortValues(keys, d.cs)
389 }
390 for i, key := range keys {
391 d.dump(d.unpackValue(key))
392 d.w.Write(colonSpaceBytes)
393 d.ignoreNextIndent = true
394 d.dump(d.unpackValue(v.MapIndex(key)))
395 if i < (numEntries - 1) {
396 d.w.Write(commaNewlineBytes)
397 } else {
398 d.w.Write(newlineBytes)
399 }
400 }
401 }
402 d.depth--
403 d.indent()
404 d.w.Write(closeBraceBytes)
405 406 case reflect.Struct:
407 d.w.Write(openBraceNewlineBytes)
408 d.depth++
409 if (d.cs.MaxDepth != 0) && (d.depth > d.cs.MaxDepth) {
410 d.indent()
411 d.w.Write(maxNewlineBytes)
412 } else {
413 vt := v.Type()
414 numFields := v.NumField()
415 for i := 0; i < numFields; i++ {
416 d.indent()
417 vtf := vt.Field(i)
418 d.w.Write([]byte(vtf.Name))
419 d.w.Write(colonSpaceBytes)
420 d.ignoreNextIndent = true
421 d.dump(d.unpackValue(v.Field(i)))
422 if i < (numFields - 1) {
423 d.w.Write(commaNewlineBytes)
424 } else {
425 d.w.Write(newlineBytes)
426 }
427 }
428 }
429 d.depth--
430 d.indent()
431 d.w.Write(closeBraceBytes)
432 433 case reflect.Uintptr:
434 printHexPtr(d.w, uintptr(v.Uint()))
435 436 case reflect.UnsafePointer, reflect.Chan, reflect.Func:
437 printHexPtr(d.w, v.Pointer())
438 439 // There were not any other types at the time this code was written, but
440 // fall back to letting the default fmt package handle it in case any new
441 // types are added.
442 default:
443 if v.CanInterface() {
444 fmt.Fprintf(d.w, "%v", v.Interface())
445 } else {
446 fmt.Fprintf(d.w, "%v", v.String())
447 }
448 }
449 }
450 451 // fdump is a helper function to consolidate the logic from the various public
452 // methods which take varying writers and config states.
453 func fdump(cs *ConfigState, w io.Writer, a ...interface{}) {
454 for _, arg := range a {
455 if arg == nil {
456 w.Write(interfaceBytes)
457 w.Write(spaceBytes)
458 w.Write(nilAngleBytes)
459 w.Write(newlineBytes)
460 continue
461 }
462 463 d := dumpState{w: w, cs: cs}
464 d.pointers = make(map[uintptr]int)
465 d.dump(reflect.ValueOf(arg))
466 d.w.Write(newlineBytes)
467 }
468 }
469 470 // Fdump formats and displays the passed arguments to io.Writer w. It formats
471 // exactly the same as Dump.
472 func Fdump(w io.Writer, a ...interface{}) {
473 fdump(&Config, w, a...)
474 }
475 476 // Sdump returns a string with the passed arguments formatted exactly the same
477 // as Dump.
478 func Sdump(a ...interface{}) string {
479 var buf bytes.Buffer
480 fdump(&Config, &buf, a...)
481 return buf.String()
482 }
483 484 /*
485 Dump displays the passed parameters to standard out with newlines, customizable
486 indentation, and additional debug information such as complete types and all
487 pointer addresses used to indirect to the final value. It provides the
488 following features over the built-in printing facilities provided by the fmt
489 package:
490 491 * Pointers are dereferenced and followed
492 * Circular data structures are detected and handled properly
493 * Custom Stringer/error interfaces are optionally invoked, including
494 on unexported types
495 * Custom types which only implement the Stringer/error interfaces via
496 a pointer receiver are optionally invoked when passing non-pointer
497 variables
498 * Byte arrays and slices are dumped like the hexdump -C command which
499 includes offsets, byte values in hex, and ASCII output
500 501 The configuration options are controlled by an exported package global,
502 spew.Config. See ConfigState for options documentation.
503 504 See Fdump if you would prefer dumping to an arbitrary io.Writer or Sdump to
505 get the formatted result as a string.
506 */
507 func Dump(a ...interface{}) {
508 fdump(&Config, os.Stdout, a...)
509 }
510