output

package module
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: May 24, 2026 License: MIT Imports: 17 Imported by: 0

README

go-output

CI Go Report Card GoDoc

A Go library that formats structured data into 12 output formats — tables, trees, and diagrams — with type-safe enums, branded IDs, and zero-config color support. Write your data once, render it anywhere.

import "github.com/larsartmann/go-output"

Quick Start

Build tabular data once, render it in any format:

data := output.NewTableData([]string{"Name", "Health", "Complexity"})
data.AddRow([]string{"Alpha", "90%", "7/10"})
data.AddRow([]string{"Beta", "75%", "5/10"})

// Markdown table
md := output.NewMarkdownTable()
md.SetHeaders(data.GetHeaders())
for _, row := range data.GetRows() {
    md.AddRow(row)
}
out, _ := md.Render()

// JSON
json, _ := output.MarshalJSONIndent(projects, "", "  ")

// CSV
w := output.NewCSVWriter(os.Stdout)
w.WriteHeader(data.GetHeaders())
for _, row := range data.GetRows() {
    w.WriteRow(row)
}
w.Flush()

Use the Format enum for runtime format selection — perfect for CLI flags:

format, _ := output.ParseFormat("json") // validates input
fmt.Println(format.Supports(output.ShapeTable)) // true
fmt.Println(format.Shapes())                     // [table tree graph]

Why go-output?

  • 12 formats, one API — Same data, different renderers. No format-specific code paths.
  • Type-safe enums — Format, ColorMode, SortBy — all validated at parse time, never raw strings.
  • Zero heavy deps in root module — go get go-output pulls only go-faster/yaml and x/term. Lipgloss is isolated in table/, D2 and graph renderers in their own modules.
  • Branded IDs — Phantom types prevent mixing D2NodeID, TreeNodeID, GraphNodeID at compile time.
  • Streaming — StreamingHTMLRenderer for large datasets with minimal memory.
  • Extensible registry — Register custom renderers for runtime dispatch.

Supported Formats

Format Table Tree Graph Notes
table ✅ Terminal tables with lipgloss styling (separate table/ module)
json ✅ ✅ ✅ Shape-agnostic serialization
csv ✅ Comma-separated export
tsv ✅ Tab-separated export
xml ✅ XML with table structure
markdown ✅ Markdown tables
yaml ✅ ✅ ✅ Shape-agnostic serialization
d2 ✅ ✅ SQL tables + node-edge diagrams (separate d2/ module)
html ✅ ✅ HTML tables + collapsible tree
tree ✅ ASCII tree with box-drawing chars
mermaid ✅ ✅ Mermaid flowchart diagrams (separate graph/ module)
dot ✅ ✅ DOT/Graphviz directed graphs (separate graph/ module)

All formats implement the Renderer interface:

type Renderer interface {
    Render() (string, error)
}
Table Formats
// JSON table (array of objects)
jt := output.NewJSONTableRenderer()
jt.SetHeaders([]string{"Name", "Health"})
jt.AddRow([]string{"Alpha", "90%"})
out, _ := jt.Render()
// [{"Name": "Alpha", "Health": "90%"}]

// YAML table (sequence of mappings)
yt := output.NewYAMLTableRenderer()
yt.SetHeaders([]string{"Name", "Health"})
yt.AddRow([]string{"Alpha", "90%"})
out, _ := yt.Render()

// JSON (any data)
data, _ := output.MarshalJSONIndent(projects, "", "  ")

// CSV
w := output.NewCSVWriter(os.Stdout)
w.WriteHeader([]string{"Name", "Value"})
w.WriteRow([]string{"Item", "123"})
w.Flush()

// TSV
tw := output.NewTSVWriter(os.Stdout)
tw.WriteHeader([]string{"Name", "Value"})
tw.WriteRow([]string{"Item", "123"})
tw.Flush()

// XML
data, _ := output.MarshalXMLFromTableData(tableData)

// YAML (any data)
data, _ := output.MarshalYAML(projects)

// Markdown table
md := output.NewMarkdownTable()
md.SetHeaders([]string{"Name", "Health"})
md.AddRow([]string{"Alpha", "90%"})
out, _ := md.Render()

// Terminal table with lipgloss styling (requires go-output/table)
tbl := table.New()
tbl.SetHeaders("Name", "Health")
tbl.AddRow("Alpha", "90%")
out, _ := tbl.Render()
Tree Formats
root := output.NewTreeNode("root", "Projects")
root.AddChild(output.NewTreeNode("alpha", "Alpha"))
root.AddChild(output.NewTreeNode("beta", "Beta"))

// ASCII tree
tree := output.NewASCIITreeRenderer()
tree.SetRoot(root)
out, _ := tree.Render()
// Projects
// ├── Alpha
// └── Beta

// JSON tree
jt := output.NewJSONTreeRenderer()
jt.SetRoot(root)
out, _ := jt.Render()
// {"id": "root", "label": "Projects", "children": [...]}

// YAML tree
yt := output.NewYAMLTreeRenderer()
yt.SetRoot(root)
out, _ := yt.Render()
// id: root
// label: Projects
// children: ...

// HTML tree (collapsible)
ht := output.NewHTMLTreeRenderer()
ht.SetRoot(root)
out, _ := ht.Render()
Graph Formats
import (
    "github.com/larsartmann/go-output"
    "github.com/larsartmann/go-output/d2"
    "github.com/larsartmann/go-output/graph"
)

nodes := []output.GraphNode{
    output.NewGraphNode("a", "API Gateway"),
    output.NewGraphNode("b", "Backend"),
}
edges := []output.GraphEdge{
    output.NewGraphEdge("a", "b"),
}

// DOT / Graphviz (requires go-output/graph)
renderer := graph.DOTFromTableData(data)
out, _ := renderer.Render()

// Mermaid flowchart (requires go-output/graph)
renderer := graph.MermaidFromTableData(data)
out, _ := renderer.Render()

