asciigraph

https://pkg.go.dev/github.com/guptarohit/asciigraph
Admin
A Go package that creates lightweight ASCII line graphs with support for single and multiple series,...
Tokens:5,043
Snippets:55
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install asciigraph

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Command to install the package via go get.

```bash
go get -u github.com/guptarohit/asciigraph@latest
```

--------------------------------

### Install asciigraph CLI

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Install the command-line utility via Go or pull the latest Docker image.

```bash
go install github.com/guptarohit/asciigraph/cmd/asciigraph@latest
```

```bash
docker pull ghcr.io/guptarohit/asciigraph:latest
```

--------------------------------

### Display asciigraph help

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

View all available command-line options and flags.

```bash
> asciigraph --help
```

--------------------------------

### Create a basic line graph

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Generate a simple ASCII line graph from a slice of float64 values.

```go
package main

import (
    "fmt"
    "github.com/guptarohit/asciigraph"
)

func main() {
    data := []float64{3, 4, 9, 6, 2, 4, 5, 8, 5, 10, 2, 7, 2, 5, 6}
    graph := asciigraph.Plot(data)

    fmt.Println(graph)
}
```

--------------------------------

### Configure Line Ending

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Sets the line ending sequence, defaulting to \n.

```go
func LineEnding(ending string) Option
```

--------------------------------

### Create colored graphs

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Apply specific colors to multiple data series.

```go
package main

import (
    "fmt"
    "github.com/guptarohit/asciigraph"
)

func main() {
	data := make([][]float64, 4)

	for i := 0; i < 4; i++ {
		for x := -20; x <= 20; x++ {
			v := math.NaN()
			if r := 20 - i; x >= -r && x <= r {
				v = math.Sqrt(math.Pow(float64(r), 2)-math.Pow(float64(x), 2)) / 2
			}
			data[i] = append(data[i], v)
		}
	}
	graph := asciigraph.PlotMany(data, asciigraph.Precision(0), asciigraph.SeriesColors(
		asciigraph.Red,
		asciigraph.Yellow,
		asciigraph.Green,
		asciigraph.Blue,
	))

	fmt.Println(graph)
}
```

--------------------------------

### Configuration Option Functions

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Functions to configure graph properties like axis color and captions.

```go
func AxisColor(ac AnsiColor) Option
```

```go
func Caption(caption string) Option
```

--------------------------------

### Add X-axis support

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Configure an X-axis range and tick count for the graph.

```go
package main

import (
	"fmt"
	"github.com/guptarohit/asciigraph"
)

func main() {
	data := []float64{3, 4, 9, 6, 2, 4, 5, 8, 5, 10, 2, 7, 2, 5, 6}
	graph := asciigraph.Plot(data,
		asciigraph.XAxisRange(0, 14),
		asciigraph.XAxisTickCount(3),
	)

	fmt.Println(graph)
}
```

--------------------------------

### CreateCharSet Helper Function

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Creates a CharSet with all fields set to the same character for uniform plotting.

```go
func CreateCharSet(char string) CharSet
```

--------------------------------

### AnsiColor String Method

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Returns the string representation of an AnsiColor.

```go
func (c AnsiColor) String() string
```

--------------------------------

### Configure Conditional Point Coloring

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Functions to color points based on value thresholds.

```go
func ColorAbove(color AnsiColor, threshold float64) Option
```

```go
func ColorBelow(color AnsiColor, threshold float64) Option
```

--------------------------------

### Apply threshold coloring via CLI

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Use the -ca and -cb flags to define color and threshold value pairs directly in the command line.

```bash
seq 1 100 | asciigraph -h 10 -ca red,80 -cb green,25
```

--------------------------------

### Option Interface Definition

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Represents a configuration setting for the graph.

```go
type Option interface {
	// contains filtered or unexported methods
}
```

--------------------------------

### Real-time graph from data stream

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Use the -r flag to enable real-time plotting of a continuous data stream.

