blob: 2e3d22f312026ff2c863bbffcbc88b7f6fb942f5 [file] [log] [blame]
Andrea Campanella7167ebb2020-02-24 09:56:38 +01001/*
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
17package spew
18
19import (
20 "bytes"
21 "fmt"
22 "io"
23 "os"
24)
25
26// ConfigState houses the configuration options used by spew to format and
27// display values. There is a global instance, Config, that is used to control
28// all top-level Formatter and Dump functionality. Each ConfigState instance
29// provides methods equivalent to the top-level functions.
30//
31// The zero value for ConfigState provides no indentation. You would typically
32// want to set it to a space or a tab.
33//
34// Alternatively, you can use NewDefaultConfig to get a ConfigState instance
35// with default settings. See the documentation of NewDefaultConfig for default
36// values.
37type ConfigState struct {
38 // Indent specifies the string to use for each indentation level. The
39 // global config instance that all top-level functions use set this to a
40 // single space by default. If you would like more indentation, you might
41 // set this to a tab with "\t" or perhaps two spaces with " ".
42 Indent string
43
44 // MaxDepth controls the maximum number of levels to descend into nested
45 // data structures. The default, 0, means there is no limit.
46 //
47 // NOTE: Circular data structures are properly detected, so it is not
48 // necessary to set this value unless you specifically want to limit deeply
49 // nested data structures.
50 MaxDepth int
51
52 // DisableMethods specifies whether or not error and Stringer interfaces are
53 // invoked for types that implement them.
54 DisableMethods bool
55
56 // DisablePointerMethods specifies whether or not to check for and invoke
57 // error and Stringer interfaces on types which only accept a pointer
58 // receiver when the current type is not a pointer.
59 //
60 // NOTE: This might be an unsafe action since calling one of these methods
61 // with a pointer receiver could technically mutate the value, however,
62 // in practice, types which choose to satisify an error or Stringer
63 // interface with a pointer receiver should not be mutating their state
64 // inside these interface methods. As a result, this option relies on
65 // access to the unsafe package, so it will not have any effect when
66 // running in environments without access to the unsafe package such as
67 // Google App Engine or with the "safe" build tag specified.
68 DisablePointerMethods bool
69
70 // DisablePointerAddresses specifies whether to disable the printing of
71 // pointer addresses. This is useful when diffing data structures in tests.
72 DisablePointerAddresses bool
73
74 // DisableCapacities specifies whether to disable the printing of capacities
75 // for arrays, slices, maps and channels. This is useful when diffing
76 // data structures in tests.
77 DisableCapacities bool
78
79 // ContinueOnMethod specifies whether or not recursion should continue once
80 // a custom error or Stringer interface is invoked. The default, false,
81 // means it will print the results of invoking the custom error or Stringer
82 // interface and return immediately instead of continuing to recurse into
83 // the internals of the data type.
84 //
85 // NOTE: This flag does not have any effect if method invocation is disabled
86 // via the DisableMethods or DisablePointerMethods options.
87 ContinueOnMethod bool
88
89 // SortKeys specifies map keys should be sorted before being printed. Use
90 // this to have a more deterministic, diffable output. Note that only
91 // native types (bool, int, uint, floats, uintptr and string) and types
92 // that support the error or Stringer interfaces (if methods are
93 // enabled) are supported, with other types sorted according to the
94 // reflect.Value.String() output which guarantees display stability.
95 SortKeys bool
96
97 // SpewKeys specifies that, as a last resort attempt, map keys should
98 // be spewed to strings and sorted by those strings. This is only
99 // considered if SortKeys is true.
100 SpewKeys bool
101}
102
103// Config is the active configuration of the top-level functions.
104// The configuration can be changed by modifying the contents of spew.Config.
105var Config = ConfigState{Indent: " "}
106
107// Errorf is a wrapper for fmt.Errorf that treats each argument as if it were
108// passed with a Formatter interface returned by c.NewFormatter. It returns
109// the formatted string as a value that satisfies error. See NewFormatter
110// for formatting details.
111//
112// This function is shorthand for the following syntax:
113//
114// fmt.Errorf(format, c.NewFormatter(a), c.NewFormatter(b))
115func (c *ConfigState) Errorf(format string, a ...interface{}) (err error) {
116 return fmt.Errorf(format, c.convertArgs(a)...)
117}
118
119// Fprint is a wrapper for fmt.Fprint that treats each argument as if it were
120// passed with a Formatter interface returned by c.NewFormatter. It returns
121// the number of bytes written and any write error encountered. See
122// NewFormatter for formatting details.
123//
124// This function is shorthand for the following syntax:
125//
126// fmt.Fprint(w, c.NewFormatter(a), c.NewFormatter(b))
127func (c *ConfigState) Fprint(w io.Writer, a ...interface{}) (n int, err error) {
128 return fmt.Fprint(w, c.convertArgs(a)...)
129}
130
131// Fprintf is a wrapper for fmt.Fprintf that treats each argument as if it were
132// passed with a Formatter interface returned by c.NewFormatter. It returns
133// the number of bytes written and any write error encountered. See
134// NewFormatter for formatting details.
135//
136// This function is shorthand for the following syntax:
137//
138// fmt.Fprintf(w, format, c.NewFormatter(a), c.NewFormatter(b))
139func (c *ConfigState) Fprintf(w io.Writer, format string, a ...interface{}) (n int, err error) {
140 return fmt.Fprintf(w, format, c.convertArgs(a)...)
141}
142
143// Fprintln is a wrapper for fmt.Fprintln that treats each argument as if it
144// passed with a Formatter interface returned by c.NewFormatter. See
145// NewFormatter for formatting details.
146//
147// This function is shorthand for the following syntax:
148//
149// fmt.Fprintln(w, c.NewFormatter(a), c.NewFormatter(b))
150func (c *ConfigState) Fprintln(w io.Writer, a ...interface{}) (n int, err error) {
151 return fmt.Fprintln(w, c.convertArgs(a)...)
152}
153
154// Print is a wrapper for fmt.Print that treats each argument as if it were
155// passed with a Formatter interface returned by c.NewFormatter. It returns
156// the number of bytes written and any write error encountered. See
157// NewFormatter for formatting details.
158//
159// This function is shorthand for the following syntax:
160//
161// fmt.Print(c.NewFormatter(a), c.NewFormatter(b))
162func (c *ConfigState) Print(a ...interface{}) (n int, err error) {
163 return fmt.Print(c.convertArgs(a)...)
164}
165
166// Printf is a wrapper for fmt.Printf that treats each argument as if it were
167// passed with a Formatter interface returned by c.NewFormatter. It returns
168// the number of bytes written and any write error encountered. See
169// NewFormatter for formatting details.
170//
171// This function is shorthand for the following syntax:
172//
173// fmt.Printf(format, c.NewFormatter(a), c.NewFormatter(b))
174func (c *ConfigState) Printf(format string, a ...interface{}) (n int, err error) {
175 return fmt.Printf(format, c.convertArgs(a)...)
176}
177
178// Println is a wrapper for fmt.Println that treats each argument as if it were
179// passed with a Formatter interface returned by c.NewFormatter. It returns
180// the number of bytes written and any write error encountered. See
181// NewFormatter for formatting details.
182//
183// This function is shorthand for the following syntax:
184//
185// fmt.Println(c.NewFormatter(a), c.NewFormatter(b))
186func (c *ConfigState) Println(a ...interface{}) (n int, err error) {
187 return fmt.Println(c.convertArgs(a)...)
188}
189
190// Sprint is a wrapper for fmt.Sprint that treats each argument as if it were
191// passed with a Formatter interface returned by c.NewFormatter. It returns
192// the resulting string. See NewFormatter for formatting details.
193//
194// This function is shorthand for the following syntax:
195//
196// fmt.Sprint(c.NewFormatter(a), c.NewFormatter(b))
197func (c *ConfigState) Sprint(a ...interface{}) string {
198 return fmt.Sprint(c.convertArgs(a)...)
199}
200
201// Sprintf is a wrapper for fmt.Sprintf that treats each argument as if it were
202// passed with a Formatter interface returned by c.NewFormatter. It returns
203// the resulting string. See NewFormatter for formatting details.
204//
205// This function is shorthand for the following syntax:
206//
207// fmt.Sprintf(format, c.NewFormatter(a), c.NewFormatter(b))
208func (c *ConfigState) Sprintf(format string, a ...interface{}) string {
209 return fmt.Sprintf(format, c.convertArgs(a)...)
210}
211
212// Sprintln is a wrapper for fmt.Sprintln that treats each argument as if it
213// were passed with a Formatter interface returned by c.NewFormatter. It
214// returns the resulting string. See NewFormatter for formatting details.
215//
216// This function is shorthand for the following syntax:
217//
218// fmt.Sprintln(c.NewFormatter(a), c.NewFormatter(b))
219func (c *ConfigState) Sprintln(a ...interface{}) string {
220 return fmt.Sprintln(c.convertArgs(a)...)
221}
222
223/*
224NewFormatter returns a custom formatter that satisfies the fmt.Formatter
225interface. As a result, it integrates cleanly with standard fmt package
226printing functions. The formatter is useful for inline printing of smaller data
227types similar to the standard %v format specifier.
228
229The custom formatter only responds to the %v (most compact), %+v (adds pointer
230addresses), %#v (adds types), and %#+v (adds types and pointer addresses) verb
231combinations. Any other verbs such as %x and %q will be sent to the the
232standard fmt package for formatting. In addition, the custom formatter ignores
233the width and precision arguments (however they will still work on the format
234specifiers not handled by the custom formatter).
235
236Typically this function shouldn't be called directly. It is much easier to make
237use of the custom formatter by calling one of the convenience functions such as
238c.Printf, c.Println, or c.Printf.
239*/
240func (c *ConfigState) NewFormatter(v interface{}) fmt.Formatter {
241 return newFormatter(c, v)
242}
243
244// Fdump formats and displays the passed arguments to io.Writer w. It formats
245// exactly the same as Dump.
246func (c *ConfigState) Fdump(w io.Writer, a ...interface{}) {
247 fdump(c, w, a...)
248}
249
250/*
251Dump displays the passed parameters to standard out with newlines, customizable
252indentation, and additional debug information such as complete types and all
253pointer addresses used to indirect to the final value. It provides the
254following features over the built-in printing facilities provided by the fmt
255package:
256
257 * Pointers are dereferenced and followed
258 * Circular data structures are detected and handled properly
259 * Custom Stringer/error interfaces are optionally invoked, including
260 on unexported types
261 * Custom types which only implement the Stringer/error interfaces via
262 a pointer receiver are optionally invoked when passing non-pointer
263 variables
264 * Byte arrays and slices are dumped like the hexdump -C command which
265 includes offsets, byte values in hex, and ASCII output
266
267The configuration options are controlled by modifying the public members
268of c. See ConfigState for options documentation.
269
270See Fdump if you would prefer dumping to an arbitrary io.Writer or Sdump to
271get the formatted result as a string.
272*/
273func (c *ConfigState) Dump(a ...interface{}) {
274 fdump(c, os.Stdout, a...)
275}
276
277// Sdump returns a string with the passed arguments formatted exactly the same
278// as Dump.
279func (c *ConfigState) Sdump(a ...interface{}) string {
280 var buf bytes.Buffer
281 fdump(c, &buf, a...)
282 return buf.String()
283}
284
285// convertArgs accepts a slice of arguments and returns a slice of the same
286// length with each argument converted to a spew Formatter interface using
287// the ConfigState associated with s.
288func (c *ConfigState) convertArgs(args []interface{}) (formatters []interface{}) {
289 formatters = make([]interface{}, len(args))
290 for index, arg := range args {
291 formatters[index] = newFormatter(c, arg)
292 }
293 return formatters
294}
295
296// NewDefaultConfig returns a ConfigState with the following default settings.
297//
298// Indent: " "
299// MaxDepth: 0
300// DisableMethods: false
301// DisablePointerMethods: false
302// ContinueOnMethod: false
303// SortKeys: false
304func NewDefaultConfig() *ConfigState {
305 return &ConfigState{Indent: " "}
306}