Charta

A command-line tool for generating colorful terminal graphs from data files or stdin input. Charta supports multiple graph types and various input formats including JSON, YAML, and plain text.

Project Structure

The project is organized into several packages:

• charta.go: Main entry point and CLI argument parsing
• common/: Shared interfaces, types, and utilities for all graph types
• simple/: Simple single-value graph implementation
• minmax/: Min/Max/Average graph implementation
• compare/: Dual-value comparison graph implementation
• cumul/: Cumulative multi-value graph implementation
• heatmap/: Heat map visualization for data matrices
• formatter/: Text formatting and output management (plugin-based architecture)
• formatter/ansi/: ANSI terminal color implementation (supports 8-bit and truecolor)
• formatter/noansi/: Plain text output without ANSI codes
• formatter/svg/: SVG graphics output for web and file export
• utils/: Utility functions (Braille character generation, scale calculation)

Features

• Multiple Graph Types: Simple value graphs, Min/Max/Average graphs, Comparison graphs, Cumulative graphs, and Heat maps
• Flexible Input: Support for JSON, YAML, TXT files, or stdin
• Colorful Output: Terminal-based graphs with customizable colors and label colors
• Grouping: Group multiple values for averaging or analysis
• Thresholds: Warning and alert thresholds with automatic color coding
• Customizable: Adjustable width, min/max values, labels, graph colors, and label colors
• Negative Values: Support for negative values with proper scaling
• Overflow Indicators: Visual indicators when values exceed the scale range
• Plugin Architecture: Extensible formatter system for different output formats

Installation

Requirements

• Go 1.21 or later

Build from source

go build -o charta

Install from repository

go install codeberg.org/spn109/charta@latest

Usage

Basic Command Structure

./charta <graph-type> [graph-options] [values...]

Graph Types

Simple Graph

Displays a single value as a horizontal bar graph:

./charta simple 75
./charta simple --min 0 --max 100 --label "CPU Usage" 85

MinMax Graph

Displays minimum, average, and maximum values from a dataset:

./charta minmax 10 20 30 40 50
./charta minmax --label "Response Times" 120 150 180 200 175

Compare Graph

Displays two values side-by-side for direct comparison:

./charta compare 75.5 82.3
./charta compare --label "Performance" --legend "Server A" --legend2 "Server B" 75.5 82.3
./charta compare --color green --color2 blue --max 100 45 52

Cumul Graph

Displays multiple values as stacked colored segments in a single cumulative bar:

# Basic cumulative graph with three values
./charta cumul --values 25.5 40.2 15.8 --colors red green blue --labels CPU Memory Disk

# With title and custom width
./charta cumul --values 45 60 30 --colors red green blue --labels App DB Cache --title "Resource Usage" --width 80

HeatMap Graph

Displays multiple values as colored cells in a grid layout, ideal for visualizing data matrices or temperature maps:

# Basic heat map with gradient colors
./charta heatmap --values 15.5 22.3 35.8 48.2 55.0 62.5 70.1 78.9 85.3 92.7 --byline 10 --mincolor blue --maxcolor red

# With title and labels
./charta heatmap --values 18.5 20.3 22.1 25.8 28.2 26.5 23.0 --byline 7 --leftlabel "Week 1" --rightlabel "°C" --title "Weekly Temperature"

# With manual colors
./charta heatmap --values 1 2 3 4 5 --colors green green yellow red green --byline 5 --title "Status Grid"

# With three-color gradient
./charta heatmap --values 10 20 30 40 50 60 70 80 90 100 --byline 10 --mincolor blue --midcolor yellow --maxcolor red --nbcolors 10

Global Options

