scribe

README

Scribe

Scribe is a Go library for structured, indented output in CLI tools. It formats output as a tree of named sections and leaf lines, with each nesting level indented by two spaces. All visual styling is delegated to a caller-supplied Theme, so the same structured output can be rendered plain or with ANSI color without changing the calling code.

Usage

Add scribe to your module:

go get github.com/gomicro/scribe

Basic usage

s, err := scribe.NewScribe(os.Stdout, scribe.DefaultTheme())
if err != nil {
    log.Fatal(err)
}

s.BeginDescribe("Deployment")
{
    s.BeginDescribe("Services")
    s.EndDescribe()
    s.Print("Starting api")
    s.Print("Starting worker")
}
s.EndDescribe()

Output:

Deployment

  Services
    Starting api
    Starting worker

Themed usage

Pass a custom Theme to apply ANSI color or any other decoration to describe headers and error lines:

import "github.com/gomicro/scribe/color"

theme := &scribe.Theme{
    Describe: color.CyanFg,
    Print:    scribe.NoopDecorator,
    Error: func(err error) string {
        return color.RedFg("Error: " + err.Error())
    },
}

s, err := scribe.NewScribe(os.Stdout, theme)
if err != nil {
    log.Fatal(err)
}

s.BeginDescribe("Deployment")
{
    s.Print("Pushing image")
    s.Error(errors.New("registry unreachable"))
}
s.EndDescribe()

The color subpackage provides ANSI helpers for all standard and high-intensity foreground colors (RedFg, CyanFg, HiBlueFg, etc.).

Versioning

The library will be versioned in accordance with Semver 2.0.0. See the releases section for the latest version. Until version 1.0.0 the library is considered to be unstable.

License

See LICENSE.md for more information.

Documentation

Overview

Package scribe provides structured, indented output for CLI tools. Output is organized as a tree of named sections and leaf lines, with each nesting level indented by two spaces. All visual styling is delegated to a caller-supplied Theme, so the same structured output can be rendered plain or with ANSI color without changing call sites.

Index

• Variables
• func NoopDecorator(s string) string
• func NoopErrDecorator(err error) string
• func ValidateTheme(theme *Theme) error
• type Scribe
  • func (s *Scribe) BeginDescribe(desc string)
  • func (s *Scribe) Child(desc string) Scriber
  • func (s *Scribe) EndDescribe()
  • func (s *Scribe) Error(err error)
  • func (s *Scribe) Errorf(format string, args ...any)
  • func (s *Scribe) Print(str string)
  • func (s *Scribe) PrintLines(r io.Reader)
  • func (s *Scribe) Printf(format string, args ...any)
• type Scriber
  • func NewScribe(writer io.Writer, theme *Theme) (Scriber, error)
• type Theme
  • func DefaultTheme() *Theme

Variables

var (
	ErrThemeDescribeMissing = fmt.Errorf("theme missing describe decorator")
	ErrThemePrintMissing    = fmt.Errorf("theme missing print decorator")
	ErrThemeErrorMissing    = fmt.Errorf("theme missing error decorator")
)

Sentinel errors returned by ValidateTheme for missing Theme decorator fields.

Functions

func NoopDecorator

func NoopDecorator(s string) string

NoopDecorator is a no-op for Theme.Describe and Theme.Print fields.

func NoopErrDecorator

func NoopErrDecorator(err error) string

NoopErrDecorator is a no-op for the Theme.Error field.

func ValidateTheme

func ValidateTheme(theme *Theme) error

ValidateTheme checks that all three decorator fields of theme are non-nil. It returns a wrapped sentinel error for the first nil field found.

Types

type Scribe

type Scribe struct {
	// contains filtered or unexported fields
}

func (*Scribe) BeginDescribe

func (s *Scribe) BeginDescribe(desc string)

func (*Scribe) Child

func (s *Scribe) Child(desc string) Scriber

Child creates a new buffered Scriber labeled with desc at the current indent level. All output written to the child is held in memory until EndDescribe is called, at which point the entire block is written atomically to the parent's writer. This allows multiple goroutines to each own a child and produce grouped, non-interleaved output.

func (*Scribe) EndDescribe

func (s *Scribe) EndDescribe()

func (*Scribe) Error

func (s *Scribe) Error(err error)

func (*Scribe) Errorf

func (s *Scribe) Errorf(format string, args ...any)

func (*Scribe) Print

func (s *Scribe) Print(str string)

func (*Scribe) PrintLines

func (s *Scribe) PrintLines(r io.Reader)

func (*Scribe) Printf

func (s *Scribe) Printf(format string, args ...any)

type Scriber

type Scriber interface {
	// BeginDescribe emits desc at the current indent and increases indent for
	// subsequent output.
	BeginDescribe(desc string)

	// EndDescribe decrements the indent. For child scribers it also flushes
	// buffered output atomically to the parent writer.
	EndDescribe()

	// Child creates a buffered child scriber at the current indent level.
	// Output is held until EndDescribe, then written atomically to the parent
	// writer — allowing goroutines to produce non-interleaved output.
	Child(desc string) Scriber

	// Print emits a line at the current indent, styled by Theme.Print.
	Print(str string)

	// Printf is the formatted variant of Print.
	Printf(format string, args ...any)

	// PrintLines scans r and emits each line at the current indent, styled by
	// Theme.Print.
	PrintLines(r io.Reader)

	// Error emits a line at the current indent, styled by Theme.Error.
	Error(err error)

	// Errorf is the formatted variant of Error.
	Errorf(format string, args ...any)
}

Scriber is the interface for structured, indented CLI output. Output is organized as a tree of named sections opened with BeginDescribe/EndDescribe (or Child) and leaf lines written with Print, PrintLines, and Error. Each nesting level is indented by two spaces. All visual styling is applied by the Theme supplied to NewScribe.

func NewScribe

func NewScribe(writer io.Writer, theme *Theme) (Scriber, error)

NewScribe creates a new Scriber that writes to writer using the given theme. It returns an error if the theme fails validation (any decorator is nil).

type Theme

type Theme struct {
	// Describe formats the label emitted by BeginDescribe and Child.
	Describe func(string) string
	// Print formats lines emitted by Print, Printf, and PrintLines.
	Print func(string) string
	// Error formats lines emitted by Error and Errorf.
	Error func(error) string
}

Theme controls how each category of output line is formatted before it is written. All three fields are required; NewScribe returns an error if any is nil. Use NoopDecorator and NoopErrDecorator for fields that should pass the string through unchanged.

func DefaultTheme

func DefaultTheme() *Theme

DefaultTheme returns a Theme with no-op decorators.