github.com/kortschak/utter@v1.5.0/README.md (about)

     1  utter
     2  =====
     3  
     4  [![Build Status](https://travis-ci.org/kortschak/utter.svg?branch=master)](https://travis-ci.org/kortschak/utter) [![Coverage Status](https://coveralls.io/repos/kortschak/utter/badge.svg?branch=master)](https://coveralls.io/r/kortschak/utter?branch=master)
     5  
     6  utter is a fork of the outstanding [go-spew tool](https://github.com/davecgh/go-spew).
     7  Where go-spew is an aid for debugging, providing annotation of dumped datastructures,
     8  utter is a tool for taking snapshots of data structures to include in tests or other
     9  code. An utter dump will not construct cyclic structure literals and a number of
    10  pseudo-code representations of pointer-based structures will require subsequent
    11  processing.
    12  
    13  A comprehensive suite of tests with near 100% test coverage is provided to ensure
    14  proper functionality. utter is licensed under the liberal ISC license, so it may
    15  be used in open source or commercial projects.
    16  
    17  ## Documentation
    18  
    19  [![GoDoc](https://godoc.org/github.com/kortschak/utter?status.svg)](http://godoc.org/github.com/kortschak/utter)
    20  
    21  Full `go doc` style documentation for the project can be viewed online without
    22  installing this package by using the excellent GoDoc site here:
    23  http://godoc.org/github.com/kortschak/utter
    24  
    25  You can also view the documentation locally once the package is installed with
    26  the `godoc` tool by running `godoc -http=":6060"` and pointing your browser to
    27  http://localhost:6060/pkg/github.com/kortschak/utter
    28  
    29  ## Installation
    30  
    31  ```bash
    32  $ go get -u github.com/kortschak/utter
    33  ```
    34  
    35  ## Quick Start
    36  
    37  To dump a variable with full newlines, indentation, type, and pointer
    38  information use Dump, Fdump, or Sdump:
    39  
    40  ```Go
    41  utter.Dump(myVar1)
    42  utter.Fdump(someWriter, myVar1)
    43  str := utter.Sdump(myVar1)
    44  ```
    45  
    46  ## Sample Dump Output
    47  
    48  ```
    49  main.Foo{
    50   unexportedField: &main.Bar{
    51    flag: main.Flag(1),
    52    data: uintptr(0),
    53   },
    54   ExportedField: map[interface{}]interface{}{
    55    string("one"): bool(true),
    56   },
    57  }
    58  ```
    59  
    60  ```
    61  []uint8{
    62   0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, // |........|
    63   0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20, // |....... |
    64   0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28, // |!"#$%&'(|
    65   0x29, 0x2a, 0x2b, 0x2c, 0x2d, 0x2e, 0x2f, 0x30, // |)*+,-./0|
    66   0x31, 0x32, /*                               */ // |12|
    67  }
    68  ```
    69  
    70  ## Configuration Options
    71  
    72  Configuration of utter is handled by fields in the ConfigState type. For
    73  convenience, all of the top-level functions use a global state available via the
    74  utter.Config global.
    75  
    76  It is also possible to create a ConfigState instance that provides methods
    77  equivalent to the top-level functions. This allows concurrent configuration
    78  options. See the ConfigState documentation for more details.
    79  
    80  ```
    81  * Indent
    82  	String to use for each indentation level for Dump functions.
    83  	It is a single space by default.  A popular alternative is "\t".
    84  
    85  * NumericWidth
    86  	NumericWidth specifies the number of columns to use when dumping
    87  	a numeric slice or array (including bool). Zero specifies all entries
    88  	on one line.
    89  
    90  * StringWidth
    91  	StringWidth specifies the number of columns to use when dumping
    92  	a string slice or array. Zero specifies all entries on one line.
    93  
    94  * BytesWidth
    95  	Number of byte columns to use when dumping byte slices and arrays.
    96  
    97  * CommentBytes
    98  	Specifies whether ASCII comment annotations are attached to byte
    99  	slice and array dumps.
   100  
   101  * CommentPointers
   102  	CommentPointers specifies whether pointer information will be added
   103  	as comments.
   104  
   105  * IgnoreUnexported
   106  	Specifies that unexported fields should be ignored.
   107  
   108  * ElideType
   109  	ElideType specifies that type information defined by context should
   110  	not be printed in a dump.
   111  
   112  * OmitZero specifies that zero values should not be printed in a dump.
   113  
   114  * SortKeys
   115  	Specifies map keys should be sorted before being printed. Use
   116  	this to have a more deterministic, diffable output.  Note that
   117  	only native types (bool, int, uint, floats, uintptr and string)
   118  	are supported with other types sorted according to the
   119  	reflect.Value.String() output which guarantees display stability.
   120  	Natural map order is used by default.
   121  ```
   122  
   123  ## License
   124  
   125  utter is licensed under the liberal ISC License.