terminal_graph/live_graphs

Search:
Group by:

Live terminal graph display helpers.

LiveGraph streams the marker/fill renderer, LiveLineGraph streams the connected ASCII line renderer, and LiveCandleGraph retains bounded OHLC periods. LiveDashboard owns a full-screen lifecycle for arbitrary composed frames, including responsive multiplots. Constructing or importing these types never changes terminal state. Call startLive before draw and ensure stopLive runs from a finally block.

Most applications should access this API through import terminal_graph.

Types

LiveCandleGraph = object
  options*: CandlePlotOptions
  candleLimit*: int
A bounded OHLC history rendered repeatedly by plotCandles. 
LiveDashboard = object
  alternateScreen*: bool

Full-screen terminal lifecycle for an arbitrary rendered frame.

Every draw clears the complete screen from its home position, so old physical rows cannot survive when a terminal resize rewraps the previous frame. On VT-capable terminals, alternateScreen keeps animation frames out of the application's normal screen and scrollback.

LiveGraph = object
  plotter*: Plotter
  width*: int
  height*: int
  useColor*: bool
  showStats*: bool
A plotter configured for repeated full-screen terminal rendering. 
LiveLineGraph = object
  config*: AsciiGraphConfig
  sampleLimit*: int
A bounded collection of series rendered repeatedly by plotMany.

Procs

proc addSeries(graph: var LiveGraph; name: string; style = psLine;
               color = fgCyan; marker = "•"): int {.discardable,
    ...raises: [ValueError], tags: [], forbids: [].}
Adds a series to the underlying plotter and returns its index. 
proc candleCount(graph: LiveCandleGraph): int {....raises: [], tags: [],
    forbids: [].}
Returns the number of retained candles. 
proc clear(graph: var LiveCandleGraph) {....raises: [], tags: [], forbids: [].}
Clears all retained candles and labels. 
proc clear(graph: var LiveGraph) {....raises: [], tags: [], forbids: [].}
Clears samples from every series in the underlying plotter. 
proc clear(graph: var LiveLineGraph) {....raises: [], tags: [], forbids: [].}
Clears samples from every live line series. 
proc clearRange(graph: var LiveCandleGraph) {....raises: [], tags: [], forbids: [].}
Restores automatic price bounds on the candle renderer. 
proc clearRange(graph: var LiveGraph) {....raises: [], tags: [], forbids: [].}
Restores automatic range calculation on the underlying plotter. 
proc draw(dashboard: LiveDashboard; frame: string) {.
    ...raises: [ValueError, IOError], tags: [WriteIOEffect], forbids: [].}

Clears and replaces the complete dashboard frame.

Full redraws deliberately avoid saved logical line counts: after a resize, a terminal may have rewrapped each old line into several physical rows.

proc draw(graph: LiveGraph) {....raises: [ValueError, IOError],
                              tags: [WriteIOEffect, ReadEnvEffect], forbids: [].}

Replaces the current terminal frame with the latest graph contents.

Raises ValueError if startLive has not been called.

proc draw(graph: var LiveCandleGraph) {....raises: [ValueError, Exception, IOError],
                                        tags: [RootEffect, WriteIOEffect],
                                        forbids: [].}
Redraws the streaming candle chart while preserving content above it. 
proc draw(graph: var LiveLineGraph) {....raises: [ValueError, Exception, IOError],
                                      tags: [RootEffect, WriteIOEffect],
                                      forbids: [].}
Redraws the streaming line graph, preserving content above it. 
proc initLiveCandleGraph(maxCandles = 80; options = initCandlePlotOptions();
                         output: File = stdout): LiveCandleGraph {.
    ...raises: [ValueError], tags: [], forbids: [].}
Creates a bounded live candle chart without changing terminal state. 
proc initLiveDashboard(alternateScreen = true; output: File = stdout): LiveDashboard {.
    ...raises: [ValueError], tags: [], forbids: [].}

Creates a side-effect-free full-screen dashboard controller.

output defaults to standard output and is retained for the complete lifecycle. Alternate-screen mode is enabled only for a VT-capable TTY; other outputs still receive deterministic full-screen redraws.

