Raxol.Core.Buffer (Raxol Core v2.0.0)

View Source

Lightweight terminal buffer primitives for Raxol v2.0.

This module provides pure functional buffer operations without framework dependencies. Designed to be used standalone or as the foundation for higher-level abstractions.

Buffer Structure

%{
  lines: [
    %{cells: [
      %{char: " ", style: %{bold: false, fg_color: nil, bg_color: nil}}
    ]}
  ],
  width: 80,
  height: 24
}

Performance Targets

  • Operations complete in < 1ms for 80x24 buffer
  • Zero external dependencies
  • Memory efficient

Examples

# Create a blank buffer
buffer = Raxol.Core.Buffer.create_blank_buffer(80, 24)

# Write text at coordinates
buffer = Raxol.Core.Buffer.write_at(buffer, 5, 3, "Hello, Raxol!")

# Get a specific cell
cell = Raxol.Core.Buffer.get_cell(buffer, 5, 3)

# Render to string
output = Raxol.Core.Buffer.to_string(buffer)

Summary

Types

cell()
line()
t()

Functions

clear(map)

Clears the buffer, resetting all cells to blank.

create_blank_buffer(width, height)

Creates a blank buffer with the specified dimensions.

get_cell(map, x, y)

Retrieves the cell at the specified coordinates.

resize(map, new_width, new_height)

Resizes the buffer to new dimensions.

set_cell(buffer, x, y, char, style)

Updates a single cell at the specified coordinates.

to_string(map)

Converts the buffer to a string representation for debugging.

write_at(buffer, x, y, content, style \\ %{})

Writes text at the specified coordinates with optional styling.

Types

cell()

@type cell() :: %{char: String.t(), style: map()}

line()

@type line() :: %{cells: [cell()]}

t()

@type t() :: %{lines: [line()], width: non_neg_integer(), height: non_neg_integer()}

Functions

clear(map)

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

Clears the buffer, resetting all cells to blank.

Parameters

  • buffer - The buffer to clear

create_blank_buffer(width, height)

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

Creates a blank buffer with the specified dimensions.

Parameters

  • width - Width of the buffer in characters
  • height - Height of the buffer in lines

Examples

iex> buffer = Raxol.Core.Buffer.create_blank_buffer(80, 24)
iex> buffer.width
80
iex> buffer.height
24

get_cell(map, x, y)

@spec get_cell(t(), non_neg_integer(), non_neg_integer()) :: cell() | nil

Retrieves the cell at the specified coordinates.

Parameters

  • buffer - The buffer to read from
  • x - X coordinate (column)
  • y - Y coordinate (row)

Returns

The cell at the specified position, or nil if out of bounds.

resize(map, new_width, new_height)

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

Resizes the buffer to new dimensions.

Parameters

  • buffer - The buffer to resize
  • width - New width
  • height - New height

set_cell(buffer, x, y, char, style)

@spec set_cell(t(), non_neg_integer(), non_neg_integer(), String.t(), map()) :: t()

Updates a single cell at the specified coordinates.

Parameters

  • buffer - The buffer to update
  • x - X coordinate (column)
  • y - Y coordinate (row)
  • char - Character to set
  • style - Style to apply

to_string(map)

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

Converts the buffer to a string representation for debugging.

Parameters

  • buffer - The buffer to convert

write_at(buffer, x, y, content, style \\ %{})

@spec write_at(t(), non_neg_integer(), non_neg_integer(), String.t(), map()) :: t()

Writes text at the specified coordinates with optional styling.

Parameters

  • buffer - The buffer to write to
  • x - X coordinate (column)
  • y - Y coordinate (row)
  • content - Text to write
  • style - Optional style map (default: %{})

Examples

iex> buffer = Raxol.Core.Buffer.create_blank_buffer(80, 24)
iex> buffer = Raxol.Core.Buffer.write_at(buffer, 0, 0, "Hello")
iex> cell = Raxol.Core.Buffer.get_cell(buffer, 0, 0)
iex> cell.char
"H"