terminal_graph/line_graphs

Search:
Group by:

High-fidelity ASCII line graphs inspired by guptarohit/asciigraph.

The upstream implementation is Copyright (c) 2018 Rohit Gupta and licensed under BSD-3-Clause; see THIRD_PARTY_NOTICES.md in the package root.

The renderer supports one or many series, interpolation, soft bounds, captions, legends, custom characters and axis formatters, X-axis labels, standard, indexed, and RGB colors, value gradients, threshold colors, NaN gaps, and custom line endings. Most applications should import the terminal_graph façade rather than this submodule directly.

Types

AsciiGraphConfig = object
  width*: int
  height*: int
  lowerBound*: Option[float64]
  upperBound*: Option[float64]
  offset*: int
  caption*: string
  precision*: Option[int]
  captionColor*: TerminalColor
  axisColor*: TerminalColor
  labelColor*: TerminalColor
  seriesColors*: seq[TerminalColor]
  gradient*: seq[TerminalColor]
  aboveThreshold*: Option[float64]
  aboveColor*: TerminalColor
  belowThreshold*: Option[float64]
  belowColor*: TerminalColor
  seriesLegends*: seq[string]
  lineEnding*: string
  seriesChars*: seq[LineCharSet]
  yAxisValueFormatter*: AxisValueFormatter
  xAxisRange*: Option[tuple[minimum, maximum: float64]]
  xAxisTickCount*: int
  xAxisValueFormatter*: AxisValueFormatter
Complete line-graph configuration. initAsciiGraphConfig supplies defaults; option builders are the more concise public interface. 
AxisValueFormatter = proc (value: float64): string {.closure.}
Callback used to format an X- or Y-axis value. 
LineCharSet = object
  horizontal*: string
  verticalLine*: string
  arcDownRight*: string
  arcDownLeft*: string
  arcUpRight*: string
  arcUpLeft*: string
  endCap*: string
  startCap*: string
  upRight*: string
  downHorizontal*: string
Characters used to connect adjacent samples in one series. 
LineGraphOption = proc (config: var AsciiGraphConfig) {.closure.}
A composable option accepted by plot and plotMany.

Consts

DefaultLineCharSet = (horizontal: "─", verticalLine: "│",
                      arcDownRight: "â•­", arcDownLeft: "â•®",
                      arcUpRight: "╰", arcUpLeft: "╯", endCap: "╴",
                      startCap: "╶", upRight: "└", downHorizontal: "┬")
