Documentation
¶
Overview ¶
Package pretty pretty-prints Go structures.
This package uses reflection to examine a Go value and can print out in a nice, aligned fashion. It supports three modes (normal, compact, and extended) for advanced use.
See the Reflect and Print examples for what the output looks like.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
View Source
var ( // DefaultFormatter is the default set of overrides for stringification. DefaultFormatter = map[reflect.Type]interface{}{ reflect.TypeOf(time.Time{}): fmt.Sprint, reflect.TypeOf(net.IP{}): fmt.Sprint, reflect.TypeOf((*error)(nil)).Elem(): fmt.Sprint, } // CompareConfig is the default configuration used for Compare. CompareConfig = &Config{ Diffable: true, IncludeUnexported: true, Formatter: DefaultFormatter, } // DefaultConfig is the default configuration used for all other top-level functions. DefaultConfig = &Config{ Formatter: DefaultFormatter, } // CycleTracker is a convenience config for formatting and comparing recursive structures. CycleTracker = &Config{ Diffable: true, Formatter: DefaultFormatter, TrackCycles: true, } )
Default Config objects
Functions ¶
func Compare ¶
func Compare(a, b interface{}) string
Compare returns a string containing a line-by-line unified diff of the values in a and b, using the CompareConfig.
Each line in the output is prefixed with '+', '-', or ' ' to indicate which side it's from. Lines from the a side are marked with '-', lines from the b side are marked with '+' and lines that are the same on both sides are marked with ' '.
The comparison is based on the intentionally-untyped output of Print, and as such this comparison is pretty forviving. In particular, if the types of or types within in a and b are different but have the same representation, Compare will not indicate any differences between them.
Example (Debugging) ¶
package main
import (
"fmt"
"github.com/kylelemons/godebug/pretty"
)
func main() {
type ShipManifest struct {
Name string
Crew map[string]string
Androids int
Stolen bool
}
reported := &ShipManifest{
Name: "Spaceship Heart of Gold",
Crew: map[string]string{
"Zaphod Beeblebrox": "Galactic President",
"Trillian": "Human",
"Ford Prefect": "A Hoopy Frood",
"Arthur Dent": "Along for the Ride",
},
Androids: 1,
Stolen: true,
}
expected := &ShipManifest{
Name: "Spaceship Heart of Gold",
Crew: map[string]string{
"Trillian": "Human",
"Rowan Artosok": "Captain",
},
Androids: 1,
Stolen: false,
}
fmt.Println(pretty.Compare(reported, expected))
}
Output: { Name: "Spaceship Heart of Gold", Crew: { - Arthur Dent: "Along for the Ride", - Ford Prefect: "A Hoopy Frood", + Rowan Artosok: "Captain", Trillian: "Human", - Zaphod Beeblebrox: "Galactic President", }, Androids: 1, - Stolen: true, + Stolen: false, }
Example (Testing) ¶
package main
import (
"fmt"
"github.com/kylelemons/godebug/pretty"
)
var t = struct {
Errorf func(string, ...interface{})
}{
Errorf: func(format string, args ...interface{}) {
fmt.Println(fmt.Sprintf(format, args...) + "\n")
},
}
func main() {
// Code under test:
type ShipManifest struct {
Name string
Crew map[string]string
Androids int
Stolen bool
}
// AddCrew tries to add the given crewmember to the manifest.
AddCrew := func(m *ShipManifest, name, title string) {
if m.Crew == nil {
m.Crew = make(map[string]string)
}
m.Crew[title] = name
}
// Test function:
tests := []struct {
desc string
before *ShipManifest
name, title string
after *ShipManifest
}{
{
desc: "add first",
before: &ShipManifest{},
name: "Zaphod Beeblebrox",
title: "Galactic President",
after: &ShipManifest{
Crew: map[string]string{
"Zaphod Beeblebrox": "Galactic President",
},
},
},
{
desc: "add another",
before: &ShipManifest{
Crew: map[string]string{
"Zaphod Beeblebrox": "Galactic President",
},
},
name: "Trillian",
title: "Human",
after: &ShipManifest{
Crew: map[string]string{
"Zaphod Beeblebrox": "Galactic President",
"Trillian": "Human",
},
},
},
{
desc: "overwrite",
before: &ShipManifest{
Crew: map[string]string{
"Zaphod Beeblebrox": "Galactic President",
},
},
name: "Zaphod Beeblebrox",
title: "Just this guy, you know?",
after: &ShipManifest{
Crew: map[string]string{
"Zaphod Beeblebrox": "Just this guy, you know?",
},
},
},
}
for _, test := range tests {
AddCrew(test.before, test.name, test.title)
if diff := pretty.Compare(test.before, test.after); diff != "" {
t.Errorf("%s: post-AddCrew diff: (-got +want)\n%s", test.desc, diff)
}
}
}
Output: add first: post-AddCrew diff: (-got +want) { Name: "", Crew: { - Galactic President: "Zaphod Beeblebrox", + Zaphod Beeblebrox: "Galactic President", }, Androids: 0, Stolen: false, } add another: post-AddCrew diff: (-got +want) { Name: "", Crew: { - Human: "Trillian", + Trillian: "Human", Zaphod Beeblebrox: "Galactic President", }, Androids: 0, Stolen: false, } overwrite: post-AddCrew diff: (-got +want) { Name: "", Crew: { - Just this guy, you know?: "Zaphod Beeblebrox", - Zaphod Beeblebrox: "Galactic President", + Zaphod Beeblebrox: "Just this guy, you know?", }, Androids: 0, Stolen: false, }
Example (WithCycles) ¶
package main
import (
"fmt"
"github.com/kylelemons/godebug/pretty"
)
type ListNode struct {
Value int
Next *ListNode
}
func circular(nodes int) *ListNode {
final := &ListNode{
Value: nodes,
}
final.Next = final
recent := final
for i := nodes - 1; i > 0; i-- {
n := &ListNode{
Value: i,
Next: recent,
}
final.Next = n
recent = n
}
return recent
}
func main() {
got, want := circular(3), circular(3)
// Make the got one broken
got.Next.Next.Next = got.Next
fmt.Printf("Diff: (-got +want)\n%s", pretty.CycleTracker.Compare(got, want))
}
Output: Diff: (-got +want) -{ +<#1> { Value: 1, - Next: <#1> { + Next: { Value: 2, Next: { Value: 3, Next: <see #1>, }, }, }
func Fprint ¶
Fprint writes the representation of the given value to the writer according to the DefaultConfig.
func Print ¶
func Print(vals ...interface{})
Print writes the DefaultConfig representation of the given values to standard output.
Example ¶
package main
import (
"github.com/kylelemons/godebug/pretty"
)
func main() {
type ShipManifest struct {
Name string
Crew map[string]string
Androids int
Stolen bool
}
manifest := &ShipManifest{
Name: "Spaceship Heart of Gold",
Crew: map[string]string{
"Zaphod Beeblebrox": "Galactic President",
"Trillian": "Human",
"Ford Prefect": "A Hoopy Frood",
"Arthur Dent": "Along for the Ride",
},
Androids: 1,
Stolen: true,
}
pretty.Print(manifest)
}
Output: {Name: "Spaceship Heart of Gold", Crew: {Arthur Dent: "Along for the Ride", Ford Prefect: "A Hoopy Frood", Trillian: "Human", Zaphod Beeblebrox: "Galactic President"}, Androids: 1, Stolen: true}
Example (WithCycles) ¶
package main
import (
"github.com/kylelemons/godebug/pretty"
)
type ListNode struct {
Value int
Next *ListNode
}
func circular(nodes int) *ListNode {
final := &ListNode{
Value: nodes,
}
final.Next = final
recent := final
for i := nodes - 1; i > 0; i-- {
n := &ListNode{
Value: i,
Next: recent,
}
final.Next = n
recent = n
}
return recent
}
func main() {
pretty.CycleTracker.Print(circular(3))
}
Output: <#1> { Value: 1, Next: { Value: 2, Next: { Value: 3, Next: <see #1>, }, }, }
Types ¶
type Config ¶
type Config struct {
// Verbosity options
Compact bool // One-line output. Overrides Diffable.
Diffable bool // Adds extra newlines for more easily diffable output.
// Field and value options
IncludeUnexported bool // Include unexported fields in output
PrintStringers bool // Call String on a fmt.Stringer
PrintTextMarshalers bool // Call MarshalText on an encoding.TextMarshaler
SkipZeroFields bool // Skip struct fields that have a zero value.
// Output transforms
ShortList int // Maximum character length for short lists if nonzero.
// Type-specific overrides
//
// Formatter maps a type to a function that will provide a one-line string
// representation of the input value. Conceptually:
// Formatter[reflect.TypeOf(v)](v) = "v as a string"
//
// Note that the first argument need not explicitly match the type, it must
// merely be callable with it.
//
// When processing an input value, if its type exists as a key in Formatter:
// 1) If the value is nil, no stringification is performed.
// This allows overriding of PrintStringers and PrintTextMarshalers.
// 2) The value will be called with the input as its only argument.
// The function must return a string as its first return value.
//
// In addition to func literals, two common values for this will be:
// fmt.Sprint (function) func Sprint(...interface{}) string
// Type.String (method) func (Type) String() string
//
// Note that neither of these work if the String method is a pointer
// method and the input will be provided as a value. In that case,
// use a function that calls .String on the formal value parameter.
Formatter map[reflect.Type]interface{}
// If TrackCycles is enabled, pretty will detect and track
// self-referential structures. If a self-referential structure (aka a
// "recursive" value) is detected, numbered placeholders will be emitted.
//
// Pointer tracking is disabled by default for performance reasons.
TrackCycles bool
}
A Config represents optional configuration parameters for formatting.
Some options, notably ShortList, dramatically increase the overhead of pretty-printing a value.
Example (CustomFormatter) ¶
package main
import (
"fmt"
"net"
"reflect"
"github.com/kylelemons/godebug/pretty"
)
func main() {
pretty.DefaultFormatter[reflect.TypeOf(&net.IPNet{})] = func(n *net.IPNet) string {
return fmt.Sprintf("CIDR=%s", n)
}
pretty.Print(&net.IPNet{
IP: net.IPv4(192, 168, 1, 100),
Mask: net.CIDRMask(24, 32),
})
}
Output: CIDR=192.168.1.100/24
Example (FmtFormatter) ¶
package main
import (
"fmt"
"net"
"reflect"
"github.com/kylelemons/godebug/pretty"
)
func main() {
pretty.DefaultFormatter[reflect.TypeOf(&net.IPNet{})] = fmt.Sprint
pretty.DefaultFormatter[reflect.TypeOf(net.HardwareAddr{})] = fmt.Sprint
pretty.Print(&net.IPNet{
IP: net.IPv4(192, 168, 1, 100),
Mask: net.CIDRMask(24, 32),
})
pretty.Print(net.HardwareAddr{1, 2, 3, 4, 5, 6})
}
Output: 192.168.1.100/24 01:02:03:04:05:06
func (*Config) Compare ¶
Compare returns a string containing a line-by-line unified diff of the values in got and want according to the cfg.
Each line in the output is prefixed with '+', '-', or ' ' to indicate which side it's from. Lines from the a side are marked with '-', lines from the b side are marked with '+' and lines that are the same on both sides are marked with ' '.
The comparison is based on the intentionally-untyped output of Print, and as such this comparison is pretty forviving. In particular, if the types of or types within in a and b are different but have the same representation, Compare will not indicate any differences between them.
func (*Config) Fprint ¶
Fprint writes the representation of the given value to the writer according to the cfg.
func (*Config) Print ¶
func (cfg *Config) Print(vals ...interface{})
Print writes the configured presentation of the given values to standard output.
func (*Config) Sprint ¶
Sprint returns a string representation of the given value according to cfg.
Example ¶
package main
import (
"fmt"
"github.com/kylelemons/godebug/pretty"
)
func main() {
type Pair [2]int
type Map struct {
Name string
Players map[string]Pair
Obstacles map[Pair]string
}
m := Map{
Name: "Rock Creek",
Players: map[string]Pair{
"player1": {1, 3},
"player2": {0, -1},
},
Obstacles: map[Pair]string{
Pair{0, 0}: "rock",
Pair{2, 1}: "pond",
Pair{1, 1}: "stream",
Pair{0, 1}: "stream",
},
}
// Specific output formats
compact := &pretty.Config{
Compact: true,
}
diffable := &pretty.Config{
Diffable: true,
}
// Print out a summary
fmt.Printf("Players: %s\n", compact.Sprint(m.Players))
// Print diffable output
fmt.Printf("Map State:\n%s", diffable.Sprint(m))
}
Output: Players: {player1:[1,3],player2:[0,-1]} Map State: { Name: "Rock Creek", Players: { player1: [ 1, 3, ], player2: [ 0, -1, ], }, Obstacles: { [0,0]: "rock", [0,1]: "stream", [1,1]: "stream", [2,1]: "pond", }, }
Source Files
Click to show internal directories.
Click to hide internal directories.