godump (goforj)

Feature Comparison: godump vs go-spew vs pp

Feature	godump	go-spew	pp
Zero dependencies	✓	-	-
Colorized terminal output	✓	✓	✓
HTML output	✓	-	-
JSON output helpers (DumpJSON, DumpJSONStr)	✓	-	-
Diff output helpers (Diff, DiffStr)	✓	-	-
Diff HTML output (DiffHTML)	✓	-	-
Dump to io.Writer	✓	✓	✓
Shows file + line number of dump call	✓	-	-
Cyclic reference detection	✓	~	-
Handles unexported struct fields	✓	✓	✓
Visibility markers (+ / -)	✓	-	-
Max depth control	✓	-	-
Max items (slice/map truncation)	✓	-	-
Max string length truncation	✓	-	-
Dump & Die (dd() equivalent)	✓	-	-
Control character escaping	✓	~	~
Supports structs, maps, slices, pointers, interfaces	✓	✓	✓
Pretty type name rendering (#package.Type)	✓	-	-
Builder-style configuration API	✓	-	-
Test-friendly string output (DumpStr, DiffStr, DumpJSONStr)	✓	✓	✓
HTML / Web UI debugging support	✓	-	-

If you'd like to suggest improvements or additional comparisons, feel free to open an issue or PR.

Installation

go get github.com/goforj/godump

Basic Usage

type User struct { Name string }
godump.Dump(User{Name: "Alice"})
// #main.User {
//    +Name => "Alice" #string
// }	

Extended Usage (Snippets)

godump.DumpStr(v)     // return as string
godump.DumpHTML(v)    // return HTML output
godump.DumpJSON(v)    // print JSON directly
godump.Fdump(w, v)    // write to io.Writer
godump.Dd(v)          // dump + exit
godump.Diff(a, b)     // diff two values
godump.DiffStr(a, b)  // diff two values as string
godump.DiffHTML(a, b) // diff two values as HTML

Diff Usage

type User struct {
    Name string
}
before := User{Name: "Alice"}
after := User{Name: "Bob"}
godump.Diff(before, after)
//   #main.User {
// -   +Name => "Alice" #string
// +   +Name => "Bob" #string
//   }

Builder Options Usage

godump aims for simple usage with sensible defaults out of the box, but also provides a flexible builder-style API for customization.

If you want to heavily customize the dumper behavior, you can create a Dumper instance with specific options:

godump.NewDumper(
    godump.WithMaxDepth(15),           // default: 15
    godump.WithMaxItems(100),          // default: 100
    godump.WithMaxStringLen(100000),   // default: 100000
    godump.WithWriter(os.Stdout),      // default: os.Stdout
    godump.WithSkipStackFrames(10),    // default: 10
    godump.WithDisableStringer(false), // default: false
    godump.WithoutColor(),             // default: false
).Dump(v)

Contributing

Ensure that all tests pass, and you run ./docs/generate.sh to update the API index in the README before submitting a PR.

Ensure all public functions have documentation blocks with examples, as these are used to generate runnable examples and the API index.

Runnable Examples Directory

Every function has a corresponding runnable example under ./examples.

These examples are generated directly from the documentation blocks of each function, ensuring the docs and code never drift. These are the same examples you see here in the README and GoDoc.

An automated test executes every example to verify it builds and runs successfully.

This guarantees all examples are valid, up-to-date, and remain functional as the API evolves.

godump output is designed for clarity and traceability. Here's how to interpret its structure:

Location Header

<#dump // main.go:26

• The first line shows the file and line number where godump.Dump() was invoked.
• Helpful for finding where the dump happened during debugging.

Type Names

#main.User

• Fully qualified struct name with its package path.

Visibility Markers

  +Name => "Alice"
  -secret  => "..."

• + → Exported (public) field
• - → Unexported (private) field (accessed reflectively)

Cyclic References

If a pointer has already been printed:

↩︎ &1

• Prevents infinite loops in circular structures
• References point back to earlier object instances

Slices and Maps

  0 => "value"
  a => 1

• Array/slice indices and map keys are shown with => formatting and indentation
• Slices and maps are truncated if maxItems is exceeded

Escaped Characters

"Line1\nLine2\tDone"

• Control characters like \n, \t, \r, etc. are safely escaped
• Strings are truncated after maxStringLen runes

Supported Types

• ✅ Structs (exported & unexported)
• ✅ Pointers, interfaces
• ✅ Maps, slices, arrays
• ✅ Channels, functions
• ✅ time.Time (nicely formatted)

API Index

Group	Functions
Builder	NewDumper
Diff	Diff DiffHTML DiffStr
Dump	Dd Dump DumpStr Fdump
HTML	DumpHTML
JSON	DumpJSON DumpJSONStr
Options	WithDisableStringer WithExcludeFields WithFieldMatchMode WithMaxDepth WithMaxItems WithMaxStringLen WithOnlyFields WithRedactFields WithRedactMatchMode WithRedactSensitive WithSkipStackFrames WithWriter WithoutColor WithoutHeader

Builder

NewDumper

NewDumper creates a new Dumper with the given options applied. Defaults are used for any setting not overridden.

v := map[string]int{"a": 1}
d := godump.NewDumper(
	godump.WithMaxDepth(10),
	godump.WithWriter(os.Stdout),
)
d.Dump(v)
// #map[string]int {
//   a => 1 #int
// }

Diff

Diff

Diff prints a diff between two values to stdout.

Example: print diff

a := map[string]int{"a": 1}
b := map[string]int{"a": 2}
godump.Diff(a, b)
// <#diff // path:line
// - #map[string]int {
// -   a => 1 #int
// - }
// + #map[string]int {
// +   a => 2 #int
// + }

Example: print diff with a custom dumper

d := godump.NewDumper()
a := map[string]int{"a": 1}
b := map[string]int{"a": 2}
d.Diff(a, b)
// <#diff // path:line
// - #map[string]int {
// -   a => 1 #int
// - }
// + #map[string]int {
// +   a => 2 #int
// + }

DiffHTML

DiffHTML returns an HTML diff between two values.

Example: HTML diff

a := map[string]int{"a": 1}
b := map[string]int{"a": 2}
html := godump.DiffHTML(a, b)
_ = html
// (html diff)

Example: HTML diff with a custom dumper

d := godump.NewDumper()
a := map[string]int{"a": 1}
b := map[string]int{"a": 2}
html := d.DiffHTML(a, b)
_ = html
// (html diff)

DiffStr

DiffStr returns a string diff between two values.

Example: diff string

a := map[string]int{"a": 1}
b := map[string]int{"a": 2}
out := godump.DiffStr(a, b)
_ = out
// <#diff // path:line
// - #map[string]int {
// -   a => 1 #int
// - }
// + #map[string]int {
// +   a => 2 #int
// + }

Example: diff string with a custom dumper

d := godump.NewDumper()
a := map[string]int{"a": 1}
b := map[string]int{"a": 2}
out := d.DiffStr(a, b)
_ = out
// <#diff // path:line
// - #map[string]int {
// -   a => 1 #int
// - }
// + #map[string]int {
// +   a => 2 #int
// + }

Dump

Dd

Dd is a debug function that prints the values and exits the program.

Example: dump and exit

v := map[string]int{"a": 1}
godump.Dd(v)
// #map[string]int {
//   a => 1 #int
// }

Example: dump and exit with a custom dumper

d := godump.NewDumper()
v := map[string]int{"a": 1}
d.Dd(v)
// #map[string]int {
//   a => 1 #int
// }

Dump

Dump prints the values to stdout with colorized output.

Example: print to stdout

v := map[string]int{"a": 1}
godump.Dump(v)
// #map[string]int {
//   a => 1 #int
// }

Example: print with a custom dumper

d := godump.NewDumper()
v := map[string]int{"a": 1}
d.Dump(v)
// #map[string]int {
//   a => 1 #int
// }

DumpStr

DumpStr returns a string representation of the values with colorized output.

Example: get a string dump

v := map[string]int{"a": 1}
out := godump.DumpStr(v)
godump.Dump(out)
// "#map[string]int {\n  a => 1 #int\n}" #string

Example: get a string dump with a custom dumper

d := godump.NewDumper()
v := map[string]int{"a": 1}
out := d.DumpStr(v)
_ = out
// "#map[string]int {\n  a => 1 #int\n}" #string

Fdump

Fdump writes the formatted dump of values to the given io.Writer.

var b strings.Builder
v := map[string]int{"a": 1}
godump.Fdump(&b, v)
// outputs to strings builder

HTML

DumpHTML

DumpHTML dumps the values as HTML with colorized output.

Example: dump HTML

v := map[string]int{"a": 1}
html := godump.DumpHTML(v)
_ = html
// (html output)

Example: dump HTML with a custom dumper

d := godump.NewDumper()
v := map[string]int{"a": 1}
html := d.DumpHTML(v)
_ = html
fmt.Println(html)
// (html output)

JSON

DumpJSON

DumpJSON prints a pretty-printed JSON string to the configured writer.

Example: print JSON

v := map[string]int{"a": 1}
d := godump.NewDumper()
d.DumpJSON(v)
// {
//   "a": 1
// }

Example: print JSON

v := map[string]int{"a": 1}
godump.DumpJSON(v)
// {
//   "a": 1
// }

DumpJSONStr

DumpJSONStr pretty-prints values as JSON and returns it as a string.

Example: dump JSON string

v := map[string]int{"a": 1}
d := godump.NewDumper()
out := d.DumpJSONStr(v)
_ = out
// {"a":1}

Example: JSON string

v := map[string]int{"a": 1}
out := godump.DumpJSONStr(v)
_ = out
// {"a":1}

Options

WithDisableStringer

WithDisableStringer disables using the fmt.Stringer output. When enabled, the underlying type is rendered instead of String().

// Default: false
v := time.Duration(3)
d := godump.NewDumper(godump.WithDisableStringer(true))
d.Dump(v)
// 3 #time.Duration

WithExcludeFields

WithExcludeFields omits struct fields that match the provided names.

// Default: none
type User struct {
	ID       int
	Email    string
	Password string
}
d := godump.NewDumper(
	godump.WithExcludeFields("Password"),
)
d.Dump(User{ID: 1, Email: "[email protected]", Password: "secret"})
// #godump.User {
//   +ID    => 1 #int
//   +Email => "[email protected]" #string
// }

WithFieldMatchMode

WithFieldMatchMode sets how field names are matched for WithExcludeFields.

// Default: FieldMatchExact
type User struct {
	UserID int
}
d := godump.NewDumper(
	godump.WithExcludeFields("id"),
	godump.WithFieldMatchMode(godump.FieldMatchContains),
)
d.Dump(User{UserID: 10})
// #godump.User {
// }

WithMaxDepth

WithMaxDepth limits how deep the structure will be dumped. Param n must be 0 or greater or this will be ignored, and default MaxDepth will be 15.

// Default: 15
v := map[string]map[string]int{"a": {"b": 1}}
d := godump.NewDumper(godump.WithMaxDepth(1))
d.Dump(v)
// #map[string]map[string]int {
//   a => #map[string]int {
//     b => 1 #int
//   }
// }

WithMaxItems

WithMaxItems limits how many items from an array, slice, or map can be printed. Param n must be 0 or greater or this will be ignored, and default MaxItems will be 100.

// Default: 100
v := []int{1, 2, 3}
d := godump.NewDumper(godump.WithMaxItems(2))
d.Dump(v)
// #[]int [
//   0 => 1 #int
//   1 => 2 #int
//   ... (truncated)
// ]

WithMaxStringLen

WithMaxStringLen limits how long printed strings can be. Param n must be 0 or greater or this will be ignored, and default MaxStringLen will be 100000.

// Default: 100000
v := "hello world"
d := godump.NewDumper(godump.WithMaxStringLen(5))
d.Dump(v)
// "hello…" #string

WithOnlyFields

WithOnlyFields limits struct output to fields that match the provided names.

// Default: none
type User struct {
	ID       int
	Email    string
	Password string
}
d := godump.NewDumper(
	godump.WithOnlyFields("ID", "Email"),
)
d.Dump(User{ID: 1, Email: "[email protected]", Password: "secret"})
// #godump.User {
//   +ID    => 1 #int
//   +Email => "[email protected]" #string
// }

WithRedactFields

WithRedactFields replaces matching struct fields with a redacted placeholder.

// Default: none
type User struct {
	ID       int
	Password string
}
d := godump.NewDumper(
	godump.WithRedactFields("Password"),
)
d.Dump(User{ID: 1, Password: "secret"})
// #godump.User {
//   +ID       => 1 #int
//   +Password => <redacted> #string
// }

WithRedactMatchMode

WithRedactMatchMode sets how field names are matched for WithRedactFields.

// Default: FieldMatchExact
type User struct {
	APIKey string
}
d := godump.NewDumper(
	godump.WithRedactFields("key"),
	godump.WithRedactMatchMode(godump.FieldMatchContains),
)
d.Dump(User{APIKey: "abc"})
// #godump.User {
//   +APIKey => <redacted> #string
// }

WithRedactSensitive

WithRedactSensitive enables default redaction for common sensitive fields.

// Default: disabled
type User struct {
	Password string
	Token    string
}
d := godump.NewDumper(
	godump.WithRedactSensitive(),
)
d.Dump(User{Password: "secret", Token: "abc"})
// #godump.User {
//   +Password => <redacted> #string
//   +Token    => <redacted> #string
// }

WithSkipStackFrames

WithSkipStackFrames skips additional stack frames for header reporting. This is useful when godump is wrapped and the actual call site is deeper.

// Default: 0
v := map[string]int{"a": 1}
d := godump.NewDumper(godump.WithSkipStackFrames(2))
d.Dump(v)
// <#dump // ../../../../usr/local/go/src/runtime/asm_arm64.s:1223
// #map[string]int {
//   a => 1 #int
// }

WithWriter

WithWriter routes output to the provided writer.

// Default: stdout
var b strings.Builder
v := map[string]int{"a": 1}
d := godump.NewDumper(godump.WithWriter(&b))
d.Dump(v)
// #map[string]int {
//   a => 1 #int
// }

WithoutColor

WithoutColor disables colorized output for the dumper.

// Default: false
v := map[string]int{"a": 1}
d := godump.NewDumper(godump.WithoutColor())
d.Dump(v)
// (prints without color)
// #map[string]int {
//   a => 1 #int
// }

WithoutHeader

WithoutHeader disables printing the source location header.

// Default: false
d := godump.NewDumper(godump.WithoutHeader())
d.Dump("hello")
// "hello" #string