godump

README

godump

A versatile Go library designed to output any Go variable in a structured and colored format.

This library is especially useful for debugging and testing when the standard fmt library falls short in displaying arbitrary data effectively. It can also serve as a powerful logging adapter, providing clear and readable logs for both development and production environments.

godump is not here to replace the fmt package. Instead, it provides an extension to what the fmt.Printf("%#v") can do.

Why godump

• ability to pretty print values of all types
• well formatted output
• unexported structs are dumped too
• pointers are followed, and recursive pointers are taken in mind (see examples)
• customizable, you have full control over the output, you can even generate HTML if you'd like to, see examples
• zero dependencies

Get Started

Install the library:

go get -u github.com/yassinebenaid/godump

Then use the Dump function:

package main

import (
	"github.com/yassinebenaid/godump"
)

func main() {
	godump.Dump("Anything")
}

Customization

If you need more control over the output. Use the Dumper

package main

import (
	"os"

	"github.com/yassinebenaid/godump"
)

func main() {

	var v = "Foo Bar"
	var d = godump.Dumper{
		Indentation:       "  ",
		HidePrivateFields: false,
		ShowPrimitiveNamedTypes = false
		Theme: godump.Theme{
			String: godump.RGB{R: 138, G: 201, B: 38},
			// ...
		},
	}

	d.Print(v)
	d.Println(v)
	d.Fprint(os.Stdout, v)
	d.Fprintln(os.Stdout, v)
	d.Sprint(v)
	d.Sprintln(v)
}

Demo

Example 1.

package main

import (
	"os"

	"github.com/yassinebenaid/godump"
)

func main() {
	godump.Dump(os.Stdout)
}

Output:

Example 2.

package main

import (
	"net"

	"github.com/yassinebenaid/godump"
)

func main() {
	godump.Dump(net.Dialer{})
}

Output:

Example 3.

This example shows how recursive pointers are handled.

package main

import (
	"github.com/yassinebenaid/godump"
)

func main() {
	type User struct {
		Name       string
		age        int
		BestFriend *User
	}

	me := User{
		Name: "yassinebenaid",
		age:  22,
	}

    // This creates a ring
	me.BestFriend = &me

	godump.Dump(me)
}

Output:

Example 4.

This example emphasizes how you can generate HTML

package main

import (
	"fmt"
	"net"
	"net/http"

	"github.com/yassinebenaid/godump"
)

// Define your custom style implementation
type CSSColor struct {
	R, G, B int
}

func (c CSSColor) Apply(s string) string {
	return fmt.Sprintf(`<div style="color: rgb(%d, %d, %d); display: inline-block">%s</div>`, c.R, c.G, c.B, s)
}

func main() {

	var d godump.Dumper

	d.Theme = godump.Theme{
		String:        CSSColor{138, 201, 38},// edit the theme to use your implementation
		Quotes:        CSSColor{112, 214, 255},
		Bool:          CSSColor{249, 87, 56},
		Number:        CSSColor{10, 178, 242},
		Types:         CSSColor{0, 150, 199},
		Address:       CSSColor{205, 93, 0},
		PointerTag:    CSSColor{110, 110, 110},
		Nil:           CSSColor{219, 57, 26},
		Func:          CSSColor{160, 90, 220},
		Fields:        CSSColor{189, 176, 194},
		Chan:          CSSColor{195, 154, 76},
		UnsafePointer: CSSColor{89, 193, 180},
		Braces:        CSSColor{185, 86, 86},
	}

	var html = `<pre style="background: #111; padding: 10px; color: white">`
	html += d.Sprint(net.Dialer{})
	html += "<pre>"

    // render it to browsers
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/html")
		fmt.Fprint(w, html)
	})

	http.ListenAndServe(":8000", nil)

}

Output:

For more examples, please take a look at dumper_test along with testdata

Contribution

Please read CONTRIBUTING guidelines

Documentation

Index

• Variables
• func Dump(v any) error
• type Dumper
  • func (d *Dumper) Fprint(dst io.Writer, v any) error
  • func (d *Dumper) Fprintln(dst io.Writer, v any) error
  • func (d *Dumper) Print(v any) error
  • func (d *Dumper) Println(v any) error
  • func (d *Dumper) Sprint(v any) string
  • func (d *Dumper) Sprintln(v any) string