proc initLiveGraph(title: string; unit = ""; maxSamples = DefaultMaxSamples;
                   width = 0; height = 0; useColor = true; showStats = true): LiveGraph {.
    ...raises: [ValueError], tags: [], forbids: [].}

Creates a live graph without modifying the terminal.

Zero dimensions follow the current terminal size on every draw, allowing the graph to adapt when the terminal is resized.

proc initLiveLineGraph(seriesCount = 1; maxSamples = 80;
                       config = initAsciiGraphConfig(); output: File = stdout): LiveLineGraph {.
    ...raises: [ValueError], tags: [], forbids: [].}
Creates a colored streaming line graph without touching terminal state. 
proc isActive(dashboard: LiveDashboard): bool {....raises: [], tags: [],
    forbids: [].}
Returns whether the dashboard owns the configured terminal output. 
proc isActive(graph: LiveCandleGraph): bool {....raises: [], tags: [], forbids: [].}
Returns whether the streaming candle display is active. 
proc isActive(graph: LiveGraph): bool {....raises: [], tags: [], forbids: [].}
Returns whether startLive has been called without a matching stop. 
proc isActive(graph: LiveLineGraph): bool {....raises: [], tags: [], forbids: [].}
Returns whether the streaming display is active. 
proc latestCandle(graph: LiveCandleGraph): Option[Candle] {....raises: [],
    tags: [], forbids: [].}
Returns the newest retained candle, if any. 
proc push(graph: var LiveCandleGraph; labels: openArray[string];
          values: openArray[Candle]) {....raises: [ValueError], tags: [],
                                       forbids: [].}
Atomically validates and appends labelled candles. 
proc push(graph: var LiveCandleGraph; value: Candle) {....raises: [ValueError],
    tags: [], forbids: [].}
Appends one completed candle without a period label. 
proc push(graph: var LiveCandleGraph; value: Candle; label: string) {.
    ...raises: [ValueError], tags: [], forbids: [].}
Appends one completed candle and its period label. 
proc push(graph: var LiveCandleGraph; values: openArray[Candle]) {.
    ...raises: [ValueError], tags: [], forbids: [].}
Atomically validates and appends several unlabelled candles. 
proc push(graph: var LiveGraph; seriesIdx: int; value: float64) {.
    ...raises: [ValueError], tags: [], forbids: [].}
Appends one sample to a live graph series. 
proc push(graph: var LiveGraph; seriesIdx: int; values: openArray[float64]) {.
    ...raises: [ValueError], tags: [], forbids: [].}
Appends several samples to a live graph series. 
proc push(graph: var LiveLineGraph; seriesIdx: int; value: float64) {.
    ...raises: [ValueError], tags: [], forbids: [].}
Appends one sample. NaN creates a visible gap; infinities are rejected. 
proc push(graph: var LiveLineGraph; seriesIdx: int; values: openArray[float64]) {.
    ...raises: [ValueError], tags: [], forbids: [].}
Appends several samples after validating the complete batch. 
proc renderFrame(graph: LiveCandleGraph): string {.
    ...raises: [ValueError, Exception], tags: [RootEffect], forbids: [].}
Renders the newest width-limited candle window without terminal I/O. 
proc renderFrame(graph: LiveGraph): string {....raises: [ValueError],
    tags: [ReadEnvEffect], forbids: [].}
Renders one frame without moving the cursor or writing to stdout. 
proc renderFrame(graph: LiveLineGraph): string {.
    ...raises: [ValueError, Exception], tags: [RootEffect], forbids: [].}
Renders current streaming data without writing or moving the cursor. 
proc sampleCount(graph: LiveLineGraph; seriesIdx: int): int {....raises: [],
    tags: [], forbids: [].}
Returns retained sample count for one live line series. 
proc setRange(graph: var LiveCandleGraph; minimum, maximum: float64) {.
    ...raises: [ValueError], tags: [], forbids: [].}
Sets a fixed price range on the candle renderer. 
proc setRange(graph: var LiveGraph; minimum, maximum: float64) {.
    ...raises: [ValueError], tags: [], forbids: [].}
Sets a fixed range on the underlying plotter. 
proc startLive(dashboard: var LiveDashboard) {....raises: [IOError],
    tags: [WriteIOEffect], forbids: [].}