// JSON graph
jg := output.NewJSONGraphRenderer()
jg.SetNodes(nodes)
jg.SetEdges(edges)
out, _ := jg.Render()
// {"nodes": [...], "edges": [...]}

// YAML graph
yg := output.NewYAMLGraphRenderer()
yg.SetNodes(nodes)
yg.SetEdges(edges)
out, _ := yg.Render()

// D2 diagrams (requires go-output/d2)
diagram := d2.NewD2Diagram().
    AddNodeWithShape("api", "API Gateway", d2.D2ShapeHexagon).
    AddEdgeSimple("api", "backend")
out, _ := diagram.Render()

Data Shapes

Every format declares which data shapes it supports via the capability matrix:

// Check if a format supports a specific data shape
format, _ := output.ParseFormat("d2")
fmt.Println(format.Supports(output.ShapeTable)) // true (D2 supports SQL tables)
fmt.Println(format.Supports(output.ShapeGraph)) // true (D2 supports node-edge diagrams)
fmt.Println(format.Supports(output.ShapeTree))  // false

// Get all shapes a format supports
for _, shape := range format.Shapes() {
    fmt.Println(shape) // "table", "graph"
}

// Find all formats that can render graph data
for _, f := range output.FormatsForShape(output.ShapeGraph) {
    fmt.Println(f) // json, yaml, d2, mermaid, dot
}

Installation

go get github.com/larsartmann/go-output

Sub-modules for specific formats:

go get github.com/larsartmann/go-output/table   # Terminal tables with lipgloss
go get github.com/larsartmann/go-output/d2     # D2 diagrams
go get github.com/larsartmann/go-output/graph  # DOT + Mermaid renderers

Branded IDs

Type-safe identifiers prevent mixing different ID types at compile time:

nodeID := output.NewBrandedID[output.D2NodeIDBrand]("node-1")
treeID := output.NewBrandedID[output.TreeNodeIDBrand]("root")

// nodeID = treeID  // COMPILE ERROR: different branded types

Define your own branded types:

type ProjectIDBrand struct{}
projectID := output.NewBrandedID[ProjectIDBrand]("proj-123")

D2 Advanced Features

D2 diagrams support SQL tables, constraints, grid layouts, and nested containers:

table := d2.D2Table{
    Name: "users",
    Columns: []d2.D2Column{
        {Name: "id", Type: "INT", Constraint: d2.D2ConstraintPrimary},
        {Name: "email", Type: "VARCHAR(255)", Constraint: d2.D2ConstraintUnique},
        {Name: "manager_id", Type: "INT", Constraint: d2.D2ConstraintForeign},
    },
}

node := d2.D2Node{
    ID:          output.NewBrandedID[output.D2NodeIDBrand]("dashboard"),
    Label:       output.NewBrandedID[output.D2NodeLabelBrand]("Dashboard"),
    GridRows:    3,
    GridColumns: 2,
    GridGap:     8,
}

Registry System

Register custom renderers for runtime dispatch:

output.Register(output.Format("custom"), func() output.Renderer {
    return &myCustomRenderer{}
})

renderer, _ := output.Create(output.FormatTable)
formats := output.RegisteredFormats()

Streaming Renderer

For large datasets, stream output incrementally:

renderer := output.NewStreamingHTMLRenderer()
renderer.SetData(tableData)
_ = renderer.Stream(os.Stdout)

Color Modes

Mode Description
auto Respect NO_COLOR, CI env vars, TTY detection
always Force ANSI colors
never Disable colors

Type-Safe Enums

All configuration types provide validation and string conversion:

format, err := output.ParseFormat("json")
if format.IsValid() {
    fmt.Println(format.String()) // "json"
}
allowed := format.AllowedValues() // []string{"table", "json", "csv", ...}

Escape Functions

The escape/ subpackage provides safe escaping for each format:

import "github.com/larsartmann/go-output/escape"

safe := escape.HTML("<script>alert('xss')</script>")
safeID := escape.D2("my-node.with.dots")
Function Purpose
escape.HTML HTML special characters
escape.XML XML special characters
escape.D2 D2 diagram identifiers
escape.DOT DOT graph identifiers
escape.MermaidID Mermaid node IDs

Dependencies

Root module — zero lipgloss dependencies:

require (
    github.com/go-faster/yaml v0.4.6
    golang.org/x/term v0.42.0
)

Terminal table module (install separately):

require (
    charm.land/lipgloss/v2 v2.0.3
)

D2 diagram module (install separately):

require github.com/larsartmann/go-output/d2 v0.0.0

DOT + Mermaid graph module (install separately):

require github.com/larsartmann/go-output/graph v0.0.0

Examples

See examples/basic/main.go for a complete example demonstrating all 12 formats:

go run ./examples/basic/main.go markdown

Development

nix develop                    # Enter dev shell (Go 1.26, golangci-lint, gopls)
nix fmt                        # Format .nix files
nix flake check                # Verify formatting + pre-commit hooks
Go toolchain (manual)
go build ./...                  # Build all workspace modules
go test ./...                   # Test all modules
go test -race ./...             # Race detector
go test -cover ./...            # Coverage report
golangci-lint run --fix ./...   # Lint

API Stability

This library is pre-v1. The following guarantees apply:

  • Root module (github.com/larsartmann/go-output): Public API is stable. Breaking changes will be documented in CHANGELOG.md.
  • Sub-modules (d2, graph, table): May evolve independently. Import them explicitly to opt in.
  • Renderer interface: Stable — all formats implement Render() (string, error).
  • internal/ packages: No stability guarantee. Do not import these.

License

MIT

Documentation

Overview

Package output provides consistent output formatting for CLI applications.

Package output provides consistent output formatting for CLI applications.

Index

Constants

This section is empty.

Variables

View Source 
var AllFormats = []Format{
	FormatTable,
	FormatJSON,
	FormatCSV,
	FormatTSV,
	FormatMarkdown,
	FormatXML,
	FormatD2,
	FormatYAML,
	FormatHTML,
	FormatTree,
	FormatMermaid,
	FormatDOT,
}

