reveal

README

reveal

A modern, maintained, and bug-fixed deep pretty printer for Go data structures. Drop-in replacement for go-spew.

Installation

go get github.com/agentine/reveal

Quick Start

import "github.com/agentine/reveal"

reveal.Dump(myStruct)          // print to stdout
s := reveal.Sdump(myStruct)    // return as string
reveal.Fdump(w, myStruct)      // print to io.Writer

Example output:

(main.Person) {
 Name: (string) (len=5) "Alice",
 Age: (int) 30,
 Addr: (*main.Address)(0xc0000b4000)(
  (main.Address) {
   City: (string) (len=10) "Wonderland"
  })
}

Migration from go-spew

Change one import — nothing else needs to change:

// Before
import "github.com/davecgh/go-spew/spew"
spew.Dump(myStruct)

// After
import "github.com/agentine/reveal"
reveal.Dump(myStruct)

Output format is identical by default. All go-spew API functions (Dump, Sdump, Fdump, Sprint, Sprintf, Sprintln, Fprint, Fprintf, Fprintln, NewFormatter) are supported, with the same signatures.

API

Package-level functions

All functions use the default Config. Each function is also available as a method on ConfigState for custom configurations.

Function	Description
Dump(a ...)	Print to stdout
Sdump(a ...) string	Return as string
Fdump(w, a ...)	Print to io.Writer
Sprint(a ...) string	Deep-aware fmt.Sprint
Sprintf(format, a ...) string	Deep-aware fmt.Sprintf
Sprintln(a ...) string	Deep-aware fmt.Sprintln
Fprint(w, a ...) (int, error)	Deep-aware fmt.Fprint
Fprintf(w, format, a ...) (int, error)	Deep-aware fmt.Fprintf
Fprintln(w, a ...) (int, error)	Deep-aware fmt.Fprintln
Printf(format, a ...) (int, error)	Deep-aware fmt.Printf
Println(a ...) (int, error)	Deep-aware fmt.Println
NewFormatter(v) fmt.Formatter	Wrap value for use with fmt verbs

fmt verb support

Values wrapped with NewFormatter support these verbs:

Verb	Output
%v	Standard fmt value format
%+v	Dump format with field names
%#v	Go-syntax representation
%d	Dump format (same as Dump output)
%s	Dump format as string

Configuration

Modify the global default:

reveal.Config.MaxDepth = 5
reveal.Config.SortKeys = true
reveal.Config.Dump(myStruct)

Or create an isolated configuration:

c := reveal.ConfigState{
    Indent:   "    ",
    SortKeys: true,
    MaxDepth: 3,
}
c.Dump(myStruct)

Field	Default	Description
Indent	" "	Indentation string per level
MaxDepth	0	Max recursion depth (0 = unlimited)
DisableMethods	false	Skip Stringer/Error methods
DisablePointerMethods	false	Skip pointer receiver methods
DisablePointerAddresses	false	Hide pointer addresses
DisableCapacities	false	Hide slice capacities
ContinueOnMethod	false	Show internals after method output
SortKeys	false	Sort map keys for deterministic output
SpewKeys	false	Use dump format for map keys
MaxSize	10485760 (10 MB)	Max output bytes (0 = unlimited)
RecoverPanics	true	Recover from Stringer/Error panics
OmitNilPointers	false	Suppress nil pointer struct fields
OmitUnexported	false	Suppress unexported struct fields
HexIntegers	false	Format integers as hexadecimal

Safety Features

MaxSize (default 10 MB): Output is truncated and a notice appended once the byte limit is reached. Prevents memory exhaustion when dumping deeply nested or self-referential structures.

RecoverPanics (default true): All Stringer and error method calls are wrapped in a deferred recover. If a method panics, reveal falls back to raw value output and includes <panic in method: ...> in the output rather than crashing the caller. Set to false to let panics propagate (useful in tests).

Bug Fixes vs go-spew

Issue	Description	Fix
#145	Memory exhaustion on deeply nested structures	MaxSize output limit (default 10 MB)
#141	Panic with custom Stringer on map values	RecoverPanics safe method invocation
#115	Panic with custom Stringer on maps	RecoverPanics safe method invocation
#144	Panic with wrapped custom errors	Panic recovery covers error.Error() calls
#108	Panic sorting maps with unexported field keys	Safe key comparison logic
—	Stringer recursion loop	Detected and broken automatically (pointer and type-depth tracking)