Enters full-screen mode and hides the cursor.

Calling this procedure again while active has no effect.

proc startLive(graph: var LiveCandleGraph; clearScreen = true) {.
    ...raises: [IOError], tags: [WriteIOEffect], forbids: [].}
Starts the streaming display and hides the terminal cursor. 
proc startLive(graph: var LiveGraph; clearScreen = true) {....raises: [IOError],
    tags: [WriteIOEffect], forbids: [].}

Hides the cursor and optionally clears the terminal before live drawing.

Calling this procedure again while the graph is active has no effect.

proc startLive(graph: var LiveLineGraph; clearScreen = true) {.
    ...raises: [IOError], tags: [WriteIOEffect], forbids: [].}
Starts a streaming line display and hides the terminal cursor. 
proc stopLive(dashboard: var LiveDashboard) {....raises: [IOError],
    tags: [WriteIOEffect], forbids: [].}

Restores attributes, the normal screen, and cursor visibility.

Calling this procedure for an inactive dashboard has no effect.

proc stopLive(graph: var LiveCandleGraph) {....raises: [IOError],
    tags: [WriteIOEffect], forbids: [].}
Stops streaming and restores terminal attributes and cursor visibility. 
proc stopLive(graph: var LiveGraph) {....raises: [IOError], tags: [WriteIOEffect],
                                      forbids: [].}

Restores terminal attributes and cursor visibility.

Calling this procedure for an inactive graph has no effect.

proc stopLive(graph: var LiveLineGraph) {....raises: [IOError],
    tags: [WriteIOEffect], forbids: [].}
Stops streaming and restores terminal attributes and cursor visibility. 
proc updateLatest(graph: var LiveCandleGraph; value: Candle) {.
    ...raises: [ValueError], tags: [], forbids: [].}
Replaces the newest in-progress candle while retaining its label. 
proc updateLatest(graph: var LiveCandleGraph; value: Candle; label: string) {.
    ...raises: [ValueError], tags: [], forbids: [].}
Replaces the newest in-progress candle and its label.

Exports

clearLines, graphAxisColor, graphColorBelow, plot, graphXAxisTickCount, graphCaptionColor, clearCandleRange, DefaultLineCharSet, initAsciiGraphConfig, graphXAxisRange, graphSeriesLegends, AsciiGraphConfig, graphColorGradient, graphYAxisFormatter, Candle, clearTerminal, axisOffset, replaceLinesSequence, synchronizedOutputSequence, plotMany, plotCandles, AxisValueFormatter, initCandlePlotOptions, upperBound, HeatmapSpectrum, plotCandles, labelPrecision, setCandleRange, graphLabelColor, graphSeriesChars, plot, graphWidth, lowerBound, graphSeriesColors, plotMany, LineCharSet, graphCaption, graphHeight, LineGraphOption, candle, CandlePlotOptions, graphColorAbove, plotCandles, clearLinesSequence, graphLineEnding, graphXAxisFormatter, createLineCharSet, plotCandles, replaceLinesSequence, graphLabelColor, graphAxisColor, clearLines, graphColorBelow, plot, graphXAxisTickCount, graphCaptionColor, DefaultLineCharSet, initAsciiGraphConfig, graphXAxisRange, plot, clearTerminal, AxisValueFormatter, graphSeriesLegends, AsciiGraphConfig, graphColorGradient, plotMany, synchronizedOutputSequence, axisOffset, upperBound, HeatmapSpectrum, labelPrecision, graphSeriesChars, graphWidth, lowerBound, graphSeriesColors, plotMany, LineCharSet, graphCaption, graphYAxisFormatter, graphHeight, LineGraphOption, graphColorAbove, clearLinesSequence, graphLineEnding, graphXAxisFormatter, createLineCharSet, render, PlotStyle, clear, Plotter, clearRange, initPlotter, MinimumRenderWidth, Series, MinimumRenderHeight, clear, maxSamples, push, addSeries, initStaticGraph, latest, sampleCount, valueRange, DefaultMaxSamples, setRange, setMaxSamples, SeriesStats, seriesCount, push, statistics, StaticGraph, samples

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