output

Documentation

Overview

Package output implements a declarative, template-based rendering system for dodot's command-line interface.

Architecture Overview

The output package provides a clean separation between data, structure, and presentation through three main components:

1. Style Registry (styles/): Defines all visual styles using lipgloss
2. Templates (templates/): Go templates that define output structure
3. Renderer: Orchestrates template execution and style application

Rendering Pipeline

The rendering process follows these steps:

1. Commands return structured data (DisplayResult or ExecutionContext)
2. Renderer executes the appropriate Go template with the data
3. Template output contains XML-like style tags (e.g., <Bold>text</Bold>)
4. Lipbalm expands style tags to ANSI escape codes
5. Final output is written to the provided io.Writer

Usage Example

// Create a renderer
renderer, err := output.NewRenderer(os.Stdout, false)
if err != nil {
    return err
}

// Render a DisplayResult
result := &types.DisplayResult{
    Command: "status",
    Packs: []types.DisplayPack{...},
}
err = renderer.Render(result)

Template System

Templates use standard Go text/template syntax with custom style tags:

<CommandHeader>{{.Command}}</CommandHeader>
<PowerUp>{{.PowerUp}}</PowerUp>
<Success>✓</Success>

Style tags correspond to entries in the style registry and are automatically expanded to the appropriate ANSI codes based on terminal capabilities.

Color Support

The renderer automatically detects terminal capabilities and handles:

• Full color terminals (256 colors, true color)
• NO_COLOR environment variable
• Adaptive colors that adjust to light/dark themes
• Graceful fallback to plain text

Extending the System

To add new output formats:

1. Define new styles in styles/styles.go
2. Create templates in templates/
3. Use the style tags in your templates

For detailed architecture documentation, see docs/dev/20_cli-architecture.txxt

Index

• func LoadStylesFromFile(path string) error
• type Renderer
  • func NewRenderer(w io.Writer, noColor bool) (*Renderer, error)
  • func (r *Renderer) Render(result *types.DisplayResult) error
  • func (r *Renderer) RenderError(err error) error
  • func (r *Renderer) RenderExecutionContext(ctx *types.ExecutionContext) error
  • func (r *Renderer) RenderMessage(style, message string) error

Functions

func LoadStylesFromFile

func LoadStylesFromFile(path string) error

LoadStylesFromFile loads a custom styles configuration from the specified file path. This allows users to override the default styles at runtime.

Types

type Renderer

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

Renderer orchestrates the template-based output rendering pipeline. It combines Go templates with lipgloss styling to produce rich terminal output.

The renderer follows a two-phase approach:

1. Template expansion: Go templates process the data structure
2. Style application: Lipbalm converts XML-like tags to ANSI codes

For detailed documentation, see pkg/output/doc.go

func NewRenderer

func NewRenderer(w io.Writer, noColor bool) (*Renderer, error)

NewRenderer creates a new Renderer instance.

Parameters:

• w: The io.Writer to write output to (typically os.Stdout)
• noColor: If true, all style tags will be stripped for plain text output

The renderer will automatically detect terminal capabilities and honor the NO_COLOR environment variable when noColor is false.

func (*Renderer) Render

func (r *Renderer) Render(result *types.DisplayResult) error

Render processes a DisplayResult through the template pipeline and writes the formatted output.

The rendering process:

1. Executes the "result.tmpl" template with the provided data
2. Applies style tags using lipbalm (or strips them if noColor is true)
3. Writes the final output to the configured writer

Returns an error if template execution or style expansion fails.

func (*Renderer) RenderError

func (r *Renderer) RenderError(err error) error

RenderError renders an error message with appropriate styling

func (*Renderer) RenderExecutionContext

func (r *Renderer) RenderExecutionContext(ctx *types.ExecutionContext) error

RenderExecutionContext is a convenience method that transforms ExecutionContext and renders it

func (*Renderer) RenderMessage

func (r *Renderer) RenderMessage(style, message string) error

RenderMessage renders a simple message with optional styling