HeatmapSpectrum: array[21, TerminalColor] = [
    (kind: tckAnsi256, index: 21'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 27'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 33'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 39'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 45'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 51'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 50'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 49'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 48'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 47'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 46'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 82'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 118'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 154'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 190'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 226'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 220'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 214'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 208'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 202'u, red: 0'u, green: 0'u, blue: 0'u),
    (kind: tckAnsi256, index: 196'u, red: 0'u, green: 0'u, blue: 0'u)]
Built-in cool-to-warm ANSI-256 palette.

Procs

proc axisOffset(value: int): LineGraphOption {....raises: [], tags: [], forbids: [].}
Sets the horizontal axis offset. Non-positive values use the default 3. 
proc clearLines(lineCount: int) {....raises: [IOError], tags: [WriteIOEffect],
                                  forbids: [].}
Clears recently rendered lines while preserving terminal content above. 
proc clearLinesSequence(lineCount: int): string {....raises: [], tags: [],
    forbids: [].}
Returns the ANSI sequence that clears the previous lineCount lines. 
proc clearTerminal() {....raises: [IOError], tags: [WriteIOEffect], forbids: [].}
Clears the entire terminal and moves the cursor home. 
proc createLineCharSet(character: string): LineCharSet {....raises: [], tags: [],
    forbids: [].}
Creates a character set with every field set to character. 
proc graphAxisColor(value: TerminalColor): LineGraphOption {....raises: [],
    tags: [], forbids: [].}
Sets both axis lines' color. 
proc graphCaption(value: string): LineGraphOption {....raises: [], tags: [],
    forbids: [].}
Sets a centered caption; surrounding whitespace is removed. 
proc graphCaptionColor(value: TerminalColor): LineGraphOption {....raises: [],
    tags: [], forbids: [].}
Sets the caption color. 
proc graphColorAbove(color: TerminalColor; threshold: float64): LineGraphOption {.
    ...raises: [], tags: [], forbids: [].}
Colors graph points strictly above threshold. 
proc graphColorBelow(color: TerminalColor; threshold: float64): LineGraphOption {.
    ...raises: [], tags: [], forbids: [].}
Colors graph points strictly below threshold. 
proc graphColorGradient(stops: openArray[TerminalColor]): LineGraphOption {.
    ...raises: [], tags: [], forbids: [].}
Colors plotted points by value along the supplied low-to-high palette. 
proc graphHeight(value: int): LineGraphOption {....raises: [], tags: [],
    forbids: [].}
Sets the plot height. Non-positive values restore automatic height. 
proc graphLabelColor(value: TerminalColor): LineGraphOption {....raises: [],
    tags: [], forbids: [].}
Sets X- and Y-axis label color. 
proc graphLineEnding(value: string): LineGraphOption {....raises: [], tags: [],
    forbids: [].}
Sets the line ending, such as "\r\n" for raw Windows terminals. 
proc graphSeriesChars(values: openArray[LineCharSet]): LineGraphOption {.
    ...raises: [], tags: [], forbids: [].}
Sets drawing characters corresponding to each series. 
proc graphSeriesColors(values: openArray[TerminalColor]): LineGraphOption {.
    ...raises: [], tags: [], forbids: [].}
Sets colors corresponding to each series. 
proc graphSeriesLegends(values: openArray[string]): LineGraphOption {.
    ...raises: [], tags: [], forbids: [].}
Sets legend text corresponding to each series. 
proc graphWidth(value: int): LineGraphOption {....raises: [], tags: [], forbids: [].}
Sets the interpolated plot width. Non-positive values restore auto width. 
proc graphXAxisFormatter(formatter: AxisValueFormatter): LineGraphOption {.
    ...raises: [], tags: [], forbids: [].}
Sets a custom X-axis value formatter. 
proc graphXAxisRange(minimum, maximum: float64): LineGraphOption {....raises: [],
    tags: [], forbids: [].}
Enables an X-axis and maps this domain across the plot width. 
proc graphXAxisTickCount(value: int): LineGraphOption {....raises: [], tags: [],
    forbids: [].}
Sets X-axis tick count. Values below two leave the default unchanged. 
proc graphYAxisFormatter(formatter: AxisValueFormatter): LineGraphOption {.
    ...raises: [], tags: [], forbids: [].}
Sets a custom Y-axis value formatter. 
proc initAsciiGraphConfig(): AsciiGraphConfig {....raises: [], tags: [],
    forbids: [].}
Returns the default line-graph configuration. 
proc labelPrecision(value: Natural): LineGraphOption {....raises: [], tags: [],
    forbids: [].}
Sets the number of decimal places on default Y-axis labels. 
proc lowerBound(value: float64): LineGraphOption {....raises: [], tags: [],
    forbids: [].}
Extends the y-axis down to value unless the data is lower. 
proc plot[T: SomeNumber](series: openArray[T]; config: AsciiGraphConfig): string
Plots one numeric series using a reusable configuration object. 
proc plot[T: SomeNumber](series: openArray[T]; options: varargs[LineGraphOption]): string
Plots one numeric series using composable graph options. 
proc plotMany[T: SomeNumber](data: openArray[seq[T]];
                             options: varargs[LineGraphOption]): string
Plots multiple numeric series on the same axes. 
proc plotMany[T: SomeNumber](data: openArray[seq[T]]; config: AsciiGraphConfig): string
Plots multiple numeric series using a reusable configuration object. 
proc replaceLinesSequence(frame: string; previousLineCount: int): string {.
    ...raises: [ValueError], tags: [], forbids: [].}

Returns an ANSI update that replaces a previously rendered frame.

The new lines are painted before their stale tails and any obsolete lower rows are erased. This avoids exposing a cleared intermediate frame, which can appear as flicker or black scan lines on some terminals.

proc synchronizedOutputSequence(update: string): string {....raises: [], tags: [],
    forbids: [].}

Wraps a terminal update in DEC synchronized-output mode.

Supporting terminals hold rendering until the closing sequence, so a complete frame becomes visible at once. Unsupported terminals ignore the private mode and process update normally.

proc upperBound(value: float64): LineGraphOption {....raises: [], tags: [],
    forbids: [].}
Extends the y-axis up to value unless the data is higher.

Made with Nim. Generated: 2026-08-28 00:25:34 UTC