pretty

package module
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 29, 2025 License: MIT Imports: 12 Imported by: 0

README

Pretty

A Go library for pretty-printing any data structure with optional ANSI color support.

Features

  • Pretty-print any Go data type (structs, slices, maps, primitives, etc.)
  • Configurable line width for automatic multi-line formatting
  • ANSI color support with automatic terminal detection
  • Clean, readable output with proper indentation
  • Fluent API for easy configuration

Installation

go get github.com/jogly/pretty

Usage

Basic Usage
package main

import (
    "fmt"
    "github.com/jogly/pretty"
)

func main() {
    data := map[string]interface{}{
        "name": "Alice",
        "age": 30,
        "active": true,
        "balance": 123.45,
        "tags": []string{"user", "premium"},
    }

    fmt.Println(pretty.Print(data))
}
Custom Configuration
// Custom width
pp := &pretty.Printer{MaxWidth: 50}
fmt.Println(pp.Print(data))

// Fluent API
output := pretty.New().
    WithMaxWidth(80).
    WithColorMode(pretty.ColorAlways).
    Print(data)
Color Options
// Auto-detect terminal support (default)
printer := pretty.New().WithColorMode(pretty.ColorAuto)

// Always use colors
printer := pretty.New().WithColorMode(pretty.ColorAlways)

// Never use colors
printer := pretty.New().WithColorMode(pretty.ColorNever)

Examples

Visual comparison between this library and spew.Dump:

Pretty Output Spew Output
Nested Structs Pretty Nested Structs Spew
Cycle Detection Pretty Cycle Detection Spew
JSON Strings Pretty JSON Strings Spew
Slice Truncation Pretty Slice Truncation Spew
Collections Width Pretty Collections Width Spew
UUID Detection Pretty UUID Detection Spew
Channels Pretty Channels Spew

Note: Run ./bin/create_images.sh to generate the example images shown above.

Documentation

Overview

Package pretty provides utilities for formatting any input into pretty-printed strings.

Basic usage:

pretty.Print(data)

With custom width:

pp := &pretty.Printer{MaxWidth: 50}
pp.Print(data)

Or using the fluent API:

pretty.New().WithMaxWidth(50).Print(data)

Index

Constants

This section is empty.

Variables

View Source
var (
	Default = New()
)

Functions

func Print

func Print(v interface{}) string

Print formats any input value into a pretty-printed string representation using default options

func PrintWidth added in v1.3.0

func PrintWidth(v interface{}, width int) string

func Time added in v1.3.0

func Time(t time.Time) string

Time formats a time.Time value into a human-friendly relative string using default settings

Types

type ColorMode

type ColorMode int

ColorMode controls when colors are used

const (
	// ColorAuto automatically detects if colors should be used based on terminal
	ColorAuto ColorMode = iota
	// ColorAlways always uses colors
	ColorAlways
	// ColorNever never uses colors
	ColorNever
)

type Printer

type Printer struct {
	// MaxWidth is the maximum line width before breaking to multiple lines
	MaxWidth int
	// ColorMode controls when colors are used in output
	ColorMode ColorMode
	// MaxSliceLength is the maximum number of elements to show in slices/arrays
	// If 0, shows all elements (default behavior)
	MaxSliceLength int
	// MaxStringLength is the maximum length for individual strings before truncation
	// If 0, no truncation is applied (default behavior)
	MaxStringLength int
	// MaxKeysInline is the maximum number of keys to show in maps & structs
	// inline before breaking to multiple lines. This allows maps and structs to
	// be multi-lined before the overall max width is reached.
	MaxKeysInline int
	// Margin adds space around the output
	// If 0, no margin is applied (default behavior)
	Margin [4]int

	// Styles holds the lipgloss Styles for different semantic purposes
	Styles struct {
		Error       lipgloss.Style // for errors and invalid values
		String      lipgloss.Style // for string values
		Boolean     lipgloss.Style // for boolean values
		Number      lipgloss.Style // for integer numbers
		Float       lipgloss.Style // for floating-point numbers
		SpecialType lipgloss.Style // for special types like io.ReadCloser
		Time        lipgloss.Style // for time values
		Null        lipgloss.Style // for nil/null values
		Comment     lipgloss.Style // for comments and metadata
		Field       lipgloss.Style // for field names (struct fields and string map keys)
		Pointer     lipgloss.Style // for pointers
	}
	// contains filtered or unexported fields
}

Printer configures and performs pretty printing

func New

func New() *Printer