• type RGB
  • func (rgb RGB) Apply(v string) string
• type Style
• type Theme

Variables

var DefaultTheme = Theme{
	String:        RGB{138, 201, 38},
	Quotes:        RGB{112, 214, 255},
	Bool:          RGB{249, 87, 56},
	Number:        RGB{10, 178, 242},
	Types:         RGB{0, 150, 199},
	Address:       RGB{205, 93, 0},
	PointerTag:    RGB{110, 110, 110},
	Nil:           RGB{219, 57, 26},
	Func:          RGB{160, 90, 220},
	Fields:        RGB{189, 176, 194},
	Chan:          RGB{195, 154, 76},
	UnsafePointer: RGB{89, 193, 180},
	Braces:        RGB{185, 86, 86},
}

DefaultTheme is the default Theme used by Dump.

Functions

func Dump

func Dump(v any) error

Dump pretty prints `v` using the default Dumper options and the default theme

Types

type Dumper

type Dumper struct {
	// Indentation is an optional string used for indentation.
	// The default value is a string of three spaces.
	Indentation string

	// ShowPrimitiveNamedTypes determines whether to show primitive named types.
	ShowPrimitiveNamedTypes bool

	// HidePrivateFields allows you to optionally hide struct's unexported fields from being printed.
	HidePrivateFields bool

	// Theme allows you to define your preferred styling.
	Theme Theme
	// contains filtered or unexported fields
}

Dumper provides an elegant interface to pretty print any variable of any type in a colored and structured format.

The zero value for Dumper is a theme-less Dumper ready to use.

func (*Dumper) Fprint

func (d *Dumper) Fprint(dst io.Writer, v any) error

Fprint formats `v` and writes the result to `dst`.

It returns a write error if encountered while writing to `dst`.

func (*Dumper) Fprintln

func (d *Dumper) Fprintln(dst io.Writer, v any) error

Fprintln formats `v`, appends a new line, and writes the result to `dst`.

It returns a write error if encountered while writing to `dst`.

func (*Dumper) Print

func (d *Dumper) Print(v any) error

Print formats `v` and writes the result to standard output.

It returns a write error if encountered while writing to standard output.

func (*Dumper) Println

func (d *Dumper) Println(v any) error

Println formats `v`, appends a new line, and writes the result to standard output.

It returns a write error if encountered while writing to standard output.

func (*Dumper) Sprint

func (d *Dumper) Sprint(v any) string

Sprint formats `v` and returns the resulting string.

func (*Dumper) Sprintln

func (d *Dumper) Sprintln(v any) string

Sprintln formats `v`, appends a new line, and returns the resulting string.

type RGB

type RGB struct {
	R, G, B int
}

RGB implements Style and allows you to define your style as an RGB value, it uses ANSI escape sequences under the hood.

func (RGB) Apply

func (rgb RGB) Apply(v string) string

type Style

type Style interface {
	Apply(string) string
}

Style defines a general interface used for styling.

type Theme

type Theme struct {
	// String defines the style used for strings
	String Style

	// Quotes defines the style used for quotes (") around strings.
	Quotes Style

	// Bool defines the style used for boolean values.
	Bool Style

	// Number defines the style used for numbers, including all types of integers, floats and complex numbers.
	Number Style

	// Types defines the style used for defined and/or structural types, eg., slices, structs, maps...
	Types Style

	// Nil defines the style used for nil.
	Nil Style

	// Func defines the style used for functions.
	Func Style

	// Chan defines the style used for channels.
	Chan Style

	// UnsafePointer defines the style used for unsafe pointers.
	UnsafePointer Style

	// Address defines the style used for address symbol '&'.
	Address Style

	// PointerTag defines the style used for pointer tags, typically the pointer id '#x' and the recursive reference '@x'.
	PointerTag Style

	// Fields defines the style used for struct fields.
	Fields Style

	// Braces defines the style used for braces '{}' in structural types.
	Braces Style
}

Theme allows you to define your preferred styling for Dumper.