本站源代码
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

510 lines
13KB

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