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:
- Style Registry (styles/): Defines all visual styles using lipgloss
- Templates (templates/): Go templates that define output structure
- Renderer: Orchestrates template execution and style application
Rendering Pipeline ¶
The rendering process follows these steps:
- Commands return structured data (DisplayResult or ExecutionContext)
- Renderer executes the appropriate Go template with the data
- Template output contains XML-like style tags (e.g., <Bold>text</Bold>)
- Lipbalm expands style tags to ANSI escape codes
- 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 := &display.DisplayResult{
Command: "status",
Packs: []display.DisplayPack{...},
}
err = renderer.Render(result)
Template System ¶
Templates use standard Go text/template syntax with custom style tags:
<CommandHeader>{{.Command}}</CommandHeader>
<Handler>{{.Handler}}</Handler>
<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:
- Define new styles in styles/styles.go
- Create templates in templates/
- Use the style tags in your templates
For detailed architecture documentation, see docs/dev/20_cli-architecture.txxt
Package output provides output generation functionality
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LoadStylesFromFile ¶
LoadStylesFromFile loads a custom styles configuration from the specified file path. This allows users to override the default styles at runtime.
Types ¶
type ConfigOutputOptions ¶
ConfigOutputOptions contains options specific to config output
type OutputOptions ¶
type OutputOptions struct {
// Type specifies what kind of output to generate
Type OutputType
// Write indicates whether to write the output to files
Write bool
// FileSystem is the filesystem to use (optional, defaults to OS filesystem)
FileSystem types.FS
// Additional options specific to the output type
Config *ConfigOutputOptions
Snippet *SnippetOutputOptions
}
OutputOptions contains options for the output command
type OutputResult ¶
type OutputResult struct {
// Content is the generated content
Content string
// FilesWritten contains paths of files that were written (if Write was true)
FilesWritten []string
// Metadata contains type-specific metadata
Metadata map[string]interface{}
}
OutputResult contains the result of an output operation
func GenerateOutput ¶
func GenerateOutput(opts OutputOptions) (*OutputResult, error)
GenerateOutput generates text output based on the specified type and options
type OutputType ¶
type OutputType string
OutputType represents the type of output being generated
const ( // OutputTypeConfig generates configuration file content OutputTypeConfig OutputType = "config" // OutputTypeSnippet generates shell integration snippets OutputTypeSnippet OutputType = "snippet" )
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:
- Template expansion: Go templates process the data structure
- Style application: Lipbalm converts XML-like tags to ANSI codes
For detailed documentation, see pkg/output/doc.go
func NewRenderer ¶
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 *display.DisplayResult) error
Render processes a DisplayResult through the template pipeline and writes the formatted output.
The rendering process:
- Executes the "result.tmpl" template with the provided data
- Applies style tags using lipbalm (or strips them if noColor is true)
- Writes the final output to the configured writer
Returns an error if template execution or style expansion fails.
func (*Renderer) RenderError ¶
RenderError renders an error message with appropriate styling
func (*Renderer) RenderExecutionContext ¶
func (r *Renderer) RenderExecutionContext(ctx *context.ExecutionContext) error
RenderExecutionContext is a convenience method that transforms ExecutionContext and renders it
func (*Renderer) RenderMessage ¶
RenderMessage renders a simple message with optional styling
type SnippetOutputOptions ¶
type SnippetOutputOptions struct {
Shell string
DataDir string
Provision bool // Install shell integration scripts
}
SnippetOutputOptions contains options specific to snippet output
Source Files
Directories