github.com/kortschak/utter@v1.5.0/doc.go (about)

     1  /*
     2   * Copyright (c) 2013 Dave Collins <dave@davec.name>
     3   * Copyright (c) 2015 Dan Kortschak <dan.kortschak@adelaide.edu.au>
     4   *
     5   * Permission to use, copy, modify, and distribute this software for any
     6   * purpose with or without fee is hereby granted, provided that the above
     7   * copyright notice and this permission notice appear in all copies.
     8   *
     9   * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
    10   * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
    11   * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
    12   * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
    13   * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
    14   * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
    15   * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
    16   */
    17  
    18  /*
    19  Package utter implements a deep pretty printer for Go data structures to aid
    20  data snapshotting.
    21  
    22  A quick overview of the additional features utter provides over the built-in
    23  printing facilities for Go data types are as follows:
    24  
    25  	* Pointers are dereferenced and followed
    26  	* Circular data structures are detected and annotated
    27  	* Byte arrays and slices are dumped in a way similar to the hexdump -C command
    28  	  which includes byte values in hex, and ASCII output
    29  
    30  The approach utter allows for dumping Go data structures is less flexible than
    31  its parent tool. It has just a:
    32  
    33  	* Dump style which prints with newlines and customizable indentation
    34  
    35  Quick Start
    36  
    37  This section demonstrates how to quickly get started with utter. See the
    38  sections below for further details on formatting and configuration options.
    39  
    40  To dump a variable with full newlines, indentation, type, and pointer
    41  information use Dump, Fdump, or Sdump:
    42  	utter.Dump(myVar1)
    43  	utter.Fdump(someWriter, myVar1)
    44  	str := utter.Sdump(myVar1)
    45  
    46  Configuration Options
    47  
    48  Configuration of utter is handled by fields in the ConfigState type.  For
    49  convenience, all of the top-level functions use a global state available
    50  via the utter.Config global.
    51  
    52  It is also possible to create a ConfigState instance that provides methods
    53  equivalent to the top-level functions.  This allows concurrent configuration
    54  options.  See the ConfigState documentation for more details.
    55  
    56  The following configuration options are available:
    57  	* Indent
    58  		String to use for each indentation level for Dump functions.
    59  		It is a single space by default. A popular alternative is "\t".
    60  
    61  	* NumericWidth
    62  		NumericWidth specifies the number of columns to use when dumping
    63  		a numeric slice or array (including bool). Zero specifies all entries
    64  		on one line.
    65  
    66  	* StringWidth
    67  		StringWidth specifies the number of columns to use when dumping
    68  		a string slice or array. Zero specifies all entries on one line.
    69  
    70  	* BytesWidth
    71  		Number of byte columns to use when dumping byte slices and arrays.
    72  
    73  	* CommentBytes
    74  		Specifies whether ASCII comment annotations are attached to byte
    75  		slice and array dumps.
    76  
    77  	* CommentPointers
    78  		CommentPointers specifies whether pointer information will be added
    79  		as comments.
    80  
    81  	* IgnoreUnexported
    82  		Specifies that unexported fields should be ignored.
    83  
    84  	* ElideType
    85  		ElideType specifies that type information defined by context should
    86  		not be printed in a dump.
    87  
    88  	* SortKeys
    89  		Specifies map keys should be sorted before being printed. Use
    90  		this to have a more deterministic, diffable output.  Note that
    91  		only native types (bool, int, uint, floats, uintptr and string)
    92  		are supported with other types sorted according to the
    93  		reflect.Value.String() output which guarantees display stability.
    94  		Natural map order is used by default.
    95  
    96  Dump Usage
    97  
    98  Simply call utter.Dump with a list of variables you want to dump:
    99  
   100  	utter.Dump(myVar1)
   101  
   102  You may also call utter.Fdump if you would prefer to output to an arbitrary
   103  io.Writer.  For example, to dump to standard error:
   104  
   105  	utter.Fdump(os.Stderr, myVar1)
   106  
   107  A third option is to call utter.Sdump to get the formatted output as a string:
   108  
   109  	str := utter.Sdump(myVar1)
   110  
   111  Sample Dump Output
   112  
   113  See the Dump example for details on the setup of the types and variables being
   114  shown here.
   115  
   116  	main.Foo{
   117  	 unexportedField: &main.Bar{
   118  	  flag: main.Flag(1),
   119  	  data: uintptr(0),
   120  	 },
   121  	 ExportedField: map[interface{}]interface{}{
   122  	  string("one"): bool(true),
   123  	 },
   124  	}
   125  
   126  Byte (and uint8) arrays and slices are displayed uniquely, similar to the hexdump -C
   127  command as shown.
   128  
   129  	[]uint8{
   130  	 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, // |........|
   131  	 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20, // |....... |
   132  	 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28, // |!"#$%&'(|
   133  	 0x29, 0x2a, 0x2b, 0x2c, 0x2d, 0x2e, 0x2f, 0x30, // |)*+,-./0|
   134  	 0x31, 0x32,                                     // |12|
   135  	}
   136  */
   137  package utter