Alaja.Buffer (Alaja v1.0.0)

Copy Markdown View Source

2D grid of cells for rendering terminal content.

Uses a flat tuple for O(1) access per cell and minimal GC pressure. All operations are pure — they return a new buffer without mutating the original.

Fields

  • width — visible width in columns.
  • height — visible height in rows.
  • cells — flat tuple indexed by y * width + x.

Usage

iex> buffer = Alaja.Buffer.new(80, 24)
iex> buffer = Alaja.Buffer.put(buffer, 10, 5, "X", {255, 0, 0})
iex> Alaja.Buffer.get(buffer, 10, 5)

Summary

Types

cell()
coordinates()
t()

Functions

clear(buffer)

Clears all cells in the buffer.

create_empty_buffer()

Creates an empty buffer (width 0, height 0).

fill(buffer, x1, y1, x2, y2, char \\ " ", fg \\ nil, bg \\ nil)

Fills a rectangular region with a cell.

fill_with_opts(buffer, x1, y1, x2, y2, opts)

Fill with keyword options (alternative API).

get(buffer, x, y)

Gets the cell at the specified coordinates.

get_cell(buffer, x, y)

Gets the cell at the specified coordinates (alias for get/3).

merge(buffer1, buffer2)

Merges two buffers. Cells from buffer2 override cells from buffer1.

merge_matrix(buffer, x_start, y_start, matrix)

Merges a matrix of cells into the buffer at specified position.

new(width, height)

Creates a new buffer with the specified dimensions.

put(buffer, x, y, char, fg \\ nil, bg \\ nil)

Puts a cell at the specified coordinates.

range(buffer)

Returns all coordinates in the buffer as a list of {x, y} tuples.

update_cell(buffer, x, y, cell)

Updates a cell at the specified coordinates with a pre-existing cell struct.

update_cell(buffer, x, y, char, fg \\ nil, bg \\ nil)

Updates a cell at the specified coordinates with character and optional colors.

valid_coord?(buffer, x, y)

Checks if the coordinates are within buffer bounds.

write(buffer, x, y, char)

Writes a character to the buffer (alias for put/5-6).

write(buffer, x, y, string, fg)

Writes a string with foreground color only (background transparent).

write(buffer, x, y, char, fg, bg)

Writes a character with colors to the buffer (alias for put/5-6).

write_string(buffer, x, y, string)

Writes a string (without colour parsing) to the buffer at the given position. Each grapheme is written individually left-to-right.

Types

cell()

@type cell() :: Alaja.Cell.t()

coordinates()

@type coordinates() :: {non_neg_integer(), non_neg_integer()}

t()

@type t() :: %Alaja.Buffer{
  cells: tuple(),
  height: non_neg_integer(),
  width: non_neg_integer()
}

Functions

clear(buffer)

@spec clear(t()) :: t()

Clears all cells in the buffer.

Parameters

  • buffer - The buffer to clear

Returns

  • Buffer with all cells cleared

Examples

iex> buffer = Buffer.new(10, 10) |> Buffer.put(5, 5, "X", {255, 0, 0})
iex> cleared = Buffer.clear(buffer)
iex> Buffer.get(cleared, 5, 5).char
" "

create_empty_buffer()

@spec create_empty_buffer() :: t()

Creates an empty buffer (width 0, height 0).

fill(buffer, x1, y1, x2, y2, char \\ " ", fg \\ nil, bg \\ nil)

