doc.go 8.3 KB

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