AllFormats contains all valid output format values. Use this for testing AllowedValues or generating help text.

View Source 
var AllShapes = []Shape{
	ShapeTable,
	ShapeTree,
	ShapeGraph,
}

AllShapes contains all valid data shape values.

View Source 
var ErrFormatAlreadyRegistered = errors.New("format already registered")

ErrFormatAlreadyRegistered is returned when a format is already registered.

View Source 
var ErrNoRendererRegistered = errors.New("no renderer registered for format")

ErrNoRendererRegistered is returned when no renderer is registered for a format.

View Source 
var ErrUnsupportedType = errors.New("unsupported type")

ErrUnsupportedType is returned when an unsupported type is provided for TSV marshaling.

Functions

func AddTreeNodes 

func AddTreeNodes(
	nodes *[]GraphNode, edges *[]GraphEdge,
	node *TreeNode, parentID string,
	idFunc TreeNodeIDFunc, shape GraphShape,
)

AddTreeNodes recursively adds tree nodes and edges to the provided graph slices.

func DefaultGraphNodeLabel 

func DefaultGraphNodeLabel(header, cell string) string

DefaultGraphNodeLabel returns a label in the format "header: cell".

func FilledStrings 

func FilledStrings(n int, value string) []string

FilledStrings returns a slice of n strings, each filled with the given value.

func IsRegistered deprecated 

func IsRegistered(format Format) bool

IsRegistered returns true if a format has a registered renderer.

Deprecated: Use format constructors directly.

func MarshalCSVFromTableData added in v0.5.0 

func MarshalCSVFromTableData(data *TableData) ([]byte, error)

MarshalCSVFromTableData marshals TableData as CSV with a header row.

func MarshalJSON 

func MarshalJSON(v any) ([]byte, error)

MarshalJSON encodes v to JSON.

func MarshalJSONIndent 

func MarshalJSONIndent(v any, prefix, indent string) ([]byte, error)

MarshalJSONIndent encodes v to indented JSON.

func MarshalTSV 

func MarshalTSV(data any) ([]byte, error)

MarshalTSV marshals data as TSV.

func MarshalTSVFromTableData added in v0.5.0 

func MarshalTSVFromTableData(data *TableData) ([]byte, error)

MarshalTSVFromTableData marshals TableData as TSV with a header row.

func MarshalXML 

func MarshalXML(v any) ([]byte, error)

MarshalXML encodes v to XML.

func MarshalXMLFromTableData 

func MarshalXMLFromTableData(data *TableData) ([]byte, error)

MarshalXMLFromTableData marshals TableData to XML.

func MarshalXMLIndent 

func MarshalXMLIndent(v any, prefix, indent string) (result []byte, err error)

MarshalXMLIndent encodes v to indented XML.

func MarshalYAML 

func MarshalYAML(v any) ([]byte, error)

MarshalYAML encodes v to YAML.

func MustRender 

func MustRender(r Renderer) string

MustRender calls Render on the provided Renderer and panics if it returns an error. Useful for tests and examples where rendering failure is unexpected.

func NewBrandedID 

func NewBrandedID[Brand any](value string) id.ID[Brand, string]

NewBrandedID creates a new branded ID from a string value.

func Register deprecated 

func Register(format Format, factory RendererFactory) error

Register registers a renderer factory for a format.

Deprecated: Use format constructors directly. This function may be removed in a future version.

func RenderTableData added in v0.5.0 

func RenderTableData(data *TableData, format Format, opts ...RenderOptions) error

RenderTableData renders TableData in the given format and writes to w (or os.Stdout). It supports: csv, tsv, markdown, xml, yaml, html, tree.

D2, Mermaid, and DOT are NOT handled — those require importing the d2 or graph sub-modules directly. Table and JSON formats also require per-command customization (table for lipgloss styling, json for full struct marshaling).

Returns UnsupportedFormatError for unsupported formats (d2, mermaid, dot, table, json).

func UnmarshalJSON 

func UnmarshalJSON(data []byte, v any) error

UnmarshalJSON decodes JSON data into v.

func UnmarshalYAML 

func UnmarshalYAML(data []byte, v any) error

UnmarshalYAML decodes YAML data into v.

func Unregister deprecated 

func Unregister(format Format)

Unregister removes a format from the registry.

Deprecated: Use format constructors directly.

Types

type ASCIITreeRenderer 

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

ASCIITreeRenderer implements the TreeOutputRenderer interface for ASCII tree output.

func NewASCIITreeRenderer 

func NewASCIITreeRenderer() *ASCIITreeRenderer

NewASCIITreeRenderer creates a new ASCIITreeRenderer.

func TreeRendererFromTableData 

func TreeRendererFromTableData(data *TableData) *ASCIITreeRenderer

TreeRendererFromTableData converts TableData to a tree using the first column as hierarchy.

func (*ASCIITreeRenderer) Render 

func (r *ASCIITreeRenderer) Render() (string, error)

Render returns the tree as a string.

func (*ASCIITreeRenderer) SetRoot 

func (r *ASCIITreeRenderer) SetRoot(node *TreeNode)

SetRoot sets the root node of the tree.

type Alignment 

type Alignment int

Alignment represents text alignment within a table cell. 

const (
	AlignLeft   Alignment = AlignmentLeft
	AlignRight  Alignment = AlignmentRight
	AlignCenter Alignment = AlignmentCenter
)

Column alignment constants. 

const (
	AlignmentLeft Alignment = iota
	AlignmentRight
	AlignmentCenter
)

Column alignment iota values (unexported).

type BrandedID 

type BrandedID[Brand any] = id.ID[Brand, string]

BrandedID re-export for backward compatibility. Use id.ID[Brand, string] for new code.

type CSVWriter 

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

CSVWriter writes CSV output.

func NewCSVWriter 

func NewCSVWriter(w io.Writer) *CSVWriter

NewCSVWriter creates a new CSVWriter.

func (*CSVWriter) Error 