@spec fill(
  t(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  String.t(),
  Alaja.Cell.color(),
  Alaja.Cell.color()
) :: t()

Fills a rectangular region with a cell.

Parameters

  • buffer - The buffer to fill
  • x1 - Starting x coordinate
  • y1 - Starting y coordinate
  • x2 - Ending x coordinate
  • y2 - Ending y coordinate
  • char - Character to fill with
  • fg - Foreground color
  • bg - Background color

Returns

  • Updated buffer

fill_with_opts(buffer, x1, y1, x2, y2, opts)

@spec fill_with_opts(
  t(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  keyword()
) :: t()

Fill with keyword options (alternative API).

get(buffer, x, y)

@spec get(t(), non_neg_integer(), non_neg_integer()) :: Alaja.Cell.t()

Gets the cell at the specified coordinates.

Parameters

  • buffer - The buffer to read from
  • x - The x coordinate (0-based)
  • y - The y coordinate (0-based)

Returns

  • The cell at the coordinates, or an empty cell if out of bounds

Examples

iex> buffer = Buffer.new(10, 10) |> Buffer.put(5, 5, "A", {255, 0, 0})
iex> Buffer.get(buffer, 5, 5).char
"A"

iex> buffer = Buffer.new(10, 10)
iex> Buffer.get(buffer, 100, 100).char
" "

get_cell(buffer, x, y)

@spec get_cell(t(), non_neg_integer(), non_neg_integer()) :: Alaja.Cell.t()

Gets the cell at the specified coordinates (alias for get/3).

merge(buffer1, buffer2)

@spec merge(t(), t()) :: t()

Merges two buffers. Cells from buffer2 override cells from buffer1.

Useful for Z-index layering where higher Z buffers are merged on top.

Parameters

  • buffer1 - Base buffer
  • buffer2 - Overlay buffer

Returns

  • Merged buffer

merge_matrix(buffer, x_start, y_start, matrix)

@spec merge_matrix(t(), non_neg_integer(), non_neg_integer(), [[Alaja.Cell.t()]]) ::
  t()

Merges a matrix of cells into the buffer at specified position.

Parameters

  • buffer - The buffer to merge into
  • x_start - Starting x coordinate
  • y_start - Starting y coordinate
  • matrix - 2D list of cells to merge

Returns

  • Updated buffer

new(width, height)

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

Creates a new buffer with the specified dimensions.

Uses a flat tuple for O(1) access.

Parameters

  • width - The width of the buffer in cells
  • height - The height of the buffer in cells

Returns

  • A new buffer struct

Examples

iex> Buffer.new(80, 24)
%Buffer{width: 80, height: 24, cells: {...}}

put(buffer, x, y, char, fg \\ nil, bg \\ nil)

@spec put(
  t(),
  non_neg_integer(),
  non_neg_integer(),
  String.t(),
  Alaja.Cell.color(),
  Alaja.Cell.color()
) ::
  t()

Puts a cell at the specified coordinates.

Parameters

  • buffer - The buffer to modify
  • x - The x coordinate (0-based)
  • y - The y coordinate (0-based)
  • char - The character to place
  • fg - Optional foreground color as RGB tuple
  • bg - Optional background color as RGB tuple

Returns

  • Updated buffer

Examples

iex> buffer = Buffer.new(10, 10)
iex> buffer = Buffer.put(buffer, 5, 5, "X", {255, 0, 0}, {0, 0, 0})
iex> Buffer.get(buffer, 5, 5).char
"X"

range(buffer)

@spec range(t()) :: [{non_neg_integer(), non_neg_integer()}]

Returns all coordinates in the buffer as a list of {x, y} tuples.

update_cell(buffer, x, y, cell)

@spec update_cell(t(), non_neg_integer(), non_neg_integer(), Alaja.Cell.t()) :: t()

Updates a cell at the specified coordinates with a pre-existing cell struct.

update_cell(buffer, x, y, char, fg \\ nil, bg \\ nil)

@spec update_cell(
  t(),
  non_neg_integer(),
  non_neg_integer(),
  String.t(),
  Alaja.Cell.color(),
  Alaja.Cell.color()
) :: t()

Updates a cell at the specified coordinates with character and optional colors.

valid_coord?(buffer, x, y)

@spec valid_coord?(t(), non_neg_integer(), non_neg_integer()) :: boolean()

Checks if the coordinates are within buffer bounds.

Parameters

  • buffer - The buffer to check
  • x - The x coordinate
  • y - The y coordinate

Returns

  • true if coordinates are valid
  • false otherwise

write(buffer, x, y, char)

@spec write(t(), non_neg_integer(), non_neg_integer(), String.t()) :: t()

Writes a character to the buffer (alias for put/5-6).

write(buffer, x, y, string, fg)

@spec write(t(), non_neg_integer(), non_neg_integer(), String.t(), Alaja.Cell.color()) ::
  t()
@spec write(t(), non_neg_integer(), non_neg_integer(), String.t(), keyword()) :: t()

Writes a string with foreground color only (background transparent).

write(buffer, x, y, char, fg, bg)

@spec write(
  t(),
  non_neg_integer(),
  non_neg_integer(),
  String.t(),
  Alaja.Cell.color(),
  Alaja.Cell.color()
) :: t()

Writes a character with colors to the buffer (alias for put/5-6).

write_string(buffer, x, y, string)

@spec write_string(t(), non_neg_integer(), non_neg_integer(), String.t()) :: t()

Writes a string (without colour parsing) to the buffer at the given position. Each grapheme is written individually left-to-right.

Characters beyond the buffer width are silently skipped.