gochart

README

GoChart 📊

A lightweight, modular Go library for creating beautiful ASCII charts in the terminal. Perfect for CLI monitoring tools, dashboards, and data visualization in terminal environments.

Features

• ✅ Vertical Bar Charts with customizable styling
• 🎨 ANSI Color Support with 6 different colors
• 🔧 Highly Configurable with method chaining
• 📏 Auto-scaling based on data values
• 🎯 Flexible Label Handling (short/long labels)
• 🧪 Well Tested with comprehensive unit tests
• 🔌 Modular Design - easy to extend with new chart types
• 🚀 Zero Dependencies - pure Go implementation

Installation

go get github.com/DitzDev/gochart

Quick Start

package main

import (
    "gochart"
    "gochart/bar"
)

func main() {
    // Create sample data
    data := []gochart.DataPoint{
        {Label: "Jan", Value: 25},
        {Label: "Feb", Value: 30},
        {Label: "Mar", Value: 45},
        {Label: "Apr", Value: 35},
        {Label: "May", Value: 50},
    }
    
    // Create and render chart
    chart := bar.NewVerticalBarChart("Monthly Sales", data, 12)
    chart.Render()
}

API Reference

DataPoint

type DataPoint struct {
    Label string  // Label for the data point
    Value int     // Numeric value
}

VerticalBarChart

Constructor

func NewVerticalBarChart(title string, data []DataPoint, height int) *VerticalBarChart

Configuration Methods (Chainable)

// Enable/disable ANSI colors (default: true)
func (v *VerticalBarChart) SetUseColor(useColor bool) *VerticalBarChart

// Show/hide values above bars (default: true)
func (v *VerticalBarChart) SetShowValues(showValues bool) *VerticalBarChart

// Show/hide grid lines (default: false)
func (v *VerticalBarChart) SetShowGrid(showGrid bool) *VerticalBarChart

// Set bar width in characters (default: 3)
func (v *VerticalBarChart) SetBarWidth(width int) *VerticalBarChart

// Set custom maximum value for scaling (default: auto-calculate)
func (v *VerticalBarChart) SetMaxValue(max int) *VerticalBarChart

Rendering Methods

// Render chart to stdout
func (v *VerticalBarChart) Render()

// Get chart as string (useful for testing)
func (v *VerticalBarChart) RenderToString() string

Examples

Basic Chart

data := []gochart.DataPoint{
    {Label: "A", Value: 10},
    {Label: "B", Value: 20},
    {Label: "C", Value: 15},
}

chart := bar.NewVerticalBarChart("Simple Chart", data, 8)
chart.Render()

Customized Chart

data := []gochart.DataPoint{
    {Label: "Q1", Value: 20},
    {Label: "Q2", Value: 40},
    {Label: "Q3", Value: 60},
    {Label: "Q4", Value: 80},
}

chart := bar.NewVerticalBarChart("Quarterly Progress", data, 12).
    SetMaxValue(100).          // Scale to 100
    SetBarWidth(5).            // Wider bars
    SetUseColor(true).         // Enable colors
    SetShowValues(true)        // Show values above bars

chart.Render()

Server Monitoring Example

data := []gochart.DataPoint{
    {Label: "Server1", Value: 80},
    {Label: "Server2", Value: 45},
    {Label: "Server3", Value: 92},
    {Label: "Server4", Value: 67},
}

chart := bar.NewVerticalBarChart("Server CPU Usage (%)", data, 15).
    SetMaxValue(100).
    SetUseColor(false).
    SetShowValues(false)

chart.Render()

Long Labels Support

data := []gochart.DataPoint{
    {Label: "January", Value: 120},
    {Label: "February", Value: 150},
    {Label: "March", Value: 180},
}

chart := bar.NewVerticalBarChart("Monthly Revenue", data, 10)
chart.Render()

Testing

Run the test suite:

go test ./...

Run tests with verbose output:

go test -v ./...

Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-chart-type)
3. Commit your changes (git commit -am 'Add horizontal bar chart')
4. Push to the branch (git push origin feature/new-chart-type)
5. Create a Pull Request

Adding New Chart Types

The library is designed to be easily extensible. To add a new chart type:

1. Create a new package under the main directory (e.g., line/, pie/)
2. Implement the Chart interface
3. Add rendering logic using the render package utilities
4. Add comprehensive tests
5. Update documentation

Roadmap

• Horizontal Bar Charts
• Line Charts
• Pie Charts
• Histogram Charts
• Box Plots
• Scatter Plots
• Advanced Styling Options
• Chart Animations
• Data Export Features

Use Cases

• CLI Monitoring Tools (like htop, top)
• CI/CD Pipeline Dashboards
• Performance Monitoring
• Data Visualization in Terminal
• System Administration Tools
• DevOps Dashboards
• Log Analysis Tools

Requirements

• Go 1.19 or later
• Terminal with ANSI color support (optional)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Index

• type Chart
• type DataPoint

Types

type Chart

type Chart interface {
	Render()

	RenderToString() string
}

type DataPoint

type DataPoint struct {
	Label string
	Value int
}