• -f, --file <file>: Input file (JSON, YAML, TXT) or "stdin"
• -H, --help_for_file <type>: Display formatted help for file type (txt, json, yaml)
• -b, --groupby <n>: Group N values together (default: 0 - no grouping)
• -B, --grouptype <type>: Group type: avg (average) or sum (default: avg)
• -o, --condensed: Enable condensed mode - displays up to 4 values per line using Braille characters (overrides --groupby and --grouptype)
• -m, --min <value>: Minimum scale value (default: 0)
• -M, --max <value>: Maximum scale value (default: 100)
• -w, --width <value>: Graph width in characters (default: 100)
• -l, --label <text>: Label for the graph (default: "Label")
• -c, --color <color>: Graph color (red, green, yellow, blue, magenta, cyan, grey, orange*, purple*)
• -L, --label_color <color>: Label color (red, green, yellow, blue, magenta, cyan, grey, orange*, purple*)
• -W, --warning <value>: Warning threshold (default: 50)
• -A, --alert <value>: Alert threshold (default: 80)
• -t, --title <text>: Graph title
• -T, --title_color <color>: Title color (default: blue)
• -g, --legend <text>: Legend text for values
• -F, --formatter <name>: Output formatter (ansi, noansi, svg)

*orange and purple require truecolor terminal support

Compare Graph Specific Options

• -G, --legend2 <text>: Legend text for the second value
• -C, --color2 <color>: Color for the second value's bar (red, green, yellow, blue, magenta, cyan, grey, orange*, purple*)

Cumul Graph Specific Options

• -v, --values <value>: Add a value to the cumulative graph (can be used multiple times)
• -c, --colors <colors>: Comma-separated list of colors for each segment
• -l, --labels <labels>: Comma-separated list of labels for the legend
• -g, --nolegend: Hide the legend display

HeatMap Graph Specific Options

• -v, --values <value>: Add a value to the heat map (can be used multiple times)
• -b, --byline <number>: Number of values per line (default: 10)
• -l, --leftlabel <text>: Label displayed on the left side
• -r, --rightlabel <text>: Label displayed on the right side
• -L, --label_color <color>: Color for labels (default: green)
• -c, --colors <colors>: Comma-separated list of colors for manual color assignment
• --mincolor <color>: Starting color for gradient (requires truecolor terminal)
• --midcolor <color>: Middle color for gradient (optional, requires truecolor terminal)
• --maxcolor <color>: Ending color for gradient (requires truecolor terminal)
• --nbcolors <number>: Number of colors in gradient (default: 10)
• -u, --unicode <theme>: Use Unicode characters instead of colored blocks. Available themes: disc, emoji, heart, moon, nocolor, square, weather, weather-colored, zodiac
• -U, --unicodes <chars>: Custom array of Unicode characters for value ranges (comma-separated)
• -g, --nolegend: Hide the legend display

Getting Help

Display formatted help for specific file formats:

# Get help for text format
./charta simple --help_for_file txt

# Get help for JSON format
./charta minmax --help_for_file json

# Get help for YAML format
./charta simple --help_for_file yaml

The help is displayed with beautiful Markdown formatting in your terminal, including:

• Syntax-highlighted code blocks
• Formatted tables
• Structured sections
• Easy-to-read examples

Input File Formats

JSON Format

{
  "type": "simple",
  "args": {
    "max": "500",
    "min": "100",
    "label": "Memory Usage"
  },
  "values": [250, 300, 275]
}

YAML Format

type: minmax
args:
  max: 500
  min: 100
  label: "Response Time"
values:
  - 120
  - 150
  - 180

Text Format

First line contains the type of graph, and after that one argument or value per line, like this:

minmax
label=essai
alert=70
55.0
71
30
42

Examples

Simple Value Display

# Display CPU usage
./charta simple --min 0 --max 100 --label "CPU" 75

# With warning/alert thresholds
./charta simple --warning 70 --alert 90 --label "Disk Usage" 85

# Condensed mode - display multiple values compactly
./charta simple --condensed --label "Metrics" 25.5 50.2 75.8 90.3