```bash
ping -i.2 google.com | grep -oP '(?<=time=).*(?=ms)' --line-buffered | asciigraph -r -h 10 -w 40 -c "realtime plot data (google ping in ms) from stdin"
```

--------------------------------

### CreateCharSet(string)

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Creates a CharSet where all characters are set to the provided string.

```APIDOC
## func CreateCharSet(char string)

### Description
Creates a CharSet with all fields set to the same character. This is useful for simple uniform character sets like "*", "•", "#", etc.

### Parameters
- **char** (string) - Required - The character to use for all CharSet fields.
```

--------------------------------

### Apply gradient coloring

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Use SeriesColorGradient to color points based on their values using a spectrum.

```go
package main

import (
	"fmt"
	"github.com/guptarohit/asciigraph"
)

func main() {
	data := []float64{1, 2, 3, 4, 5, 6, 7, 8, 9, 8, 7, 6, 5, 4, 3, 2, 1}
	graph := asciigraph.Plot(data,
		asciigraph.Height(10),
		asciigraph.SeriesColorGradient(asciigraph.HeatmapSpectrum...),
	)
	fmt.Println(graph)
}
```

--------------------------------

### AnsiColor Type and Constants

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Type definition and common color constants for terminal output styling.

```go
type AnsiColor byte
```

```go
var (
	Default              AnsiColor = 0
	AliceBlue            AnsiColor = 255
	AntiqueWhite         AnsiColor = 255
	Aqua                 AnsiColor = 14
	Aquamarine           AnsiColor = 122
	Azure                AnsiColor = 15
	Beige                AnsiColor = 230
	Bisque               AnsiColor = 224
	Black                AnsiColor = 188 // dummy value
	BlanchedAlmond       AnsiColor = 230
	Blue                 AnsiColor = 12
	BlueViolet           AnsiColor = 92
	Brown                AnsiColor = 88
	BurlyWood            AnsiColor = 180
	CadetBlue            AnsiColor = 73
	Chartreuse           AnsiColor = 118
	Chocolate            AnsiColor = 166
	Coral                AnsiColor = 209
	CornflowerBlue       AnsiColor = 68
	Cornsilk             AnsiColor = 230
	Crimson              AnsiColor = 161
	Cyan                 AnsiColor = 14
	DarkBlue             AnsiColor = 18
	DarkCyan             AnsiColor = 30
	DarkGoldenrod        AnsiColor = 136
	DarkGray             AnsiColor = 248
	DarkGreen            AnsiColor = 22
	DarkKhaki            AnsiColor = 143
	DarkMagenta          AnsiColor = 90
	DarkOliveGreen       AnsiColor = 59
	DarkOrange           AnsiColor = 208
	DarkOrchid           AnsiColor = 134
	DarkRed              AnsiColor = 88
	DarkSalmon           AnsiColor = 173
	DarkSeaGreen         AnsiColor = 108
	DarkSlateBlue        AnsiColor = 60
	DarkSlateGray        AnsiColor = 238
	DarkTurquoise        AnsiColor = 44
	DarkViolet           AnsiColor = 92
	DeepPink             AnsiColor = 198
	DeepSkyBlue          AnsiColor = 39
	DimGray              AnsiColor = 242
	DodgerBlue           AnsiColor = 33
	Firebrick            AnsiColor = 124
	FloralWhite          AnsiColor = 15
	ForestGreen          AnsiColor = 28
	Fuchsia              AnsiColor = 13
	Gainsboro            AnsiColor = 253
	GhostWhite           AnsiColor = 15
	Gold                 AnsiColor = 220
	Goldenrod            AnsiColor = 178
	Gray                 AnsiColor = 8
)
```

--------------------------------

### Configure Caption Color

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Sets the color for the graph caption.

```go
func CaptionColor(ac AnsiColor) Option
```

--------------------------------

### Configure X-Axis Settings

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Functions to control X-axis range, tick count, and value formatting.