func (c *CSVWriter) Error() error

Error returns any error from the writer.

func (*CSVWriter) Flush 

func (c *CSVWriter) Flush()

Flush flushes the writer.

func (*CSVWriter) WriteHeader 

func (c *CSVWriter) WriteHeader(cols []string) error

WriteHeader writes the header row.

func (*CSVWriter) WriteRow 

func (c *CSVWriter) WriteRow(values []string) error

WriteRow writes a single row.

func (*CSVWriter) WriteRows 

func (c *CSVWriter) WriteRows(values [][]string) error

WriteRows writes multiple rows.

type ColorMode 

type ColorMode string

ColorMode controls terminal color output. 

const (
	ColorModeAuto   ColorMode = "auto"
	ColorModeAlways ColorMode = "always"
	ColorModeNever  ColorMode = "never"
)

Terminal color output modes.

func ParseColorMode 

func ParseColorMode(s string) (ColorMode, error)

ParseColorMode converts a string to ColorMode, returning an error if invalid.

func (ColorMode) AllowedValues 

func (c ColorMode) AllowedValues() []string

AllowedValues returns all valid color mode values.

func (ColorMode) IsValid 

func (c ColorMode) IsValid() bool

IsValid checks if the color mode is valid.

func (ColorMode) ShouldColor 

func (c ColorMode) ShouldColor() bool

ShouldColor returns true if colors should be enabled.

func (ColorMode) String 

func (c ColorMode) String() string

String returns the string representation of the color mode.

type D2NodeID 

type D2NodeID = id.ID[D2NodeIDBrand, string]

D2NodeID is a branded identifier for D2 diagram nodes.

type D2NodeIDBrand 

type D2NodeIDBrand struct{}

D2NodeIDBrand is the brand type for D2 node IDs.

type D2NodeLabel 

type D2NodeLabel = id.ID[D2NodeLabelBrand, string]

D2NodeLabel is a branded identifier for D2 diagram node labels.

type D2NodeLabelBrand 

type D2NodeLabelBrand struct{}

D2NodeLabelBrand is the brand type for D2 node labels.

type DelimitedWriter 

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

DelimitedWriter handles common logic for CSV and TSV writing.

func NewDelimitedWriter 

func NewDelimitedWriter(w io.Writer, delimiter rune, name string) *DelimitedWriter

NewDelimitedWriter creates a new DelimitedWriter.

func (*DelimitedWriter) Error 

func (d *DelimitedWriter) Error() error

Error returns any error encountered during writing.

func (*DelimitedWriter) Flush 

func (d *DelimitedWriter) Flush()

Flush flushes the writer.

func (*DelimitedWriter) WriteRow 

func (d *DelimitedWriter) WriteRow(cols []string, description string) error

WriteRow writes a single row.

func (*DelimitedWriter) WriteRows 

func (d *DelimitedWriter) WriteRows(values [][]string, description string) error

WriteRows writes multiple rows.

type EdgeStyle 

type EdgeStyle struct {
	Color     string
	Style     string // solid, dashed, dotted
	ArrowHead string
	ArrowTail string
}

EdgeStyle represents styling attributes for an edge.

type Format 

type Format string

Format represents the available output format options for CLI applications. 

const (
	FormatTable    Format = "table"
	FormatJSON     Format = "json"
	FormatCSV      Format = "csv"
	FormatTSV      Format = "tsv"
	FormatMarkdown Format = "markdown"
	FormatXML      Format = "xml"
	FormatD2       Format = "d2"
	FormatYAML     Format = "yaml"
	FormatHTML     Format = "html"
	FormatTree     Format = "tree"
	FormatMermaid  Format = "mermaid"
	FormatDOT      Format = "dot"
)

Output format constants.

func FormatsForShape added in v0.5.0 

func FormatsForShape(s Shape) []Format

FormatsForShape returns all formats that support the given data shape.

func ParseFormat 

func ParseFormat(s string) (Format, error)

ParseFormat converts a string to Format, returning an error if invalid.

func RegisteredFormats deprecated 

func RegisteredFormats() []Format

RegisteredFormats returns a sorted list of all registered formats.

Deprecated: Use format constructors directly.

func (Format) AllowedValues 

func (f Format) AllowedValues() []string

AllowedValues returns all valid output format values for CLI help text.

func (Format) IsValid 

func (f Format) IsValid() bool

IsValid returns true if the format is a valid Format value.

func (Format) Shapes added in v0.5.0 

func (f Format) Shapes() []Shape

Shapes returns all data shapes this format supports.

func (Format) String 

func (f Format) String() string

String returns the string representation of the format.

func (Format) Supports added in v0.5.0 

func (f Format) Supports(s Shape) bool

Supports returns true if the format can render the given data shape.

type GraphEdge 

type GraphEdge struct {
	From  GraphNodeID
	To    GraphNodeID
	Label GraphNodeLabel
	Style EdgeStyle
}

GraphEdge represents an edge between two nodes.

func NewGraphEdge 

func NewGraphEdge(from, to string) *GraphEdge

NewGraphEdge creates a new GraphEdge.

type GraphNode 

type GraphNode struct {
	ID       GraphNodeID
	Label    GraphNodeLabel
	Shape    GraphShape
	Style    GraphStyle
	Metadata map[string]string
}

GraphNode represents a node in a graph.

func NewGraphNode 

func NewGraphNode(id, label string) *GraphNode

NewGraphNode creates a new GraphNode.

func NodesFromTableData 

func NodesFromTableData(data *TableData, labelFn GraphNodeLabelFunc) []GraphNode

NodesFromTableData creates GraphNodes from TableData using the provided label function.

type GraphNodeID 

type GraphNodeID = id.ID[GraphNodeIDBrand, string]

GraphNodeID is a branded identifier for graph nodes.

type GraphNodeIDBrand 

type GraphNodeIDBrand struct{}

GraphNodeIDBrand is the brand type for graph node IDs.

type GraphNodeLabel 