# Condensed mode with auto-scaling
./charta simple --condensed --label "Temps" 18.5 22.3 26.7 31.2

Multiple Values Analysis

# Show min/avg/max of response times
./charta minmax --label "Response Time (ms)" --max 300 120 150 180 200 175

Value Comparison

# Compare two servers
./charta compare --label "CPU Usage" --legend "Server A" --legend2 "Server B" 75.5 82.3

# Compare with custom colors
./charta compare --label "Performance" --color green --color2 blue --max 100 45 52

# Compare memory usage
./charta compare --label "Memory" --legend "Before" --legend2 "After" --max 16 8.5 6.2

Cumulative Values Display

# Show resource distribution
./charta cumul --values 45.2 62.8 38.5 --colors red green blue --labels CPU RAM Disk --title "Server Resources"

# Without legend
./charta cumul --values 25 40 15 --colors red green blue --nolegend

Heat Map Visualization

# Temperature monitoring
./charta heatmap --values 15.5 22.3 35.8 48.2 55.0 62.5 70.1 78.9 85.3 92.7 --byline 10 --mincolor blue --maxcolor red --title "Temperature Map"

# Status grid with manual colors
./charta heatmap --values 1 2 3 4 5 --colors green green yellow red green --byline 5 --title "Server Status"

# Multi-row heat map
./charta heatmap --values 18.5 20.3 22.1 25.8 28.2 26.5 23.0 16.2 19.5 21.8 24.3 27.1 25.8 22.5 --byline 7 --leftlabel "Week 1-2" --rightlabel "°C" --title "Temperature Trends"

# Unicode character themes
./charta heatmap --values 10 20 30 40 50 60 70 80 90 100 --byline 10 --unicode disc --title "Disc Theme"
./charta heatmap --values 15 25 35 45 55 65 --byline 6 --unicode weather --leftlabel "Forecast" --title "Weather Pattern"
./charta heatmap --values 5 15 25 35 45 55 65 75 --byline 8 --unicode moon --title "Moon Phases"
./charta heatmap --values 10 20 30 40 50 60 70 80 90 100 --byline 10 --unicode emoji --title "Emoji Theme"

# Custom Unicode characters
./charta heatmap --values 10 30 50 70 90 --byline 5 --unicodes "▁,▃,▅,▇,█" --title "Custom Bars"
./charta heatmap --values 20 40 60 80 100 --byline 5 --unicodes "●,◐,◑,◕,○" --title "Circle Progress"

From Files

# Process JSON file
./charta --file data.json

# Process YAML file
./charta --file config.yaml

# Process text file
./charta --file values.txt

# Pipe data from another command
echo "75" | ./charta simple --label "CPU Usage" --file stdin

# Process streaming data
tail -f logfile | grep "response_time:" | cut -d: -f2 | ./charta simple --label "Response Time" --file stdin

# With grouping and custom width
echo -e "10\n20\n30\n40\n50" | ./charta minmax --label "Stats" --width 60 --groupby 5 --file stdin

# Condensed mode for compact multi-value display
echo -e "15\n25\n35\n45" | ./charta simple --condensed --label "Values" --file stdin

Color Coding

Graphs automatically change color based on thresholds:

• Green: Normal values (below warning threshold)
• Yellow: Warning values (above warning, below alert)
• Red: Alert values (above alert threshold)

Override with --color option for fixed colors.

Output Format

Simple Graph

Label           Min[█████████████████████████████████████                                                           ]Max
                   ^                                    ^                                                           ^
                  Min                                  Value                                                      Max

Simple Graph (Condensed Mode)

The condensed mode displays up to 4 values simultaneously using Braille characters for high-density visualization:

Label                -10[⠀⠀⠿⣿|⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿]100
                     ^                                   ^
                    Min                                  Max

Features of condensed mode:

