config.go (12842B)
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 "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. 37 type 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. 105 var 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)) 115 func (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)) 127 func (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)) 139 func (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)) 150 func (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)) 162 func (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)) 174 func (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)) 186 func (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)) 197 func (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)) 208 func (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)) 219 func (c *ConfigState) Sprintln(a ...interface{}) string { 220 return fmt.Sprintln(c.convertArgs(a)...) 221 } 222 223 /* 224 NewFormatter returns a custom formatter that satisfies the fmt.Formatter 225 interface. As a result, it integrates cleanly with standard fmt package 226 printing functions. The formatter is useful for inline printing of smaller data 227 types similar to the standard %v format specifier. 228 229 The custom formatter only responds to the %v (most compact), %+v (adds pointer 230 addresses), %#v (adds types), and %#+v (adds types and pointer addresses) verb 231 combinations. Any other verbs such as %x and %q will be sent to the the 232 standard fmt package for formatting. In addition, the custom formatter ignores 233 the width and precision arguments (however they will still work on the format 234 specifiers not handled by the custom formatter). 235 236 Typically this function shouldn't be called directly. It is much easier to make 237 use of the custom formatter by calling one of the convenience functions such as 238 c.Printf, c.Println, or c.Printf. 239 */ 240 func (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. 246 func (c *ConfigState) Fdump(w io.Writer, a ...interface{}) { 247 fdump(c, w, a...) 248 } 249 250 /* 251 Dump displays the passed parameters to standard out with newlines, customizable 252 indentation, and additional debug information such as complete types and all 253 pointer addresses used to indirect to the final value. It provides the 254 following features over the built-in printing facilities provided by the fmt 255 package: 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 267 The configuration options are controlled by modifying the public members 268 of c. See ConfigState for options documentation. 269 270 See Fdump if you would prefer dumping to an arbitrary io.Writer or Sdump to 271 get the formatted result as a string. 272 */ 273 func (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. 279 func (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. 288 func (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 304 func NewDefaultConfig() *ConfigState { 305 return &ConfigState{Indent: " "} 306 }