type GraphNodeLabel = id.ID[GraphNodeLabelBrand, string]

GraphNodeLabel is a branded identifier for graph node labels.

type GraphNodeLabelBrand 

type GraphNodeLabelBrand struct{}

GraphNodeLabelBrand is the brand type for graph node labels.

type GraphNodeLabelFunc 

type GraphNodeLabelFunc func(header, cell string) string

GraphNodeLabelFunc is a function that formats a cell value with its header into a label.

type GraphRenderer 

type GraphRenderer interface {
	Renderer
	// SetNodes sets the graph nodes.
	SetNodes(nodes []GraphNode)
	// SetEdges sets the graph edges.
	SetEdges(edges []GraphEdge)
}

GraphRenderer defines the interface for graph format renderers.

type GraphRendererMixin 

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

GraphRendererMixin contains shared fields and methods for graph renderers.

D2 does not use this mixin because it has richer domain-specific types (D2Node, D2Edge with classes, SQL tables, shapes, arrow types, etc.) that do not map to the simpler GraphNode/GraphEdge model.

func NewGraphRendererMixin 

func NewGraphRendererMixin() GraphRendererMixin

NewGraphRendererMixin creates a new GraphRendererMixin with initialized slices.

func (*GraphRendererMixin) AddRowEdges 

func (m *GraphRendererMixin) AddRowEdges(data *TableData)

AddRowEdges adds edges from data.CreateRowEdges() to the graph.

func (*GraphRendererMixin) Edges added in v0.5.0 

func (m *GraphRendererMixin) Edges() []GraphEdge

Edges returns the graph edges.

func (*GraphRendererMixin) EdgesPtr added in v0.5.0 

func (m *GraphRendererMixin) EdgesPtr() *[]GraphEdge

EdgesPtr returns a pointer to the graph edges slice for mutation.

func (*GraphRendererMixin) Nodes added in v0.5.0 

func (m *GraphRendererMixin) Nodes() []GraphNode

Nodes returns the graph nodes.

func (*GraphRendererMixin) NodesPtr added in v0.5.0 

func (m *GraphRendererMixin) NodesPtr() *[]GraphNode

NodesPtr returns a pointer to the graph nodes slice for mutation.

func (*GraphRendererMixin) SetEdges 

func (m *GraphRendererMixin) SetEdges(edges []GraphEdge)

SetEdges sets the graph edges.

func (*GraphRendererMixin) SetNodes 

func (m *GraphRendererMixin) SetNodes(nodes []GraphNode)

SetNodes sets the graph nodes.

func (*GraphRendererMixin) SetNodesFromTableData 

func (m *GraphRendererMixin) SetNodesFromTableData(
	data *TableData,
	modifyNode func(i int, n *GraphNode),
)

SetNodesFromTableData creates nodes from TableData, applies per-node modifications, adds them to the graph, and adds row edges.

type GraphShape 

type GraphShape string

GraphShape represents the shape of a graph node. 

const (
	ShapeBox           GraphShape = "box"
	ShapeEllipse       GraphShape = "ellipse"
	ShapeDiamond       GraphShape = "diamond"
	ShapeCircle        GraphShape = "circle"
	ShapeCylinder      GraphShape = "cylinder"
	ShapeHexagon       GraphShape = "hexagon"
	ShapeParallelogram GraphShape = "parallelogram"
	ShapeRect          GraphShape = "rect"
)

GraphShape constants define the available shapes for graph nodes.

func ParseGraphShape 

func ParseGraphShape(s string) (GraphShape, error)

ParseGraphShape converts a string to GraphShape, returning an error if invalid.

func (GraphShape) AllowedValues 

func (s GraphShape) AllowedValues() []string

AllowedValues returns all valid graph shape values.

func (GraphShape) IsValid 

func (s GraphShape) IsValid() bool

IsValid checks if the graph shape is valid.

func (GraphShape) String 

func (s GraphShape) String() string

String returns the string representation of the graph shape.

type GraphStyle 

type GraphStyle struct {
	FillColor   string
	StrokeColor string
	FontColor   string
	FontSize    int
}

GraphStyle represents styling attributes for a graph node.

type HTMLRenderer 

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

HTMLRenderer implements the Renderer interface for HTML table output.

func NewHTMLRenderer 

func NewHTMLRenderer() *HTMLRenderer

NewHTMLRenderer creates a new HTMLRenderer.

func (*HTMLRenderer) AddRow 

func (b *HTMLRenderer) AddRow(row []string)

AddRow adds a data row.

func (*HTMLRenderer) Render 

func (r *HTMLRenderer) Render() (string, error)

Render returns the HTML table as a string.

func (*HTMLRenderer) RenderFullHTML 

func (r *HTMLRenderer) RenderFullHTML(title string) (string, error)

RenderFullHTML returns a complete HTML document with the table.

func (*HTMLRenderer) SetData 

func (b *HTMLRenderer) SetData(data *TableData)

SetData sets the table data directly.

func (*HTMLRenderer) SetHeaders 

func (b *HTMLRenderer) SetHeaders(headers []string)

SetHeaders sets the column headers.

type HTMLTreeRenderer 

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

HTMLTreeRenderer renders a tree structure as HTML with nested lists.

func NewHTMLTreeRenderer 

func NewHTMLTreeRenderer() *HTMLTreeRenderer

NewHTMLTreeRenderer creates a new HTMLTreeRenderer.

func (*HTMLTreeRenderer) Render 

func (r *HTMLTreeRenderer) Render() (string, error)

Render returns the tree as an HTML string.

func (*HTMLTreeRenderer) RenderFullHTML 

func (r *HTMLTreeRenderer) RenderFullHTML(title string) (string, error)

RenderFullHTML returns a complete HTML document with the tree.

func (*HTMLTreeRenderer) SetRoot 

func (r *HTMLTreeRenderer) SetRoot(node *TreeNode)

SetRoot sets the root node of the tree.

type InvalidColorModeError added in v0.5.0 

type InvalidColorModeError struct {
	Value string
}

