Raxol.Terminal.Cell (Raxol v0.5.0)

View Source

Terminal character cell module.

This module handles the representation and manipulation of individual character cells in the terminal screen buffer, including:

  • Character content
  • Text attributes (color, style)
  • Cell state

Summary

Types

Text style for a terminal cell. See Raxol.Terminal.ANSI.TextFormatting.text_style/0 for details.

t()

Functions

Creates a deep copy of a cell.

Checks if the cell is in double-height mode.

Checks if the cell is in double-width mode.

Creates an empty cell.

Checks if a cell is empty.

Compares two cells for equality.

Creates a Cell struct from a map representation, typically from rendering. Expects a map like %{char: integer_codepoint, style: map, is_wide_placeholder: boolean | nil}. Returns nil if the map is invalid.

Returns the character of the cell.

Gets the text style of the cell.

Checks if the cell has a specific attribute.

Checks if the cell has a specific decoration.

Merges a given style map into the cell's style.

Creates a new cell with optional character and style.

Creates a new cell representing the second half of a wide character. Inherits the style from the primary cell.

Sets the character content of a cell.

Sets the text style of the cell.

Creates a copy of a cell with new attributes applied.

Creates a copy of a cell with a new character.

Types

style()

Text style for a terminal cell. See Raxol.Terminal.ANSI.TextFormatting.text_style/0 for details.

t()

@type t() :: %Raxol.Terminal.Cell{
  char: String.t() | nil,
  dirty: boolean(),
  is_wide_placeholder: boolean(),
  style: Raxol.Terminal.ANSI.TextFormatting.text_style() | nil
}

Functions

copy(cell)

Creates a deep copy of a cell.

Examples

iex> cell = Cell.new("A", %{foreground: :red})
iex> copy = Cell.copy(cell)
iex> Cell.get_char(copy)
"A"
iex> Cell.get_style(copy)
%{foreground: :red}

double_height?(cell)

Checks if the cell is in double-height mode.

Examples

iex> cell = Cell.new("A", %{foreground: :red})
iex> Cell.double_height?(cell)
false

double_width?(cell)

Checks if the cell is in double-width mode.

Examples

iex> cell = Cell.new("A", %{foreground: :red})
iex> Cell.double_width?(cell)
false

empty()

@spec empty() :: t()

Creates an empty cell.

empty?(cell)

@spec empty?(t()) :: boolean()

Checks if a cell is empty.

A cell is considered empty if it contains a space character and has the default text formatting style.

Examples

iex> cell = Cell.new()
iex> Cell.is_empty?(cell)
true

iex> cell = Cell.new("A")
iex> Cell.is_empty?(cell)
false

iex> bold_style = TextFormatting.new() |> TextFormatting.apply_attribute(:bold)
iex> cell = Cell.new(" ", bold_style) # Space char but non-default style
iex> Cell.is_empty?(cell)
false

equals?(cell1, cell2)

Compares two cells for equality.

Cells are considered equal if they have the same character and the same style map. Handles comparison with nil.

Examples

iex> style1 = TextFormatting.new() |> TextFormatting.apply_attribute(:bold)
iex> style2 = TextFormatting.new() |> TextFormatting.apply_attribute(:bold)
iex> style3 = TextFormatting.new() |> TextFormatting.apply_attribute(:underline)
iex> cell1 = Cell.new("A", style1)
iex> cell2 = Cell.new("A", style2) # Same char and style attributes
iex> cell3 = Cell.new("B", style1) # Different char
iex> cell4 = Cell.new("A", style3) # Different style
iex> Cell.equals?(cell1, cell2)
true
iex> Cell.equals?(cell1, cell3)
false
iex> Cell.equals?(cell1, cell4)
false
iex> Cell.equals?(cell1, nil)
false
iex> Cell.equals?(nil, cell1)
false
iex> Cell.equals?(nil, nil)
true

from_map(map)

@spec from_map(map()) :: t() | nil