```go
func XAxisRange(min, max float64) Option
```

```go
func XAxisTickCount(n int) Option
```

```go
func XAxisValueFormatter(f XAxisValueFormatterFunc) Option
```

--------------------------------

### Configure Graph Dimensions

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Functions to set the physical dimensions and positioning of the graph.

```go
func Height(h int) Option
```

```go
func Width(w int) Option
```

```go
func Offset(o int) Option
```

--------------------------------

### AnsiColor.String()

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Returns the string representation of an AnsiColor.

```APIDOC
## func (AnsiColor) String()

### Description
Returns the string representation of the AnsiColor value.

### Signature
`func (c AnsiColor) String() string`
```

--------------------------------

### Plot data from stdin

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Pipe data into asciigraph to generate a static plot.

```bash
seq 1 72 | asciigraph -h 10 -c "plot data from stdin" -xmin 0 -xmax 40 -xt 5
```

```bash
seq 1 72 | docker run -i --rm ghcr.io/guptarohit/asciigraph -h 10 -c "plot data from stdin" -xmin 0 -xmax 40 -xt 5
```

--------------------------------

### Heatmap Spectrum Palette

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

A predefined color palette for heatmap-style graphs.

```go
var HeatmapSpectrum = []AnsiColor{
	21, 27, 33, 39, 45, 51,
	50, 49, 48, 47, 46,
	82, 118, 154, 190, 226,
	220, 214, 208, 202, 196,
}
```

--------------------------------

### Configure Series Appearance

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Functions to define characters, colors, gradients, and legends for data series.

```go
func SeriesChars(charSets ...CharSet) Option
```

```go
func SeriesColorGradient(stops ...AnsiColor) Option
```

```go
func SeriesColors(ac ...AnsiColor) Option
```

```go
func SeriesLegends(text ...string) Option
```

--------------------------------

### Configure Axis Bounds

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Sets the minimum or maximum values for the vertical axis.

```go
func LowerBound(min float64) Option
```

```go
func UpperBound(max float64) Option
```

--------------------------------

### Configure Label Color

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Sets the color for axis labels.

```go
func LabelColor(ac AnsiColor) Option
```

--------------------------------

### Graph Configuration Options

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

A collection of functional options used to customize the appearance and behavior of generated graphs.

```APIDOC
## func CaptionColor(ac AnsiColor) Option
Sets the caption color.

## func ColorAbove(color AnsiColor, threshold float64) Option
Colors points whose value is strictly above threshold with the given color.

## func ColorBelow(color AnsiColor, threshold float64) Option
Colors points whose value is strictly below threshold with the given color.

## func Height(h int) Option
Sets the graph's height.

## func LabelColor(ac AnsiColor) Option
Sets the axis label color.

## func LineEnding(ending string) Option
Sets the line ending sequence (e.g., "\r\n" or "\n").

## func LowerBound(min float64) Option
Sets the graph's minimum value for the vertical axis.

## func Offset(o int) Option
Sets the graph's offset.

## func Precision(p uint) Option
Sets the graph's precision.

## func SeriesChars(charSets ...CharSet) Option
Sets the character sets for each series.

## func SeriesColorGradient(stops ...AnsiColor) Option
Colors each plotted point by its value along the given stops to produce a gradient.

## func SeriesColors(ac ...AnsiColor) Option
Sets the series colors.

## func SeriesLegends(text ...string) Option
Sets the legend text for the corresponding series.

## func UpperBound(max float64) Option
Sets the graph's maximum value for the vertical axis.

## func Width(w int) Option
Sets the graph's width.

## func XAxisRange(min, max float64) Option
Enables the X-axis and maps the given domain onto the plot width.

## func XAxisTickCount(n int) Option
Sets the number of ticks on the X-axis.

## func XAxisValueFormatter(f XAxisValueFormatterFunc) Option
Formats values printed on the X-axis.

## func YAxisValueFormatter(f YAxisValueFormatterFunc) Option
Formats values printed on the Y-axis.
```