InvalidColorModeError is returned when an invalid color mode is provided.

func (*InvalidColorModeError) Error added in v0.5.0 

func (e *InvalidColorModeError) Error() string

type InvalidFormatError 

type InvalidFormatError struct {
	Value   string
	Allowed []Format
}

InvalidFormatError represents an invalid format error.

func (*InvalidFormatError) Error 

func (e *InvalidFormatError) Error() string

Error returns a descriptive error message including allowed values.

type InvalidGraphShapeError added in v0.5.0 

type InvalidGraphShapeError struct {
	Value string
}

InvalidGraphShapeError is returned when an invalid graph shape is provided.

func (*InvalidGraphShapeError) Error added in v0.5.0 

func (e *InvalidGraphShapeError) Error() string

type InvalidShapeError added in v0.5.0 

type InvalidShapeError struct {
	Value string
}

InvalidShapeError is returned when an invalid data shape is provided.

func (*InvalidShapeError) Error added in v0.5.0 

func (e *InvalidShapeError) Error() string

type InvalidSortByError added in v0.5.0 

type InvalidSortByError struct {
	Value string
}

InvalidSortByError is returned when an invalid sort field is provided.

func (*InvalidSortByError) Error added in v0.5.0 

func (e *InvalidSortByError) Error() string

type JSONGraphRenderer added in v0.5.0 

type JSONGraphRenderer struct {
	GraphRendererMixin
}

JSONGraphRenderer renders graph nodes and edges as JSON.

func NewJSONGraphRenderer added in v0.5.0 

func NewJSONGraphRenderer() *JSONGraphRenderer

NewJSONGraphRenderer creates a new JSONGraphRenderer.

func (*JSONGraphRenderer) Render added in v0.5.0 

func (r *JSONGraphRenderer) Render() (string, error)

Render returns the graph as a JSON string.

type JSONTableRenderer added in v0.5.0 

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

JSONTableRenderer renders TableData as a JSON array of objects. Each row becomes a JSON object with headers as keys.

func NewJSONTableRenderer added in v0.5.0 

func NewJSONTableRenderer() *JSONTableRenderer

NewJSONTableRenderer creates a new JSONTableRenderer.

func (*JSONTableRenderer) AddRow added in v0.5.0 

func (b *JSONTableRenderer) AddRow(row []string)

AddRow adds a data row.

func (*JSONTableRenderer) Render added in v0.5.0 

func (r *JSONTableRenderer) Render() (string, error)

Render returns the table data as a JSON string.

func (*JSONTableRenderer) SetData added in v0.5.0 

func (b *JSONTableRenderer) SetData(data *TableData)

SetData sets the table data directly.

func (*JSONTableRenderer) SetHeaders added in v0.5.0 

func (b *JSONTableRenderer) SetHeaders(headers []string)

SetHeaders sets the column headers.

type JSONTreeRenderer added in v0.5.0 

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

JSONTreeRenderer renders a TreeNode hierarchy as JSON. Each node becomes a JSON object with "id", "label", and optional "children".

func NewJSONTreeRenderer added in v0.5.0 

func NewJSONTreeRenderer() *JSONTreeRenderer

NewJSONTreeRenderer creates a new JSONTreeRenderer.

func (*JSONTreeRenderer) Render added in v0.5.0 

func (r *JSONTreeRenderer) Render() (string, error)

Render returns the tree as a JSON string.

func (*JSONTreeRenderer) SetRoot added in v0.5.0 

func (r *JSONTreeRenderer) SetRoot(node *TreeNode)

SetRoot sets the root node of the tree.

type JSONWriter 

type JSONWriter struct {
	Writer io.Writer
}

JSONWriter writes JSON output to an io.Writer.

func NewJSONWriter 

func NewJSONWriter(w io.Writer) *JSONWriter

NewJSONWriter creates a new JSONWriter.

func (*JSONWriter) Encode 

func (j *JSONWriter) Encode(v any) error

Encode writes v as JSON to the underlying writer.

type MarkdownTable 

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

MarkdownTable builds Markdown tables.

func NewMarkdownTable 

func NewMarkdownTable() *MarkdownTable

NewMarkdownTable creates a new MarkdownTable.

func NewMarkdownTableFromData 

func NewMarkdownTableFromData(data *TableData) *MarkdownTable

NewMarkdownTableFromData creates a MarkdownTable populated from TableData.

func (*MarkdownTable) AddRow 

func (m *MarkdownTable) AddRow(row []string) *MarkdownTable

AddRow adds a row to the table.

func (*MarkdownTable) Render 

func (m *MarkdownTable) Render() (string, error)

Render returns the Markdown table string.

func (*MarkdownTable) SetAlign 

func (m *MarkdownTable) SetAlign(col int, alignment Alignment) *MarkdownTable

SetAlign sets column alignment.

func (*MarkdownTable) SetHeaders 

func (m *MarkdownTable) SetHeaders(headers []string) *MarkdownTable

SetHeaders sets the table headers.

type RenderOptions added in v0.5.0 

type RenderOptions struct {
	// Title is used as the document title for HTML output and as a header for Markdown.
	Title string

	// GraphID is used as the graph identifier for DOT output.
	GraphID string

	// Writer overrides the default os.Stdout output destination.
	Writer io.Writer
}

RenderOptions configures optional behavior for RenderTableData.

type Renderer 

type Renderer interface {
	// Render returns the formatted output as a string.
	Render() (string, error)
}

Renderer defines the interface for output format renderers.

func Create deprecated 

func Create(format Format) (Renderer, error)

Create returns a new Renderer instance for the given format.

Deprecated: Use format constructors directly. This function may be removed in a future version.

type RendererFactory 

type RendererFactory func() Renderer

RendererFactory is a function that creates a Renderer instance.

type RowEdge 

type RowEdge struct {
	From string
	To   string
}

RowEdge represents a directed edge between two row identifiers.

type Shape added in v0.5.0 

type Shape string

