README
¶
Dapper
Dapper is a pretty-printer for Go values.
It is not intended to be used directly as a debugging tool, but as a library for applications that need to describe Go values to humans, such as testing frameworks.
Some features include:
- Concise formatting, without type ambiguity
- Deterministic output, useful for generating diffs using standard tools
- A filtering system for producing customized output on a per-value basis
Example
This example renders a basic tree structure. Note that the output only includes type names where the value's type can not be inferred from the context.
Code
package main
import (
"fmt"
"github.com/dogmatiq/dapper"
)
type TreeNode struct {
Name string
Value interface{}
Children []*TreeNode
}
type NodeValue struct{}
func main() {
v := TreeNode{
Name: "root",
Children: []*TreeNode{
{
Name: "branch #1",
Value: 100,
},
{
Name: "branch #2",
Value: NodeValue{},
},
},
}
dapper.Print(v)
}
Output
main.TreeNode{
Name: "root"
Value: nil
Children: {
{
Name: "branch #1"
Value: int(100)
Children: nil
}
{
Name: "branch #2"
Value: main.NodeValue{}
Children: nil
}
}
}
Documentation
¶
Overview ¶
Package dapper is a deterministic pretty-printer with minimal output.
Index ¶
Examples ¶
Constants ¶
const ( // DefaultIndent is the default indent string used to indent nested values. DefaultIndent = " " // DefaultRecursionMarker is the default string to displayed when recursion is // detected within a Go value. DefaultRecursionMarker = "<recursion>" )
Variables ¶
This section is empty.
Functions ¶
func Format ¶
func Format(v interface{}) string
Format returns a pretty-printed representation of v.
Example ¶
s := Format(123) fmt.Println(s)
Output: int(123)
func Print ¶ added in v0.2.0
func Print(v interface{})
Print writes a pretty-printed representation of v to os.Stdout.
Example ¶
Print(123)
Output: int(123)
func ReflectTypeFilter ¶ added in v0.3.0
ReflectTypeFilter is a filter that formats reflect.Type values.
Types ¶
type Filter ¶ added in v0.3.0
Filter is a function that provides custom formatting logic for specific values.
It writes a formatted representation of v to w, and returns the number of bytes written.
If the number of bytes written is non-zero, the default formatting logic is skipped.
Particular attention should be paid to the v.IsUnexported field. If this flag is true, many operations on v.Value are unavailable.
type Printer ¶
type Printer struct {
// Filters is the set of filters to apply when formatting values.
Filters []Filter
// Indent is the string used to indent nested values.
// If it is empty, DefaultIndent is used.
Indent string
// RecursionMarker is a string that is displayed instead of a value's
// representation when recursion has been detected.
// If it is empty, DefaultRecursionMarker is used.
RecursionMarker string
}
Printer generates human-readable representations of Go values.
The output format is intended to be as minimal as possible, without being ambigious. To that end, type information is only included where it can not be reliably inferred from the structure of the value.
Example ¶
type TreeNode struct {
Name string
Value interface{}
Children []*TreeNode
}
type NodeValue struct{}
v := TreeNode{
Name: "root",
Children: []*TreeNode{
{
Name: "branch #1",
Value: 100,
},
{
Name: "branch #2",
Value: NodeValue{},
},
},
}
p := Printer{}
s := p.Format(v)
fmt.Println(s)
Output: dapper_test.TreeNode{ Name: "root" Value: nil Children: { { Name: "branch #1" Value: int(100) Children: nil } { Name: "branch #2" Value: dapper_test.NodeValue{} Children: nil } } }
type Value ¶ added in v0.3.0
type Value struct {
// Value is the value to be formatted.
Value reflect.Value
// DynamicType is the value's type.
DynamicType reflect.Type
// StaticType is the type of the "variable" that the value is stored in, which
// may not be the same as its dynamic type.
//
// For example, when formatting the values within a slice of interface{}
// containing integers, such as []interface{}{1, 2, 3}, the DynamicType will be
// "int", but the static type will be "interface{}".
StaticType reflect.Type
// IsAmbiguousDynamicType is true if the value's dynamic type is not clear from
// the context of what has already been rendered.
IsAmbiguousDynamicType bool
// IsAmbiguousStaticType is true if the value's static type is not clear from
// the context of what has already been rendered.
IsAmbiguousStaticType bool
// IsUnexported is true if this value was obtained from an unexported struct
// field. If so, it is not possible to extract the underlying value.
IsUnexported bool
}
Value contains information about a Go value that is to be formatted.
func (*Value) IsAmbiguousType ¶ added in v0.3.0
IsAmbiguousType returns true if either the dynamic type or the static type is ambiguous.
func (*Value) IsAnonymousType ¶ added in v0.3.0
IsAnonymousType returns true if the value has an anonymous type.
Source Files