Build Tags

By default, reveal uses unsafe reflection to access unexported struct fields (same technique as go-spew). To disable this:

go build -tags safe ./...
# or
go build -tags disableunsafe ./...

With either tag, unexported fields are shown as <unexported> instead of their values.

License

MIT

Documentation

Overview

Package reveal is a deep pretty printer for Go data structures.

It is a modern, maintained, and bug-fixed replacement for github.com/davecgh/go-spew. The API is fully compatible with go-spew — change the import path and everything works.

Basic usage:

reveal.Dump(myStruct)          // print to stdout
s := reveal.Sdump(myStruct)    // return as string
reveal.Fdump(w, myStruct)      // print to io.Writer

Configuration:

config := reveal.Config
config.MaxDepth = 5
config.Dump(myStruct)

Index

• Variables
• func Dump(a ...interface{})
• func Fdump(w io.Writer, a ...interface{})
• func Fprint(w io.Writer, a ...interface{}) (int, error)
• func Fprintf(w io.Writer, format string, a ...interface{}) (int, error)
• func Fprintln(w io.Writer, a ...interface{}) (int, error)
• func NewFormatter(v interface{}) fmt.Formatter
• func Printf(format string, a ...interface{}) (int, error)
• func Println(a ...interface{}) (int, error)
• func Sdump(a ...interface{}) string
• func Sprint(a ...interface{}) string
• func Sprintf(format string, a ...interface{}) string
• func Sprintln(a ...interface{}) string
• type ConfigState
  • func (c *ConfigState) Dump(a ...interface{})
  • func (c *ConfigState) Fdump(w io.Writer, a ...interface{})
  • func (c *ConfigState) Fprint(w io.Writer, a ...interface{}) (int, error)
  • func (c *ConfigState) Fprintf(w io.Writer, format string, a ...interface{}) (int, error)
  • func (c *ConfigState) Fprintln(w io.Writer, a ...interface{}) (int, error)
  • func (c *ConfigState) NewFormatter(v interface{}) fmt.Formatter
  • func (c *ConfigState) Sdump(a ...interface{}) string
  • func (c *ConfigState) Sprint(a ...interface{}) string
  • func (c *ConfigState) Sprintf(format string, a ...interface{}) string
  • func (c *ConfigState) Sprintln(a ...interface{}) string

Variables

var Config = ConfigState{
	Indent:        " ",
	MaxSize:       10 * 1024 * 1024,
	RecoverPanics: true,
}

Config is the active default configuration for reveal. Modify this to change the default behavior of package-level functions.

Functions

func Dump

func Dump(a ...interface{})

Dump displays the passed parameters to standard output with type info, pointer addresses, and nested structure. It uses the default configuration.

func Fdump

func Fdump(w io.Writer, a ...interface{})

Fdump formats and writes the passed parameters to the given io.Writer. It uses the default configuration.

func Fprint

func Fprint(w io.Writer, a ...interface{}) (int, error)

Fprint is a deep-aware replacement for fmt.Fprint.

func Fprintf

func Fprintf(w io.Writer, format string, a ...interface{}) (int, error)

Fprintf is a deep-aware replacement for fmt.Fprintf.

func Fprintln

func Fprintln(w io.Writer, a ...interface{}) (int, error)

Fprintln is a deep-aware replacement for fmt.Fprintln.

func NewFormatter

func NewFormatter(v interface{}) fmt.Formatter

NewFormatter returns a fmt.Formatter that formats the given value using reveal. The returned Formatter supports the following verbs:

%v   — inline format (same as fmt %v but with deep traversal)
%+v  — inline format with field names (for structs)
%#v  — Go-syntax representation
%d   — dump format (same as Dump output)

Use it with fmt.Sprintf, fmt.Fprintf, etc:

fmt.Sprintf("%v", reveal.NewFormatter(myStruct))

func Printf

func Printf(format string, a ...interface{}) (int, error)

Printf is a deep-aware replacement for fmt.Printf.

func Println

func Println(a ...interface{}) (int, error)

Println is a deep-aware replacement for fmt.Println.