Shape represents a data shape that a format can render. 

const (
	ShapeTable Shape = "table" // Tabular data with headers and rows
	ShapeTree  Shape = "tree"  // Hierarchical data with parent-child nodes
	ShapeGraph Shape = "graph" // Network data with nodes and edges
)

Data shape constants for format capability classification.

func ParseShape added in v0.5.0 

func ParseShape(s string) (Shape, error)

ParseShape converts a string to Shape, returning an error if invalid.

func (Shape) AllowedValues added in v0.5.0 

func (s Shape) AllowedValues() []string

AllowedValues returns all valid data shape values for CLI help text.

func (Shape) IsValid added in v0.5.0 

func (s Shape) IsValid() bool

IsValid returns true if the shape is a valid Shape value.

func (Shape) String added in v0.5.0 

func (s Shape) String() string

String returns the string representation of the data shape.

type SortBy deprecated 

type SortBy string

SortBy represents the available sort field options for CLI applications.

Deprecated: SortBy is application-specific business logic that does not belong in a general-purpose output library. Define your own sort enum in your application. 

const (
	SortByName       SortBy = "name"
	SortByImportance SortBy = "importance"
	SortByCreatedAt  SortBy = "created_at"
	SortByUpdatedAt  SortBy = "updated_at"
	SortByHealth     SortBy = "health"
	SortByComplexity SortBy = "complexity"
)

Sort field constants.

func ParseSortBy 

func ParseSortBy(s string) (SortBy, error)

ParseSortBy converts a string to SortBy, returning an error if invalid.

func (SortBy) AllowedValues 

func (s SortBy) AllowedValues() []string

AllowedValues returns all valid sort field values for CLI help text.

func (SortBy) IsValid 

func (s SortBy) IsValid() bool

IsValid returns true if the sort field is a valid SortBy value.

func (SortBy) String 

func (s SortBy) String() string

String returns the string representation of the sort field.

type StreamingHTMLRenderer 

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

StreamingHTMLRenderer is a streaming implementation of HTMLRenderer. It writes output incrementally to minimize memory usage.

func NewStreamingHTMLRenderer 

func NewStreamingHTMLRenderer() *StreamingHTMLRenderer

NewStreamingHTMLRenderer creates a new StreamingHTMLRenderer.

func (*StreamingHTMLRenderer) AddRow 

func (b *StreamingHTMLRenderer) AddRow(row []string)

AddRow adds a data row.

func (*StreamingHTMLRenderer) Render 

func (r *StreamingHTMLRenderer) Render() (string, error)

Render returns the HTML table as a string.

func (*StreamingHTMLRenderer) SetData 

func (b *StreamingHTMLRenderer) SetData(data *TableData)

SetData sets the table data directly.

func (*StreamingHTMLRenderer) SetHeaders 

func (b *StreamingHTMLRenderer) SetHeaders(headers []string)

SetHeaders sets the column headers.

func (*StreamingHTMLRenderer) Stream 

func (r *StreamingHTMLRenderer) Stream(w io.Writer) error

Stream writes the HTML table incrementally to an io.Writer.

type StreamingRenderer 

type StreamingRenderer interface {
	Renderer
	// Stream writes the rendered output to an io.Writer in chunks.
	Stream(w io.Writer) error
}

StreamingRenderer is an interface for renderers that support streaming output. This is useful for rendering large datasets without loading everything into memory.

Note: Not all implementations provide true streaming. The adapter returned by StreamingRendererFromRenderer collects output before writing. Only StreamingHTMLRenderer provides genuine streaming behavior.

func StreamingRendererFromRenderer 

func StreamingRendererFromRenderer(r Renderer) StreamingRenderer

StreamingRendererFromRenderer wraps a standard Renderer to implement StreamingRenderer. Note: This adapter does not provide true streaming behavior - it collects all output via Render() and then writes it at once. It exists to satisfy the StreamingRenderer interface for renderers that don't have native streaming support.

type TSVWriter 

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

TSVWriter writes TSV (Tab-Separated Values) output.

func NewTSVWriter 

func NewTSVWriter(w io.Writer) *TSVWriter

NewTSVWriter creates a new TSVWriter.

func (*TSVWriter) Error 

func (t *TSVWriter) Error() error

Error returns any error from the writer.

func (*TSVWriter) Flush 

func (t *TSVWriter) Flush()

Flush flushes the writer.

func (*TSVWriter) WriteHeader 

func (t *TSVWriter) WriteHeader(cols []string) error

WriteHeader writes the header row.

func (*TSVWriter) WriteRow 

func (t *TSVWriter) WriteRow(values []string) error

WriteRow writes a single row.

func (*TSVWriter) WriteRows 

func (t *TSVWriter) WriteRows(values [][]string) error

WriteRows writes multiple rows.

type TableData 

type TableData struct {
	Headers []string
	Rows    [][]string
}

TableData represents tabular data with headers and rows.

func NewTableData 

func NewTableData(headers []string) *TableData

NewTableData creates a new TableData with the given headers.

func (*TableData) AddRow 

func (d *TableData) AddRow(row []string)

AddRow adds a row to the table data.

func (*TableData) ColCount 

func (d *TableData) ColCount() int

ColCount returns the number of columns (based on headers).

func (*TableData) CreateRowEdges 

func (d *TableData) CreateRowEdges() []RowEdge

CreateRowEdges generates edge data connecting consecutive rows. Used by graph renderers to create edges between table rows.

func (*TableData) GetHeaders 

func (d *TableData) GetHeaders() []string

GetHeaders returns the column headers. Satisfies the table.TableDataProvider interface.

func (*TableData) GetRows 

func (d *TableData) GetRows() [][]string

GetRows returns the data rows. Satisfies the table.TableDataProvider interface.

func (*TableData) RowCount 

func (d *TableData) RowCount() int

RowCount returns the number of data rows.

func (*TableData) ToMapSlice added in v0.5.0 

func (d *TableData) ToMapSlice() []map[string]string

