Resize-safe live display support for mutable terminal tables.

LiveTable separates data updates from terminal ownership. Applications mutate table or use the convenience update procedures, then call draw. Full-screen mode replaces the complete terminal frame and can use the terminal's alternate screen. In-place mode preserves content above the table and accounts for terminal rows created by wrapping after a resize.

Imports

renderers

Types

LiveTable = object table*: Table options*: LiveTableOptions when defined(windows):: A mutable table paired with an explicit live terminal lifecycle.
LiveTableMode = enum ltmFullScreen, ltmInPlace: Selects whether a live table owns the screen or only its recent rows.
LiveTableOptions = object mode*: LiveTableMode alternateScreen*: bool availableWidth*: int ## Complete table width. Zero detects the terminal width on every draw. fallbackWidth*: int ## Used when automatic terminal-width detection is unavailable. maxRows*: int ## Maximum retained body rows. Zero keeps every row.: Terminal lifecycle, sizing, and row-retention configuration.

Procs

proc addRow(live: var LiveTable; row: Row) {....raises: [ValueError], tags: [], forbids: [].}: Appends a row and removes the oldest rows beyond maxRows.
proc addRow(live: var LiveTable; values: varargs[string, `$`]) {. ...raises: [ValueError], tags: [], forbids: [].}: Appends a row and removes the oldest rows beyond maxRows.
proc draw(live: var LiveTable) {....raises: [ValueError, IOError], tags: [ReadEnvEffect, WriteIOEffect], forbids: [].}: Renders and replaces the current live table frame.

Full-screen mode always redraws from a cleared home position. In-place mode clears the physical height of the previous frame at the newly detected width, which accounts for resize-induced terminal wrapping.
proc initLiveTable(table: Table; options = initLiveTableOptions(); output: File = stdout): LiveTable {....raises: [ValueError], tags: [], forbids: [].}: Creates a live table without changing terminal state.

output is retained for the complete lifecycle. Automatic sizing uses the process terminal width; set availableWidth for a deterministic custom output or test stream.
proc initLiveTableOptions(): LiveTableOptions {....raises: [], tags: [], forbids: [].}: Returns resize-safe full-screen defaults.
proc isActive(live: LiveTable): bool {....raises: [], tags: [], forbids: [].}: Returns whether startLive has been called without a matching stop.
proc maxRows(live: LiveTable): int {....raises: [], tags: [], forbids: [].}: Returns the current body-row retention limit; zero means unlimited.
proc renderFrame(live: LiveTable): string {....raises: [ValueError], tags: [ReadEnvEffect], forbids: [].}: Responsively renders the current table without modifying terminal state.
proc replaceRow(live: var LiveTable; rowIndex: int; row: Row) {. ...raises: [ValueError], tags: [], forbids: [].}: Replaces one body row after validating its shape.
proc replaceRow(live: var LiveTable; rowIndex: int; values: varargs[string, `$`]) {. ...raises: [ValueError], tags: [], forbids: [].}: Replaces one body row after validating its shape.
proc setMaxRows(live: var LiveTable; maxRows: int) {....raises: [ValueError], tags: [], forbids: [].}: Changes the body-row retention limit and immediately trims older rows.
proc startLive(live: var LiveTable) {....raises: [ValueError, IOError], tags: [WriteIOEffect], forbids: [].}: Starts the configured display and hides the cursor.

Calling this procedure again while active has no effect. Alternate-screen mode applies to a full-screen live table attached to a VT-capable TTY.
proc stopLive(live: var LiveTable) {....raises: [IOError], tags: [WriteIOEffect], forbids: [].}: Restores attributes, screen state, and cursor visibility.

Calling this procedure for an inactive table has no effect.
proc updateCell[T](live: var LiveTable; rowIndex, columnIndex: int; value: T): Replaces one body cell's text without rebuilding the table.

terminal_table/live_tables

Imports

Types

Procs

Exports