output

package module
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: May 25, 2026 License: MIT Imports: 11 Imported by: 0

README

go-output

CI Go Report Card GoDoc

A Go library that formats structured data into 16 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 (any data — from root package)
data, _ := output.MarshalJSONIndent(projects, "", "  ")

// CSV (requires go-output/delimited)
w := delimited.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?

  • 16 formats, one API — Same data, different renderers. No format-specific code paths.
  • Type-safe enums — Format, ColorMode — all validated at parse time, never raw strings.
  • Zero heavy deps in root module — go get go-output pulls only x/term. YAML is isolated in serialization/, lipgloss 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.
  • Zero-config color — ColorMode (auto/always/never) with terminal detection. Wired into table, tree, and markdown renderers.

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)
jsonl ✅ JSON Lines — one JSON object per line (separate serialization/ module)
asciidoc ✅ AsciiDoc tables (separate markup/ module)
toml ✅ ✅ TOML serialization (separate serialization/ module)
plantuml ✅ ✅ PlantUML component diagrams (separate plantuml/ module)

All formats implement the Renderer interface:

type Renderer interface {
    Render() (string, error)
}

import (
    "github.com/larsartmann/go-output"
    "github.com/larsartmann/go-output/delimited"
    "github.com/larsartmann/go-output/serialization"
)
Table Formats
// JSON table (array of objects — requires go-output/serialization)
jt := serialization.NewJSONTableRenderer()
jt.SetHeaders([]string{"Name", "Health"})
jt.AddRow([]string{"Alpha", "90%"})
out, _ := jt.Render()
// [{"Name": "Alpha", "Health": "90%"}]

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

// JSON (any data — from root package)
data, _ := output.MarshalJSONIndent(projects, "", "  ")

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

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

// XML (requires go-output/markup)
data, _ := markup.MarshalXMLFromTableData(tableData)

// YAML (any data — requires go-output/serialization)
data, _ := serialization.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 (requires go-output/serialization)
jt := serialization.NewJSONTreeRenderer()
jt.SetRoot(root)
out, _ := jt.Render()
// {"id": "root", "label": "Projects", "children": [...]}

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

// HTML tree (requires go-output/markup)
ht := markup.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 (requires go-output/serialization)
jg := serialization.NewJSONGraphRenderer()
jg.SetNodes(nodes)
jg.SetEdges(edges)
out, _ := jg.Render()
// {"nodes": [...], "edges": [...]}

// YAML graph (requires go-output/serialization)
yg := serialization.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/delimited       # CSV + TSV writers
go get github.com/larsartmann/go-output/serialization   # JSON + YAML marshaling
go get github.com/larsartmann/go-output/markup          # XML + HTML + Streaming HTML
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,
}

Color Modes

All terminal renderers support ColorMode for controlling ANSI color output:

// Table: functional options pattern (requires go-output/table)
tbl := table.New(table.WithColorMode(output.ColorModeAlways))

// Tree: setter method
tree := output.NewASCIITreeRenderer()
tree.SetColorMode(output.ColorModeAlways)

// Markdown: setter method (chains)
md := output.NewMarkdownTable().SetColorMode(output.ColorModeAlways)

// RenderTableData dispatch: pass via RenderOptions
output.RenderTableData(data, output.FormatTree,
    output.RenderOptions{ColorMode: output.ColorModeAlways})

Default ColorModeAuto detects terminal via golang.org/x/term, respects NO_COLOR, CI, FORCE_COLOR.

Streaming Renderer

For large datasets, stream output incrementally:

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

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, zero yaml in production code. (YAML dep isolated in serialization/ module).

require (
    golang.org/x/term v0.43.0
)

Serialization module (JSON + YAML — install separately):

require (
    github.com/go-faster/yaml v0.4.6
)

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 16 formats with color support:

go run ./examples/basic/main.go markdown          # auto color
go run ./examples/basic/main.go tree --color always  # force colors
go run ./examples/basic/main.go table --color never   # no colors

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, delimited, serialization, markup): 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

Index

Constants

This section is empty.

Variables

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

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.

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 MarshalFormat added in v0.6.0 

func MarshalFormat(format string, marshalFn func(any) ([]byte, error), v any) ([]byte, error)

MarshalFormat encodes v using the provided marshal function.

func MarshalJSONIndent 

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

MarshalJSONIndent encodes v to indented JSON.

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 RegisterTableDataMarshaler added in v0.6.0 

func RegisterTableDataMarshaler(format Format, marshaler TableDataMarshaler)

RegisterTableDataMarshaler registers a marshaler for a format. Sub-modules call this from their init() to enable RenderTableData dispatch.

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 (when respective sub-modules are imported).

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 UnmarshalFormat added in v0.6.0 

func UnmarshalFormat(format string, unmarshalFn func([]byte, any) error, data []byte, v any) error

UnmarshalFormat decodes data into v using the provided unmarshal function.

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) SetColorMode added in v0.6.0 

func (r *ASCIITreeRenderer) SetColorMode(mode ColorMode)

SetColorMode sets the color mode for the tree renderer.

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 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 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"
	FormatJSONL    Format = "jsonl"
	FormatAsciiDoc Format = "asciidoc"
	FormatTOML     Format = "toml"
	FormatPlantUML Format = "plantuml"
)

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 (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 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 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) SetColorMode added in v0.6.0 

func (m *MarkdownTable) SetColorMode(mode ColorMode) *MarkdownTable

SetColorMode sets the color mode for terminal output.

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

	// ColorMode controls terminal color output. Defaults to ColorModeAuto.
	ColorMode ColorMode
}

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.

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 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.

Important: Not all implementations provide true streaming. The adapter returned by StreamingRendererFromRenderer collects output before writing. Only StreamingHTMLRenderer (in the markup sub-module) provides genuine streaming behavior.

func StreamingRendererFromRenderer 

func StreamingRendererFromRenderer(r Renderer) StreamingRenderer

StreamingRendererFromRenderer wraps a standard Renderer to implement StreamingRenderer. Important: 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 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 TableDataBase added in v0.6.0 

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

TableDataBase provides common table data storage for renderers.

func (*TableDataBase) AddRow added in v0.6.0 

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

AddRow adds a data row.

func (*TableDataBase) Data added in v0.6.0 

func (b *TableDataBase) Data() *TableData

Data returns the underlying TableData.

func (*TableDataBase) SetData added in v0.6.0 

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

SetData sets the table data directly.

func (*TableDataBase) SetHeaders added in v0.6.0 

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

SetHeaders sets the column headers.

type TableDataMarshaler added in v0.6.0 

type TableDataMarshaler func(w io.Writer, data *TableData, opts RenderOptions) error

TableDataMarshaler renders TableData in a specific format to a writer.

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

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.