Creates a Cell struct from a map representation, typically from rendering. Expects a map like %{char: integer_codepoint, style: map, is_wide_placeholder: boolean | nil}. Returns nil if the map is invalid.

get_char(cell)

@spec get_char(t()) :: String.t() | char()

Returns the character of the cell.

get_style(cell)

@spec get_style(t()) :: Raxol.Terminal.ANSI.TextFormatting.text_style() | nil

Gets the text style of the cell.

Examples

iex> cell = Cell.new("A", %{foreground: :red})
iex> Cell.get_style(cell)
%{foreground: :red}

has_attribute?(cell, attribute)

Checks if the cell has a specific attribute.

Examples

iex> cell = Cell.new("A", %{foreground: :red})
iex> Cell.has_attribute?(cell, :foreground)
true

has_decoration?(cell, decoration)

Checks if the cell has a specific decoration.

Examples

iex> cell = Cell.new("A", %{foreground: :red})
iex> Cell.has_decoration?(cell, :bold)
false

merge_style(cell, style_to_merge)

Merges a given style map into the cell's style.

Only non-default attributes from the style map will overwrite existing attributes in the cell's style. This prevents merging default values (like bold: false) and unintentionally removing existing attributes.

Examples

iex> initial_style = TextFormatting.new() |> TextFormatting.apply_attribute(:bold) # %{bold: true, ...}
iex> merge_style = TextFormatting.new() |> TextFormatting.apply_attribute(:underline) # %{underline: true, bold: false, ...}
iex> cell = Cell.new("A", initial_style)
iex> merged_cell = Cell.merge_style(cell, merge_style)
iex> Cell.get_style(merged_cell)
%{bold: true, underline: true} # Note: :bold remains, :underline added

new(char \\ "", style \\ nil)

@spec new(String.t() | nil, Raxol.Terminal.ANSI.TextFormatting.text_style() | nil) ::
  t()

Creates a new cell with optional character and style.

Examples

iex> cell = Cell.new()
iex> Cell.is_empty?(cell)
true

iex> cell = Cell.new("A")
iex> Cell.get_char(cell)
"A"

iex> cell = Cell.new("A", %{foreground: :red})
iex> Cell.get_char(cell)
"A"
iex> Cell.get_style(cell)
%{foreground: :red}

new_wide_placeholder(style)

Creates a new cell representing the second half of a wide character. Inherits the style from the primary cell.

set_char(cell, char)

@spec set_char(t(), String.t()) :: t()

Sets the character content of a cell.

Examples

iex> cell = Cell.new()
iex> cell = Cell.set_char(cell, "A")
iex> Cell.get_char(cell)
"A"

set_style(cell, style)

@spec set_style(t(), Raxol.Terminal.ANSI.TextFormatting.text_style() | nil) :: t()

Sets the text style of the cell.

Examples

iex> cell = Cell.new("A")
iex> cell = Cell.set_style(cell, %{foreground: :red})
iex> Cell.get_style(cell)
%{foreground: :red}

with_attributes(cell, attributes)

Creates a copy of a cell with new attributes applied.

Accepts a map of attributes or a list of attribute atoms. If a list is provided, the attributes are applied sequentially, starting from the cell's existing style.

Examples

iex> cell = Cell.new("A", %{bold: true})
iex> new_cell = Cell.with_attributes(cell, %{underline: true}) # Using a map
iex> Cell.get_style(new_cell)
%{bold: true, underline: true} # Merged

iex> cell = Cell.new("B", %{bold: true})
iex> new_cell = Cell.with_attributes(cell, [:underline, :reverse]) # Using a list
iex> Cell.get_style(new_cell)
%{bold: true, underline: true, reverse: true} # Original bold + list applied

with_char(cell, char)

Creates a copy of a cell with a new character.

Examples

iex> cell = Cell.new("A", %{foreground: :red})
iex> new_cell = Cell.with_char(cell, "B")
iex> Cell.get_char(new_cell)
"B"
iex> Cell.get_style(new_cell)
%{foreground: :red}