diff options
Diffstat (limited to 'vendor/github.com/davecgh/go-spew/spew/doc.go')
-rw-r--r-- | vendor/github.com/davecgh/go-spew/spew/doc.go | 211 |
1 files changed, 211 insertions, 0 deletions
diff --git a/vendor/github.com/davecgh/go-spew/spew/doc.go b/vendor/github.com/davecgh/go-spew/spew/doc.go new file mode 100644 index 0000000..aacaac6 --- /dev/null +++ b/vendor/github.com/davecgh/go-spew/spew/doc.go | |||
@@ -0,0 +1,211 @@ | |||
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 | ||