--------------------------------

### Configure Graph Precision

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Sets the numerical precision for the graph.

```go
func Precision(p uint) Option
```

--------------------------------

### Apply threshold coloring to a graph

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Use ColorAbove and ColorBelow to highlight data points exceeding or falling below specific thresholds. These settings take precedence over standard series colors.

```go
package main

import (
	"fmt"
	"github.com/guptarohit/asciigraph"
)

func main() {
	data := []float64{42, 48, 55, 81, 85, 91, 87, 34, 12, 17, 10, 18, 55, 50}
	graph := asciigraph.Plot(data,
		asciigraph.Height(10),
		asciigraph.Width(25),
		asciigraph.LowerBound(0),
		asciigraph.UpperBound(100),
		asciigraph.Caption("CPU usage % (red: critical, green: idle)"),
		asciigraph.ColorAbove(asciigraph.Red, 80),
		asciigraph.ColorBelow(asciigraph.Green, 25),
	)
	fmt.Println(graph)
}
```

--------------------------------

### Caption(string)

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Returns an Option to set the graph caption.

```APIDOC
## func Caption(caption string)

### Description
Returns an Option that sets the caption for the graph.

### Parameters
- **caption** (string) - Required - The text to display as the graph caption.
```

--------------------------------

### Multi-series real-time graph

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Plot multiple data series simultaneously by specifying the number of series and corresponding colors/legends.

```bash
{unbuffer paste -d, <(ping -i 0.4 google.com | sed -u -n -E 's/.*time=(.*)ms.*/\1/p') <(ping -i 0.4 duckduckgo.com | sed -u -n -E 's/.*time=(.*)ms.*/\1/p') } | asciigraph -r -h 15 -w 60 -sn 2 -sc "blue,red" -c "Ping Latency Comparison" -sl "Google, DuckDuckGo"
```

--------------------------------

### Default Character Set

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

The default box-drawing characters used for rendering graph elements.

```go
var DefaultCharSet = CharSet{
	Horizontal:     "─",
	VerticalLine:   "│",
	ArcDownRight:   "╭",
	ArcDownLeft:    "╮",
	ArcUpRight:     "╰",
	ArcUpLeft:      "╯",
	EndCap:         "╴",
	StartCap:       "╶",
	UpRight:        "└",
	DownHorizontal: "┬",
}
```

--------------------------------

### CharSet Structure Definition

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Defines the characters used for plotting a series, including lines, arcs, and caps.

```go
type CharSet struct {
	Horizontal     string // Horizontal line character (default: ─)
	VerticalLine   string // Vertical line character (default: │)
	ArcDownRight   string // Arc character going down and right (default: ╭)
	ArcDownLeft    string // Arc character going down and left (default: ╮)
	ArcUpRight     string // Arc character going up and right (default: ╰)
	ArcUpLeft      string // Arc character going up and left (default: ╯)
	EndCap         string // End cap character (default: ╴)
	StartCap       string // Start cap character (default: ╶)
	UpRight        string // Axis corner character (default: └)
	DownHorizontal string // X-axis tick mark character (default: ┬)
}
```

--------------------------------

### func Plot

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Generates an ASCII graph for a single series of float64 values.

```APIDOC
## func Plot(series []float64, options ...Option) string

### Description
Returns an ASCII graph representation for a provided series of data points.

### Parameters
- **series** ([]float64) - Required - The data points to plot.
- **options** (...Option) - Optional - Configuration options to customize the graph appearance.
```

--------------------------------

### Graph Plotting Functions

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Functions to generate ASCII graphs for single or multiple data series.

```go
func Plot(series []float64, options ...Option) string
```

```go
func PlotMany(data [][]float64, options ...Option) string
```

--------------------------------

### Configure Y-Axis Formatting

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Sets the formatter function for Y-axis values.