• Braille Characters: Each character can represent up to 4 values using dot patterns (2x4 grid)
• Zero Marker: A vertical bar | indicates the zero position when the scale includes negative values
• Overflow Indicators:
  • 🯝 (left arrow): Values below minimum scale
  • 🯟 (right arrow): Values above maximum scale
• Color Coding: Based on the maximum value and threshold settings
• Auto-scaling: Automatically adjusts min/max if not specified
• Compact Display: Ideal for monitoring multiple related metrics in limited space

Example with 4 values (25, 50, 75, 90):

./charta simple --condensed --label "Metrics" --max 100 25 50 75 90

MinMax Graph

Label           Min[🮐🮐🮐🮐🮐🮐🮐🮐🮐🮐🮐█████████████⧗██████████████████████████████████████████████                          ]Max
                             ^            ^                                             ^
                            Min         Average                                        Max

For MinMax graphs, the middle marker (⧗) shows the average value position.

Compare Graph

                 ████████████████ Label ████████████████████
                 ^                   ^                     ^
              Value1               Label                 Value2

The compare graph shows two bars side-by-side with a centered label between them, allowing direct visual comparison.

Cumul Graph

        0[🮐🮐🮐🮐🮐🮐🮐🮐🮐🮐🮐🮐🮐🮐🮐🮐🮐🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮘🮙🮙🮙🮙🮙🮙🮙🮙🮙🮙🮙🮙🮙🮙🮙🮙🮙🮙█████████████████████ 81.5]200
        ^                                                                                 ^
       Min                                                                                Max

The cumul graph displays multiple values as stacked colored segments in a single bar. Each segment's width is proportional to its value, and the total is shown within or after the bar. A color-coded legend identifies each segment.

HeatMap Graph

Color Mode (default):

LeftLabel   🮐🮐 🮐🮐 🮘🮘 🮘🮘 🮙🮙 🮙🮙 ██ ██ ██ ██   RightLabel

The heat map displays values as colored cells in a grid layout. Each value is represented by a colored block, with colors determined either by a gradient (based on min/max values) or by manually specified colors. The byline parameter controls how many values appear per row. A legend shows the color-to-value mapping.

Unicode Mode (--unicode):

LeftLabel   🌑🌒🌓🌔🌕🌖🌗🌘   RightLabel
            ^              ^
         Value1        Value8

When using Unicode mode, values are represented by characters instead of colored blocks. Nine predefined themes are available:

• disc: Colored circle emoji (🟢, 🔵, ⚪, 🟡, 🟠, 🔴, 🟣, 🟤, ⚫)
• emoji: Face emoji progression (😡, 😤, 😠, 😒, 😟, 😞, 😐, 😑, 😌, 😊, 😀, 😁, 😂)
• heart: Heart emoji (💚, 💙, 🩵, 🤍, 💛, 🧡, 🩷, 💜, ❤️, 🤎, 🩶, 🖤)
• moon: Moon phase emoji (🌑, 🌒, 🌓, 🌔, 🌕, 🌖, 🌗, 🌘)
• nocolor: Block characters without color ( , ▂, ▃, ▄, ▅, ▆, ▇, █)
• square: Colored square emoji (🟩, 🟦, ⬜, 🟨, 🟧, 🟥, 🟪, 🟫, ⬛)
• weather: Weather emoji (🌪, , 🌬, , 🌧, 🌦, 🌫, 🌥, , 🌣)
• weather-colored: Weather emoji with color variants (🌪️, 🌩️, 🌬️, 🌨️, 🌧️, 🌦️, 🌫️, 🌥️, 🌤️, 🌞)
• zodiac: Zodiac symbols (♈, ♉, ♊, ♋, ♌, ♍, ♎, ♏, ♐, ♑, ♒, ♓)

Custom Unicode Mode (--unicodes):

LeftLabel   ▁▃▅▇█   RightLabel
            ^     ^
         Value1 Value5

You can provide your own Unicode characters for custom visualizations. Characters are mapped to value ranges automatically.