func Sdump

func Sdump(a ...interface{}) string

Sdump returns a string with the passed parameters formatted using Dump style. It uses the default configuration.

func Sprint

func Sprint(a ...interface{}) string

Sprint is a deep-aware replacement for fmt.Sprint.

func Sprintf

func Sprintf(format string, a ...interface{}) string

Sprintf is a deep-aware replacement for fmt.Sprintf.

func Sprintln

func Sprintln(a ...interface{}) string

Sprintln is a deep-aware replacement for fmt.Sprintln.

Types

type ConfigState

type ConfigState struct {
	// Indent specifies the string to use for each indentation level. Default: " " (single space).
	Indent string

	// MaxDepth controls the maximum depth to recurse into nested types. 0 means unlimited.
	MaxDepth int

	// DisableMethods disables invocation of error and Stringer interface methods.
	DisableMethods bool

	// DisablePointerMethods disables invocation of error and Stringer interface
	// methods on pointer receivers. This only applies when DisableMethods is false.
	DisablePointerMethods bool

	// DisablePointerAddresses disables printing of pointer addresses.
	DisablePointerAddresses bool

	// DisableCapacities disables printing of capacities for arrays, slices, and maps.
	DisableCapacities bool

	// ContinueOnMethod causes the dump to continue after calling a Stringer/Error method,
	// showing the internal structure as well.
	ContinueOnMethod bool

	// SortKeys causes map keys to be sorted before printing to produce deterministic output.
	SortKeys bool

	// SpewKeys causes map keys to be formatted using the Dump format for the key.
	SpewKeys bool

	// MaxSize is the maximum number of bytes the output may be. 0 means unlimited.
	// Default: 10485760 (10 MB). Prevents memory exhaustion with deeply nested structures.
	MaxSize int

	// RecoverPanics causes reveal to recover from panics in Stringer/Error methods
	// and fall back to raw value dumping. Default: true.
	RecoverPanics bool

	// OmitNilPointers suppresses nil pointer fields in struct output.
	OmitNilPointers bool

	// OmitUnexported suppresses unexported struct fields from output.
	OmitUnexported bool

	// HexIntegers formats integer values in hexadecimal.
	HexIntegers bool
}

ConfigState holds the configuration options for reveal. All go-spew compatible fields are supported, plus additional reveal-only fields.

func (*ConfigState) Dump

func (c *ConfigState) Dump(a ...interface{})

Dump displays the passed parameters to standard output with type info, pointer addresses, and nested structure using the configuration options in c.

func (*ConfigState) Fdump

func (c *ConfigState) Fdump(w io.Writer, a ...interface{})

Fdump formats and writes the passed parameters to the given io.Writer.

func (*ConfigState) Fprint

func (c *ConfigState) Fprint(w io.Writer, a ...interface{}) (int, error)

Fprint is a deep-aware replacement for fmt.Fprint.

func (*ConfigState) Fprintf

func (c *ConfigState) Fprintf(w io.Writer, format string, a ...interface{}) (int, error)

Fprintf is a deep-aware replacement for fmt.Fprintf.

func (*ConfigState) Fprintln

func (c *ConfigState) Fprintln(w io.Writer, a ...interface{}) (int, error)

Fprintln is a deep-aware replacement for fmt.Fprintln.

func (*ConfigState) NewFormatter

func (c *ConfigState) NewFormatter(v interface{}) fmt.Formatter

NewFormatter returns a fmt.Formatter bound to this ConfigState.

func (*ConfigState) Sdump

func (c *ConfigState) Sdump(a ...interface{}) string

Sdump returns a string with the passed parameters formatted using Dump style.

func (*ConfigState) Sprint

func (c *ConfigState) Sprint(a ...interface{}) string

Sprint is a deep-aware replacement for fmt.Sprint. Each argument is formatted using reveal's dump traversal.

func (*ConfigState) Sprintf

func (c *ConfigState) Sprintf(format string, a ...interface{}) string

Sprintf is a deep-aware replacement for fmt.Sprintf. Arguments referenced by format verbs are formatted using reveal's deep traversal.

func (*ConfigState) Sprintln

func (c *ConfigState) Sprintln(a ...interface{}) string

Sprintln is a deep-aware replacement for fmt.Sprintln.