pretty

README

Pretty

Go pretty print library.

Features

• Pretty print value
• String / Write / Formatter
• Config: indentation, max depth, max length (string / map / slice), sort map keys
• Custom value writers: error, []byte hex dump, fmt.Stringer, pierrre/errors
• No infinite recursion
• Fast and (almost) no memory allocation

Usage

Example

Documentation

Overview

Package pretty provides utilities to pretty print values.

Example

type exampleStruct struct {
	Int    int
	Float  float64
	String string
	Map    map[string]int
	Slice  []int
}
v := exampleStruct{
	Int:    123,
	Float:  123.456,
	String: "test",
	Map: map[string]int{
		"foo": 1,
		"bar": 2,
	},
	Slice: []int{1, 2, 3},
}
s := String(v)
fmt.Println(s)

Output:

(pretty_test.exampleStruct) {
	Int: (int) 123,
	Float: (float64) 123.456,
	String: (string) (len=4) "test",
	Map: (map[string]int) (len=2) {
		(string) (len=3) "bar": (int) 2,
		(string) (len=3) "foo": (int) 1,
	},
	Slice: ([]int) (len=3 cap=3) {
		(int) 1,
		(int) 2,
		(int) 3,
	},
}

Index

• Variables
• func Formatter(vi any) fmt.Formatter
• func GetIndentWriter(w io.Writer, c *Config, st *State, indented bool) *indentWriter
• func String(vi any) string
• func Write(w io.Writer, vi any)
• type Config
  • func NewConfig() *Config
  • func (c *Config) Formatter(vi any) fmt.Formatter
  • func (c *Config) String(vi any) string
  • func (c *Config) Write(w io.Writer, vi any)
  • func (c *Config) WriteIndent(w io.Writer, st *State)
• type State
• type ValueWriter
  • func NewBytesValueWriter(maxLen int) ValueWriter
  • func NewByteserValueWriter(maxLen int) ValueWriter
  • func NewDefaultValueWriter() ValueWriter
  • func NewErrorValueWriter() ValueWriter
  • func NewFilterValueWriter(vw ValueWriter, f func(v reflect.Value) bool) ValueWriter
  • func NewReflectValueValueWriter() ValueWriter
  • func NewStringerValueWriter(maxLen int) ValueWriter

Examples

• Package
• Formatter
• String
• ValueWriter
• Write

Variables

var DefaultConfig = NewConfig()

DefaultConfig is the default Config.

Functions

func Formatter

func Formatter(vi any) fmt.Formatter

Formatter returns a fmt.Formatter for the value with DefaultConfig.

Example

f := Formatter("test")
s := fmt.Sprintf("%v", f)
fmt.Println(s)

Output:

(string) (len=4) "test"

func GetIndentWriter

func GetIndentWriter(w io.Writer, c *Config, st *State, indented bool) *indentWriter

GetIndentWriter returns an indentWriter from the pool.

It is exposed for internal use. It should not be used outside of this package.

func String

func String(vi any) string

String returns the value as a string with DefaultConfig.

Example

s := String("test")
fmt.Println(s)

Output:

(string) (len=4) "test"

func Write

func Write(w io.Writer, vi any)

Write writes the value to the writer with DefaultConfig.

Example

buf := new(bytes.Buffer)
Write(buf, "test")
s := buf.String()
fmt.Println(s)

Output:

(string) (len=4) "test"

Types

type Config

type Config struct {
	// Indent is the string used to indent.
	// Default: "\t".
	Indent string
	// MaxDepth is the maximum depth.
	// Default: 0 (no limit).
	MaxDepth int
	// StringMaxLen is the maximum length of strings.
	// Default: 0 (no limit).
	StringMaxLen int
	// SliceMaxLen is the maximum length of slices and arrays.
	// Default: 0 (no limit).
	SliceMaxLen int
	// MapSortKeys sorts map keys.
	// Default: false.
	MapSortKeys bool
	// MapMaxLen is the maximum length of maps.
	// Default: 0 (no limit).
	MapMaxLen int
	// StructUnexported prints unexported fields of structs.
	// Default: true.
	StructUnexported bool
	// ValueWriters is the list of ValueWriter used to write values.
	// Default: reflect.Value, error, []byte, interface{ Bytes() []byte }, fmt.Stringer.
	ValueWriters []ValueWriter
}

Config is a configuration used to pretty print values.

It should be created with NewConfig.

func NewConfig

func NewConfig() *Config

NewConfig creates a new Config initialized with default values.

func (*Config) Formatter

func (c *Config) Formatter(vi any) fmt.Formatter

Formatter returns a fmt.Formatter for the value.

func (*Config) String

func (c *Config) String(vi any) string

String returns the value as a string.

func (*Config) Write

func (c *Config) Write(w io.Writer, vi any)

Write writes the value to the writer.

func (*Config) WriteIndent

func (c *Config) WriteIndent(w io.Writer, st *State)

WriteIndent writes the indentation to the writer.

type State

type State struct {
	Depth   int
	Indent  int
	Visited []uintptr
}

State represents the state of the pretty printer.

Functions must restore the original state when they return.

type ValueWriter

type ValueWriter func(c *Config, w io.Writer, st *State, v reflect.Value) bool

ValueWriter is a function that writes a value. It can be used to override the default behavior.

It returns true if it handled the value, false otherwise.

Implementations must check reflect.Value.CanInterface before using reflect.Value.Interface.

Example

vw := func(c *Config, w io.Writer, st *State, v reflect.Value) bool {
	_, _ = io.WriteString(w, "example")
	return true
}
c := NewConfig()
c.ValueWriters = []ValueWriter{vw}
s := c.String("test")
fmt.Println(s)

Output:

(string) example

func NewBytesValueWriter

func NewBytesValueWriter(maxLen int) ValueWriter

NewBytesValueWriter returns a ValueWriter that writes []byte with encoding/hex.Dumper.

func NewByteserValueWriter

func NewByteserValueWriter(maxLen int) ValueWriter

NewByteserValueWriter returns a ValueWriter that writes interface { Bytes() []byte } with encoding/hex.Dumper.

func NewDefaultValueWriter

func NewDefaultValueWriter() ValueWriter

NewDefaultValueWriter returns a ValueWriter that writes the value with the default behavior, bypassing all ValueWriters.

It should be used with NewFilterValueWriter in order to filter specific types.

func NewErrorValueWriter

func NewErrorValueWriter() ValueWriter

NewErrorValueWriter returns a ValueWriter that writes error.

func NewFilterValueWriter

func NewFilterValueWriter(vw ValueWriter, f func(v reflect.Value) bool) ValueWriter

NewFilterValueWriter returns a ValueWriter that calls the provided ValueWriter if f returns true.

It allows to enable/disable a ValueWriter for specific values/types.

func NewReflectValueValueWriter

func NewReflectValueValueWriter() ValueWriter

NewReflectValueValueWriter returns a ValueWriter that writes reflect.Value.

func NewStringerValueWriter

func NewStringerValueWriter(maxLen int) ValueWriter

NewStringerValueWriter returns a ValueWriter that writes fmt.Stringer.