Overflow Indicators

• 🯝 (left arrow): Value is below the minimum scale
• 🯟 (right arrow): Value is above the maximum scale

Code Architecture

The project is structured into several packages:

• common: Defines the Grapher interface and shared data structures. Contains plugin registration, option management, and common parsing utilities.
• simple: Implements the standard bar graph with optional condensed mode using Braille characters.
• compare: Implements the dual-value comparison graph for side-by-side visualization.
• cumul: Implements the cumulative stack graph with multiple colored segments.
• heatmap: Implements the heat map visualization with color gradients and Unicode themes.
• minmax: Implements the min/max/average statistical graph.
• formatter: Plugin-based text formatting system with support for different output formats.
• formatter/ansi: ANSI terminal color implementation supporting both 8-bit and 24-bit truecolor modes.
• formatter/noansi: Plain text output formatter without ANSI escape codes.
• formatter/svg: SVG graphics output formatter for generating scalable vector graphics.
• utils: Provides utility functions including Braille character generation for condensed mode.

Each graph type implements the Grapher interface, which is composed of several sub-interfaces:

// Grapher is the main interface that all graph types must implement.
// It is composed of several sub-interfaces for different responsibilities.
type Grapher interface {
    GraphBuilder   // Creates new graph instances
    GraphNamer     // Returns the graph type name
    GraphParser    // Handles command-line argument parsing
    GraphPrinter   // Renders the graph output
    GraphHelper    // Provides help documentation
    GraphLoader    // Handles file loading and processing
}

// GraphBuilder creates new graph instances
type GraphBuilder interface {
    New(common *Graph) Grapher
}

// GraphNamer returns the graph type identifier
type GraphNamer interface {
    GetName() string
}

// GraphParser handles argument parsing and value processing
type GraphParser interface {
    AddToParse(parser *argparse.Parser) *argparse.Parser
    AddArg(key, value string) bool
    AddValue(value float64) bool
}

// GraphPrinter handles graph rendering
type GraphPrinter interface {
    Print(newline bool)
}

// GraphHelper provides help documentation
type GraphHelper interface {
    PrintHelpFile(t string)
}

// GraphLoader handles file loading and value initialization
type GraphLoader interface {
    InitValues()
    InitVal()
    ParseLine(line string) (printed bool)
    ProcessStructuredFile(f, ext string) error
}

Output Formatters

Charta supports multiple output formatters through a plugin-based architecture. Use the -F or --formatter option to select the desired output format.

ANSI Formatter (default)

The ANSI formatter provides colorful terminal output with automatic detection of terminal capabilities:

# Use ANSI formatter (default)
./charta simple --label "CPU" 75
./charta simple --formatter ansi --label "CPU" 75

Features:

• Automatic detection of 8-bit vs 24-bit (truecolor) terminal support
• Extended colors (orange, purple) in truecolor mode
• Fallback to standard ANSI colors in 8-bit mode
• Optimal for interactive terminal use

NoANSI Formatter

The NoANSI formatter provides plain text output without color codes, ideal for logging or non-terminal output:

# Use plain text formatter
./charta simple --formatter noansi --label "CPU" 75 > output.txt

# Useful for logging
./charta minmax --formatter noansi --label "Response Time" 120 150 180 >> log.txt

Features:

• No ANSI escape codes
• Clean text output suitable for files and logs
• Compatible with any text processing tool

SVG Formatter

The SVG formatter generates scalable vector graphics that can be saved to files or embedded in web pages:

# Generate SVG output
./charta simple --formatter svg --label "CPU" 75 > output.svg

# Create a comparison graph in SVG
./charta compare --formatter svg --label "Performance" --legend "Before" --legend2 "After" 45 52 > comparison.svg

# Generate a heat map in SVG
./charta heatmap --formatter svg --values 10 20 30 40 50 --byline 5 --mincolor blue --maxcolor red > heatmap.svg

