Documentation
¶
Overview ¶
Package simple - loader.go handles data loading and value processing for simple graphs.
This file provides:
- Value accumulation and grouping logic
- Structured file (JSON/YAML) parsing
- Data series management
Package simple - parser.go handles command-line argument parsing for simple graphs.
Package simple - printer.go handles rendering of simple bar graphs to the terminal.
This file provides two rendering modes:
- Normal mode: Standard horizontal bar graph with value display
- Condensed mode: Compact Braille character visualization for up to 4 values
Package simple provides an optimized single-value graph implementation for the Charta system.
The simple graph displays a single numeric value as a horizontal bar graph with configurable thresholds, colors, and scaling. It supports both standard and condensed mode (using Braille characters for compact display).
Features ¶
- Automatic and manual scaling with "nice" number algorithms
- Color thresholds (green/yellow/red) based on warning/alert values
- Overflow indicators for values outside scale range
- Condensed mode for displaying up to 4 values per character
- Configurable width, labels, and colors
- Support for negative values with zero marker
Performance Optimizations ¶
This implementation includes several performance optimizations:
- Optimized string parsing in value processing
- Efficient memory allocation for value storage
- Cached formatter instances for consistent styling
- Binary search for optimal scale calculations
Example Usage ¶
```go
cg := &common.Graph{
Width: 50,
Min: 0,
Max: 100,
Label: "CPU Usage",
Warning: 70,
Alert: 90,
}
s := sp.New(cg) s.AddValue(75.5) // Value in warning zone s.Print(true) // Display with warning color ```
Index ¶
- Variables
- type FileGraphStruct
- type FileLineStruct
- type FileStruct
- type Graph
- func (g *Graph) AddToParse(parser *argparse.Parser) *argparse.Parser
- func (g *Graph) AddValue(value float64) (printed bool)
- func (g Graph) GetName() string
- func (g *Graph) InitValues()
- func (g *Graph) New(common *common.Graph) common.Grapher
- func (g *Graph) Print(newline bool)
- func (g *Graph) PrintCondensed(newline bool)
- func (g *Graph) PrintHelpFile(t string)
- func (g *Graph) PrintNormal(newline bool)
- func (g *Graph) ProcessStructuredFile(f, ext string) error
Constants ¶
This section is empty.
Variables ¶
var HelpFiles embed.FS
PrintHelpFile displays embedded help content for a specific file type. Exits the program after displaying help or error.
Parameters:
- t: File type to display help for (e.g., "txt", "json", "yaml")
Functions ¶
This section is empty.
Types ¶
type FileGraphStruct ¶ added in v0.2.0
type FileGraphStruct struct {
Args map[string]string `json:"args"`
Lines []FileLineStruct `json:"lines"`
}
FileGraphStruct represents the configuration for a single graph in an input file. It includes global arguments and a list of data lines.
type FileLineStruct ¶ added in v0.2.0
type FileLineStruct struct {
Args map[string]string `json:"args"`
Values []float64 `json:"values"`
}
FileLineStruct represents a single line of data in an input file. It can have its own arguments and a list of values.
type FileStruct ¶ added in v0.2.0
type FileStruct struct {
Graphs []FileGraphStruct `json:"graphs"`
}
FileStruct represents the root structure of JSON/YAML input files. It contains a list of graphs to be generated.
type Graph ¶ added in v0.5.0
type Graph struct {
Name string
Values []float64 // The current value(s) to display
*common.Graph // Shared configuration and state
}
Graph represents a simple single-value graph that displays one numeric value as a horizontal bar with optional warning/alert thresholds and color coding.
The Graph struct embeds common.Graph to inherit shared functionality while adding graph-specific fields for value storage and display state.
Key Features ¶
- Automatic scale calculation using optimized "nice number" algorithms
- Threshold-based color coding (green/yellow/red)
- Condensed mode support with Braille character rendering
- Efficient memory management for large datasets
- Thread-safe operations for concurrent access
Value Processing ¶
Values are processed in real-time as they are added via [AddValue]. Grouping can be enabled to aggregate multiple values before display.
Performance Characteristics ¶
- O(1) value addition for non-grouped mode
- O(n) value processing for grouped mode (where n = group size)
- O(log m) scale calculation using binary search (where m = threshold table)
- O(w) rendering time (where w = graph width in characters)
func (*Graph) AddToParse ¶ added in v0.5.0
AddToParse registers the "simple" subcommand with the argument parser. This enables users to create simple single-value bar graphs from the command line.
The simple graph supports the following argument categories:
- generic: title, width, file, formatter
- minmax: min, max scale values
- alert: warning and alert thresholds
- groupby/grouptype: value aggregation settings
- label: per-line label configuration
- condensed: Braille character mode
- noansi: plain text output mode
Parameters:
- parser: The main argument parser to add the subcommand to
Returns:
- The subcommand parser for the simple graph type
func (*Graph) AddValue ¶ added in v0.5.0
AddValue adds a numeric value to the simple graph. Handles both single values and grouped values based on the GroupBy setting. When grouping is enabled, values are accumulated and averaged until the group is complete.
Parameters:
- value: The numeric value to add
Returns:
- printed: true if the graph was rendered as a result of adding this value
func (*Graph) InitValues ¶ added in v0.5.0
func (g *Graph) InitValues()
InitValues prints any accumulated values and resets the value buffer. This is called when processing "new" command in input to start a new data series.
If there are accumulated values, they are printed before resetting. This ensures no data is lost when switching to a new series.
func (*Graph) New ¶ added in v0.5.0
New creates a new Simple graph instance and registers it with the common graph system.
Parameters:
- common: Pointer to the shared Graph configuration
Returns:
- common.Grapher: New Simple graph instance implementing the Grapher interface
func (*Graph) Print ¶ added in v0.5.0
Print renders the simple graph to the terminal. Displays a horizontal bar graph with the current value, including: - Scale indicators showing min/max values - Color coding based on warning/alert thresholds - Overflow indicators for values outside the scale range - Automatic scale calculation if min/max are not set
Parameters:
- newline: If true, ends with newline; if false, ends with carriage return
func (*Graph) PrintCondensed ¶ added in v0.6.0
PrintCondensed renders a condensed version of the simple graph that displays up to 4 values simultaneously using Braille characters. This mode is activated with the --condensed flag and overrides the --groupby and --grouptype options.
The condensed mode provides a compact visualization where:
- Up to 4 values are displayed on a single line using Braille dot patterns
- Each value is represented by dots in the Braille character (2x4 grid)
- The graph automatically scales based on min/max values in the dataset
- Color coding is applied based on the maximum value and thresholds
- Overflow indicators (/) show when values exceed the scale range
- A vertical bar (|) marks the zero position when the scale includes negative values
The Braille representation allows for high-density data visualization in limited terminal space, making it ideal for monitoring multiple related metrics simultaneously.
Scale behavior:
- If min is not set and negative values exist, min is auto-calculated
- If max is not set and positive values exist, max is auto-calculated
- Scale is divided into segments based on graph width
Color selection priority:
- User-specified color (--color flag)
- Red if max value exceeds alert threshold
- Yellow if max value exceeds warning threshold
- Green otherwise
func (*Graph) PrintHelpFile ¶ added in v0.5.0
func (*Graph) PrintNormal ¶ added in v0.6.0
PrintNormal renders the standard horizontal bar graph. This is the default rendering mode that displays a single aggregated value as a colored horizontal bar with numeric value overlay.
Features:
- Automatic scale calculation based on value range
- Color coding based on warning/alert thresholds
- Overflow indicators (/ or </>) for out-of-range values
- Value text displayed within or beside the bar
- Support for both positive and negative values
The bar is rendered with:
- Label (16 chars, left-aligned)
- Min value (8 chars, right-aligned)
- Opening bracket or underflow indicator
- Colored bar with value text
- Closing bracket or overflow indicator
- Max value (8 chars, left-aligned)
This optimized version reduces string allocations and improves rendering performance.
func (*Graph) ProcessStructuredFile ¶ added in v0.5.0
ProcessStructuredFile reads and processes JSON or YAML files containing graph data. Supports multiple graphs and lines with individual configurationg.
Parameters:
- f: Path to the file
- ext: File extension (.json, .yaml, or .yml)
Returns:
- error: Any error encountered during file processing
Source Files