ToMapSlice converts TableData to a slice of maps (header→cell). Returns nil if data is nil or has no headers.

type TableRenderer 

type TableRenderer interface {
	Renderer
	// SetHeaders sets the column headers.
	SetHeaders(headers []string)
	// AddRow adds a data row.
	AddRow(row []string)
}

TableRenderer defines the interface for table format renderers.

type TreeNode 

type TreeNode struct {
	ID       TreeNodeID
	Label    TreeNodeLabel
	Children []*TreeNode
	Metadata map[string]string
	// contains filtered or unexported fields
}

TreeNode represents a node in a tree structure.

func NewTreeNode 

func NewTreeNode(id, label string) *TreeNode

NewTreeNode creates a new TreeNode with the given ID and label.

func (*TreeNode) AddChild 

func (n *TreeNode) AddChild(child *TreeNode)

AddChild adds a child node to this node.

func (*TreeNode) Depth 

func (n *TreeNode) Depth() int

Depth returns the depth of this node in the tree (root = 0).

func (*TreeNode) Parent 

func (n *TreeNode) Parent() *TreeNode

Parent returns the parent node (nil for root).

type TreeNodeID 

type TreeNodeID = id.ID[TreeNodeIDBrand, string]

TreeNodeID is a branded identifier for tree nodes.

type TreeNodeIDBrand 

type TreeNodeIDBrand struct{}

TreeNodeIDBrand is the brand type for tree node IDs.

type TreeNodeIDFunc 

type TreeNodeIDFunc func(*TreeNode) string

TreeNodeIDFunc resolves a TreeNode's ID for a specific graph format.

type TreeNodeLabel 

type TreeNodeLabel = id.ID[TreeNodeLabelBrand, string]

TreeNodeLabel is a branded identifier for tree node labels.

type TreeNodeLabelBrand 

type TreeNodeLabelBrand struct{}

TreeNodeLabelBrand is the brand type for tree node labels.

type TreeOutputRenderer 

type TreeOutputRenderer interface {
	Renderer
	// SetRoot sets the root node of the tree.
	SetRoot(node *TreeNode)
}

TreeOutputRenderer defines the interface for tree format renderers.

type UnsupportedFormatError added in v0.5.0 

type UnsupportedFormatError struct {
	Format Format
}

UnsupportedFormatError is returned when RenderTableData cannot handle a format.

func (*UnsupportedFormatError) Error added in v0.5.0 

func (e *UnsupportedFormatError) Error() string

func (*UnsupportedFormatError) Unwrap added in v0.5.0 

func (e *UnsupportedFormatError) Unwrap() error

type XMLWriter 

type XMLWriter struct {
	Writer io.Writer
}

XMLWriter writes XML output to an io.Writer.

func NewXMLWriter 

func NewXMLWriter(w io.Writer) *XMLWriter

NewXMLWriter creates a new XMLWriter.

func (*XMLWriter) WriteFooter 

func (x *XMLWriter) WriteFooter() error

WriteFooter writes the closing tags.

func (*XMLWriter) WriteHeader 

func (x *XMLWriter) WriteHeader(cols []string) error

WriteHeader writes the XML header and opening tags.

func (*XMLWriter) WriteRow 

func (x *XMLWriter) WriteRow(values []string) error

WriteRow writes a single row.

func (*XMLWriter) WriteRows 

func (x *XMLWriter) WriteRows(values [][]string) error

WriteRows writes multiple rows.

type YAMLGraphRenderer added in v0.5.0 

type YAMLGraphRenderer struct {
	GraphRendererMixin
}

YAMLGraphRenderer renders graph nodes and edges as YAML.

func NewYAMLGraphRenderer added in v0.5.0 

func NewYAMLGraphRenderer() *YAMLGraphRenderer

NewYAMLGraphRenderer creates a new YAMLGraphRenderer.

func (*YAMLGraphRenderer) Render added in v0.5.0 

func (r *YAMLGraphRenderer) Render() (string, error)

Render returns the graph as a YAML string.

type YAMLTableRenderer added in v0.5.0 

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

YAMLTableRenderer renders TableData as a YAML sequence of mappings. Each row becomes a YAML map with headers as keys.

func NewYAMLTableRenderer added in v0.5.0 

func NewYAMLTableRenderer() *YAMLTableRenderer

NewYAMLTableRenderer creates a new YAMLTableRenderer.

func (*YAMLTableRenderer) AddRow added in v0.5.0 

func (b *YAMLTableRenderer) AddRow(row []string)

AddRow adds a data row.

func (*YAMLTableRenderer) Render added in v0.5.0 

func (r *YAMLTableRenderer) Render() (string, error)

Render returns the table data as a YAML string.

func (*YAMLTableRenderer) SetData added in v0.5.0 

func (b *YAMLTableRenderer) SetData(data *TableData)

SetData sets the table data directly.

func (*YAMLTableRenderer) SetHeaders added in v0.5.0 

func (b *YAMLTableRenderer) SetHeaders(headers []string)

SetHeaders sets the column headers.

type YAMLTreeRenderer added in v0.5.0 

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

YAMLTreeRenderer renders a TreeNode hierarchy as YAML.

func NewYAMLTreeRenderer added in v0.5.0 

func NewYAMLTreeRenderer() *YAMLTreeRenderer

NewYAMLTreeRenderer creates a new YAMLTreeRenderer.

func (*YAMLTreeRenderer) Render added in v0.5.0 

func (r *YAMLTreeRenderer) Render() (string, error)

Render returns the tree as a YAML string.

func (*YAMLTreeRenderer) SetRoot added in v0.5.0 

func (r *YAMLTreeRenderer) SetRoot(node *TreeNode)

SetRoot sets the root node of the tree.

Source Files

View all Source files

Directories

Path Synopsis
d2 module
daghtml module
delimited module
enum module
envdetect module
escape module
graph module
internal
gentest
markdown module
markup module
nom module
plantuml module
sort module
table module
testhelpers module
graphtest module
tree module
tui module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.