New creates a new Printer with default options

func (*Printer) Print

func (p *Printer) Print(v interface{}) string

Print formats any input value into a pretty-printed string representation

func (*Printer) WithColorMode

func (p *Printer) WithColorMode(mode ColorMode) *Printer

WithColorMode creates a new Printer with the specified color mode

func (*Printer) WithMargin added in v1.3.0

func (p *Printer) WithMargin(margin ...int) *Printer

func (*Printer) WithMaxSliceLength added in v1.2.0

func (p *Printer) WithMaxSliceLength(maxLen int) *Printer

WithMaxSliceLength creates a new Printer with the specified maximum slice length

func (*Printer) WithMaxStringLength added in v1.2.0

func (p *Printer) WithMaxStringLength(maxLen int) *Printer

WithMaxStringLength creates a new Printer with the specified maximum string length

func (*Printer) WithMaxWidth

func (p *Printer) WithMaxWidth(width int) *Printer

WithMaxWidth creates a new Printer with the specified maximum width

type TimeFormatter added in v1.3.0

type TimeFormatter struct {
	// Reference time for calculating relative time (defaults to time.Now())
	Now time.Time

	SecondThreshold time.Duration // Show "X seconds ago" below this (default: 1 minute)
	MinuteThreshold time.Duration // Show "X minutes ago" below this (default: 1 hour)
	HourThreshold   time.Duration // Show "X hours ago" below this (default: 1 day)
	DayThreshold    time.Duration // Show "X days ago" below this (default: 1 week)
	WeekThreshold   time.Duration // Show "X weeks ago" below this (default: 1 month)
	MonthThreshold  time.Duration // Show "X months ago" below this (default: 1 year)

	// Use friendly phrases like "just now", "last week", "next month"
	FriendlyPhrases bool

	// Show future times as "in X time" vs "X from now".
	// "in %s" (default), or customize like "%s from now"
	FutureFormat string

	ZeroString string // String to show for zero time (default: "<zero>")
}

TimeFormatter configures and performs human-friendly relative time formatting

func NewTimeFormatter added in v1.3.0

func NewTimeFormatter() *TimeFormatter

NewTimeFormatter creates a new TimeFormatter with sensible defaults

func (*TimeFormatter) Format added in v1.3.0

func (tf *TimeFormatter) Format(t time.Time) string

Format formats a time.Time value into a human-friendly relative string

func (*TimeFormatter) WithDayThreshold added in v1.3.0

func (tf *TimeFormatter) WithDayThreshold(d time.Duration) *TimeFormatter

WithDayThreshold sets when to stop showing days and switch to weeks

func (*TimeFormatter) WithFriendlyPhrases added in v1.3.0

func (tf *TimeFormatter) WithFriendlyPhrases(enabled bool) *TimeFormatter

WithFriendlyPhrases enables/disables friendly phrases like "just now", "last week"

func (*TimeFormatter) WithFutureFormat added in v1.3.0

func (tf *TimeFormatter) WithFutureFormat(format string) *TimeFormatter

WithFutureFormat sets how future times are formatted ("in %s" vs "%s from now")

func (*TimeFormatter) WithHourThreshold added in v1.3.0

func (tf *TimeFormatter) WithHourThreshold(d time.Duration) *TimeFormatter

WithHourThreshold sets when to stop showing hours and switch to days

func (*TimeFormatter) WithMinuteThreshold added in v1.3.0

func (tf *TimeFormatter) WithMinuteThreshold(d time.Duration) *TimeFormatter

WithMinuteThreshold sets when to stop showing minutes and switch to hours

func (*TimeFormatter) WithMonthThreshold added in v1.3.0

func (tf *TimeFormatter) WithMonthThreshold(d time.Duration) *TimeFormatter

WithMonthThreshold sets when to stop showing months and switch to years

func (*TimeFormatter) WithNow added in v1.3.0

func (tf *TimeFormatter) WithNow(now time.Time) *TimeFormatter

WithNow sets a custom reference time for relative calculations

func (*TimeFormatter) WithSecondThreshold added in v1.3.0

func (tf *TimeFormatter) WithSecondThreshold(d time.Duration) *TimeFormatter

WithSecondThreshold sets when to stop showing seconds and switch to minutes

func (*TimeFormatter) WithWeekThreshold added in v1.3.0

func (tf *TimeFormatter) WithWeekThreshold(d time.Duration) *TimeFormatter

WithWeekThreshold sets when to stop showing weeks and switch to months

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL