Tuix.Buffer (tuix v0.1.0)

Copy Markdown View Source

A 2D grid of Tuix.Cells representing one terminal frame.

The grid is row-oriented and sparse: rows maps a row index to a map of column index to cell, and rows or cells that were never written are blank. Row orientation lets frame diffing skip unchanged rows with a single term comparison, which is the common case for incremental updates.

Coordinates are 0-based with {0, 0} at the top-left.

Summary

Types

row()
t()

Functions

at(buffer, x, y)

Returns the cell at {x, y}, or a blank cell if unset.

fill(buffer, arg, cell)

Fills a {x, y, w, h} rectangle with a cell.

grapheme_width(grapheme)

Returns the display width of a grapheme (1 or 2 columns).

new(width, height)

Creates an empty buffer of the given size.

put(buffer, x, y, cell)

Puts a cell at {x, y}. Out-of-bounds writes are ignored.

put_repeat(buffer, x, y, grapheme, count, style \\ [], clip \\ nil)

Writes count copies of a single-width grapheme horizontally starting at {x, y}, clipped to clip. Faster than put_text/6 with a duplicated string: the cell is built once and stamped per column.

put_text(buffer, x, y, string, style \\ [], clip \\ nil)

Writes a single-line string starting at {x, y}, clipped to clip (a {cx, cy, cw, ch} rectangle). Handles wide graphemes: a 2-column grapheme occupies its cell plus a :continuation cell.

row(buffer, y)

Returns row y as a sparse column map, or nil if the row is blank.

text_width(string)

Returns the display width of a full string.

to_text(buffer)

Renders the buffer to a plain-text string (no styling), one line per row, with trailing whitespace trimmed. Useful for tests.

Types

row()

@type row() :: %{required(non_neg_integer()) => Tuix.Cell.t()}

t()

@type t() :: %Tuix.Buffer{
  height: non_neg_integer(),
  rows: %{required(non_neg_integer()) => row()},
  width: non_neg_integer()
}

Functions

at(buffer, x, y)

@spec at(t(), non_neg_integer(), non_neg_integer()) :: Tuix.Cell.t()

Returns the cell at {x, y}, or a blank cell if unset.

fill(buffer, arg, cell)

@spec fill(t(), tuple(), Tuix.Cell.t()) :: t()

Fills a {x, y, w, h} rectangle with a cell.

grapheme_width(grapheme)

@spec grapheme_width(String.t()) :: 1 | 2

Returns the display width of a grapheme (1 or 2 columns).

new(width, height)

@spec new(non_neg_integer(), non_neg_integer()) :: t()

Creates an empty buffer of the given size.

put(buffer, x, y, cell)

@spec put(t(), integer(), integer(), Tuix.Cell.t()) :: t()

Puts a cell at {x, y}. Out-of-bounds writes are ignored.

put_repeat(buffer, x, y, grapheme, count, style \\ [], clip \\ nil)

@spec put_repeat(
  t(),
  integer(),
  integer(),
  String.t(),
  non_neg_integer(),
  keyword(),
  tuple() | nil
) :: t()

Writes count copies of a single-width grapheme horizontally starting at {x, y}, clipped to clip. Faster than put_text/6 with a duplicated string: the cell is built once and stamped per column.

put_text(buffer, x, y, string, style \\ [], clip \\ nil)

@spec put_text(t(), integer(), integer(), String.t(), keyword(), tuple() | nil) :: t()

Writes a single-line string starting at {x, y}, clipped to clip (a {cx, cy, cw, ch} rectangle). Handles wide graphemes: a 2-column grapheme occupies its cell plus a :continuation cell.

row(buffer, y)

@spec row(t(), non_neg_integer()) :: row() | nil

Returns row y as a sparse column map, or nil if the row is blank.

text_width(string)

@spec text_width(String.t()) :: non_neg_integer()

Returns the display width of a full string.

to_text(buffer)

@spec to_text(t()) :: String.t()

Renders the buffer to a plain-text string (no styling), one line per row, with trailing whitespace trimmed. Useful for tests.