```go
func YAxisValueFormatter(f YAxisValueFormatterFunc) Option
```

--------------------------------

### Add legends to multi-series graphs

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Use SeriesLegends to label multiple data series in a single plot. Ensure the number of legends matches the number of series provided.

```go
package main

import (
	"fmt"
	"github.com/guptarohit/asciigraph"
	"math"
)

func main() {
	data := make([][]float64, 3)
	for i := 0; i < 3; i++ {
		for x := -12; x <= 12; x++ {
			v := math.NaN()
			if r := 12 - i; x >= -r && x <= r {
				v = math.Sqrt(math.Pow(float64(r), 2)-math.Pow(float64(x), 2)) / 2
			}
			data[i] = append(data[i], v)
		}
	}
	graph := asciigraph.PlotMany(data,
		asciigraph.Precision(0),
		asciigraph.SeriesColors(asciigraph.Red, asciigraph.Green, asciigraph.Blue),
		asciigraph.SeriesLegends("Red", "Green", "Blue"),
		asciigraph.Caption("Series with legends"))
	fmt.Println(graph)
}
```

--------------------------------

### Terminal Clearing Variables

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Variables used for clearing terminal output.

```go
var Clear func()
```

```go
var ColorNames = map[string]AnsiColor{}/* 141 elements not displayed */
```

--------------------------------

### Plot multiple series

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Generate a graph containing multiple data series using PlotMany.

```go
package main

import (
    "fmt"
    "github.com/guptarohit/asciigraph"
)

func main() {
	data := [][]float64{{0, 1, 2, 3, 3, 3, 2, 0}, {5, 4, 2, 1, 4, 6, 6}}
	graph := asciigraph.PlotMany(data)

	fmt.Println(graph)
}
```

--------------------------------

### Define Formatter Types

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Function types used for custom formatting of axis values.

```go
type XAxisValueFormatterFunc func(float64) string
```

```go
type YAxisValueFormatterFunc func(float64) string
```

--------------------------------

### func PlotMany

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Generates an ASCII graph for multiple series of float64 values.

```APIDOC
## func PlotMany(data [][]float64, options ...Option) string

### Description
Returns an ASCII graph representation for multiple series of data points.

### Parameters
- **data** ([][]float64) - Required - A slice of data series to plot.
- **options** (...Option) - Optional - Configuration options to customize the graph appearance.
```

--------------------------------

### Terminal Line Clearing Function

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Erases the last n lines of the terminal output.

```go
func ClearLines(n int)
```

--------------------------------

### func ClearLines

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Erases a specified number of lines from the terminal.

```APIDOC
## func ClearLines(n int)

### Description
Erases the last n lines by moving the cursor up and clearing to the end of the screen. Content above those lines is preserved.

### Parameters
- **n** (int) - Required - The number of lines to clear.
```

--------------------------------

### Format Y-axis values

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Use YAxisValueFormatter to customize how Y-axis labels are rendered, useful for units like bytes or durations.

```go
package main

import (
	"fmt"

	"github.com/guptarohit/asciigraph"
)

func main() {
	data := []float64{
		30 * 1024 * 1024 * 1024,
		70 * 1024 * 1024 * 1024,
		2 * 1024 * 1024 * 1024,
	}

	graph := asciigraph.Plot(data,
		asciigraph.Height(5),
		asciigraph.Width(45),
		asciigraph.YAxisValueFormatter(func(v float64) string {
			return fmt.Sprintf("%.2f GiB", v/1024/1024/1024)
		}),
	)

	fmt.Println(graph)
}
```

--------------------------------

### AxisColor(AnsiColor)

Source: https://pkg.go.dev/github.com/guptarohit/asciigraph

Returns an Option to set the axis color for a graph.

```APIDOC
## func AxisColor(ac AnsiColor)

### Description
Returns an Option that sets the axis color of the graph.

### Parameters
- **ac** (AnsiColor) - Required - The color to apply to the axis.
```
Tokens:
Raw