pf

README

pf

English | 日本語 | 中文 | 한국어 | Español | Português

A Go pretty-print package that extends fmt. Formats structs, maps, and slices with indentation for readable output.

Install

go get github.com/nd-forge/pf

Quick Start

import "github.com/nd-forge/pf"

type User struct {
    Name    string `json:"name"`
    Age     int    `json:"age"`
    Active  bool
    Address Address
}

user := User{Name: "John", Age: 30, Active: true, Address: Address{City: "San Francisco"}}

// Pretty print
pf.Print(user)

Output (with ANSI colors in terminal):

{
  Name: "John",
  Age: 30,
  Active: true,
  Address: {
    City: "San Francisco"
  }
}

API

Pretty Print

Function	Description
pf.Print(v)	Print to stdout
pf.Sprint(v)	Return as string
pf.Fprint(w, v)	Write to io.Writer

Diff

Function	Description
pf.Diff(a, b)	Print diff to stdout
pf.SprintDiff(a, b)	Return diff as string
pf.FprintDiff(w, a, b)	Write diff to io.Writer

old := User{Name: "John", Age: 30, Active: true}
new := User{Name: "John", Age: 31, Active: false}

pf.Diff(old, new)
// {
//   Name: "John"
//   - Age: 30
//   + Age: 31
//   - Active: true
//   + Active: false
// }

Config

c := pf.Config{
    Indent:      "    ",  // 4-space indent
    ShowTypes:   true,    // show type names
    UseJSONTags: true,    // use `json:"..."` tag names
    MaxDepth:    3,       // limit nesting
    ColorMode:   false,   // no ANSI colors (for logging)
}

c.Print(myStruct)

UseJSONTags

type User struct {
    Name  string `json:"user_name"`
    Email string `json:"email_address,omitempty"`
}

// UseJSONTags: true
// {
//   user_name: "John",
// }
// (Email is omitempty + zero value → omitted)

Interfaces

PrettyPrinter

Highest priority. Define custom pretty-print output for your types.

type Token struct { Value string }

func (t Token) PrettyPrint() string {
    return fmt.Sprintf("Token(***%s)", t.Value[len(t.Value)-4:])
}

pf.Print(Token{Value: "secret1234"})
// Token(***1234)

PrettyPrinterConfig

Receives the Config to produce format-aware output.

func (t Token) PrettyPrintConfig(c pf.Config) string {
    masked := "***" + t.Value[len(t.Value)-4:]
    if c.ColorMode {
        return "\033[33m" + masked + "\033[0m"
    }
    return masked
}

fmt.Stringer / error

For non-struct types, fmt.Stringer and error implementations are used automatically. For structs, field expansion takes priority (implement PrettyPrinter to override).

Interface priority:

1. PrettyPrinterConfig (config-aware)
2. PrettyPrinter
3. fmt.Stringer (non-struct only)
4. error (non-struct only)
5. Reflection-based formatting

DefaultConfig

You can modify the global configuration:

pf.DefaultConfig.ColorMode = false    // for logging
pf.DefaultConfig.UseJSONTags = true   // display with JSON names
pf.DefaultConfig.ShowTypes = true     // show type names

License

MIT

Documentation

Overview

Package pf extends fmt with pretty-printing for Go values.

Basic usage:

pf.Print(myStruct)
s := pf.Sprint(myStruct)
pf.Diff(oldStruct, newStruct)

Implement PrettyPrinter for custom formatting:

func (u User) PrettyPrint() string { return fmt.Sprintf("User<%s>", u.Name) }

Index

• Variables
• func Diff(a, b interface{})
• func Fprint(w io.Writer, v interface{})
• func FprintDiff(w io.Writer, a, b interface{})
• func Print(v interface{})
• func Sprint(v interface{}) string
• func SprintDiff(a, b interface{}) string
• type Config
  • func (c Config) Fprint(w io.Writer, v interface{})
  • func (c Config) Print(v interface{})
  • func (c Config) Sprint(v interface{}) string
  • func (c Config) SprintDiff(a, b interface{}) string
• type PrettyPrinter
• type PrettyPrinterConfig

Variables

var DefaultConfig = Config{
	Indent:      "  ",
	ShowTypes:   false,
	UseJSONTags: false,
	MaxDepth:    0,
	ColorMode:   true,
}

DefaultConfig is the default pretty-print configuration.

Functions

func Diff

func Diff(a, b interface{})

Diff prints a colorized diff to stdout.

func Fprint

func Fprint(w io.Writer, v interface{})

Fprint pretty-prints to the given writer.

func FprintDiff

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

FprintDiff writes a diff to the given writer.

func Print

func Print(v interface{})

Print pretty-prints to stdout.

func Sprint

func Sprint(v interface{}) string

Sprint returns a pretty-printed string.

func SprintDiff

func SprintDiff(a, b interface{}) string

SprintDiff returns a diff string.

Types

type Config

type Config struct {
	// Indent string per level. Default: "  "
	Indent string
	// ShowTypes annotates values with their type name.
	ShowTypes bool
	// UseJSONTags uses json tag names instead of Go field names.
	UseJSONTags bool
	// MaxDepth limits nesting depth (0 = unlimited).
	MaxDepth int
	// ColorMode enables ANSI color output.
	ColorMode bool
}

Config controls pretty-print formatting.

func (Config) Fprint

func (c Config) Fprint(w io.Writer, v interface{})

Fprint pretty-prints to the given writer using this config.

func (Config) Print

func (c Config) Print(v interface{})

Print pretty-prints to stdout using this config.

func (Config) Sprint

func (c Config) Sprint(v interface{}) string

Sprint returns a pretty-printed string using this config.

func (Config) SprintDiff

func (c Config) SprintDiff(a, b interface{}) string

SprintDiff returns a diff string using this config.

type PrettyPrinter

type PrettyPrinter interface {
	PrettyPrint() string
}

PrettyPrinter can be implemented by any type to control its own pretty-print output. When a value implements PrettyPrinter, pf uses PrettyPrint() instead of reflection-based formatting.

type User struct { Name string; Age int }

func (u User) PrettyPrint() string {
    return fmt.Sprintf("User<%s, age=%d>", u.Name, u.Age)
}

type PrettyPrinterConfig

type PrettyPrinterConfig interface {
	PrettyPrintConfig(c Config) string
}

PrettyPrinterConfig is like PrettyPrinter but receives the current Config, allowing format-aware custom output.

func (u User) PrettyPrintConfig(c pf.Config) string {
    if c.ColorMode {
        return "\033[36mUser<" + u.Name + ">\033[0m"
    }
    return "User<" + u.Name + ">"
}