# Create a cumulative graph in SVG
./charta cumul --formatter svg --values 25 40 15 --colors red green blue --labels CPU RAM Disk > resources.svg

Features:

• Generates valid SVG markup with proper XML escaping
• Supports all text styles (bold, italic, underline, faint)
• Supports all alignment options (left, center, right)
• Full color support including extended colors (orange, purple)
• Automatic dimension calculation based on content
• Can be embedded in HTML or saved as standalone files
• Scalable without quality loss

SVG output is particularly useful for:

• Generating graphs for web dashboards
• Creating documentation with embedded visualizations
• Exporting graphs for presentations
• Archiving visual data in a scalable format
• Sharing graphs via email or web

Key Features

• Automatic Scale Detection: When min/max values are not specified, Charta automatically calculates appropriate scales using "nice" round numbers (2, 5, 10, 20, 50, 100, etc.)
• Color Caching: Terminal colors are cached to improve performance
• Flexible Input: Supports command-line arguments, files (JSON/YAML/TXT), and stdin
• Grouping: Values can be grouped and averaged for cleaner visualization
• Threshold-based Coloring: Automatic color changes based on warning/alert thresholds

Dependencies

Direct Dependencies

• github.com/hellflame/argparse v1.12.2 - Command line argument parsing -- gopkg.in/yaml.v3 v3.0.1 - YAML parsing

Indirect Dependencies

• github.com/fatih/color v1.16.0 - Terminal color support
• github.com/MichaelMure/go-term-text v0.3.1 - Terminal text utilities
• github.com/gomarkdown/markdown v0.0.0-20231115200524-a660076da3fd - Markdown parsing
• github.com/mattn/go-colorable v0.1.13 - Cross-platform colored terminal output
• github.com/mattn/go-isatty v0.0.20 - Terminal detection
• github.com/mattn/go-runewidth v0.0.13 - Unicode character width
• github.com/rivo/uniseg v0.4.7 - Unicode text segmentation
• go.xrstf.de/go-term-markdown v0.0.0-20231119170546-73a1852b91cc - Terminal markdown rendering
• golang.org/x/sys v0.25.0 - System calls
• golang.org/x/term v0.1.0 - Terminal utilities

Development

Running Tests

The project includes comprehensive test coverage for all graph types and utilities.

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests with verbose output
go test -v ./...

# Run tests for a specific package
go test ./common
go test ./simple
go test ./minmax
go test ./compare
go test ./cumul
go test ./heatmap
go test ./utils
go test ./formatter
go test ./formatter/ansi
go test ./formatter/noansi
go test ./formatter/svg

# Run benchmarks
go test -bench=. ./...

# Run benchmarks for a specific package
go test -bench=. ./simple
go test -bench=. ./minmax

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Test Coverage

Each package includes:

• Unit tests for core functionality
• Integration tests for file processing
• Benchmark tests for performance measurement
• Edge case tests for error handling

Test files include comprehensive documentation explaining what each test verifies.

Code Organization

• All graph types share common functionality through the common package
• File processing logic is centralized to avoid duplication
• Color management uses a plugin-based formatter system with automatic terminal capability detection
• The ANSI formatter automatically detects truecolor support via the COLORTERM environment variable
• Utility functions are separated for reusability
• Graph types register themselves via init() functions for automatic plugin discovery

Distribution binaries versions

👨‍💻 Author

• Philippe SÉRAPHIN - philippe.seraphin@spn109.fr

📄 License

This project is distributed under the Apache 2.0 License.

❤️ Support the Project

If you find Charta useful, please consider supporting its development with a donation: Donate via Paypal

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Guidelines

• Write clear, documented code with Go doc comments
• Add tests for new features
• Update relevant documentation (README, help files)
• Follow Go best practices and conventions
• Run go fmt before committing
• Ensure all tests pass with go test ./...