Raxol Core

Lightweight terminal buffer primitives for Elixir. Pure functional buffer operations with zero runtime dependencies.

Features

Pure Functional - Immutable buffer operations, no side effects
Zero Dependencies - No external runtime dependencies
Lightweight - < 100KB compiled
Fast - Sub-millisecond operations for 80x24 buffers
Flexible - Use with any rendering backend

Installation

Add raxol_core to your list of dependencies in mix.exs:

def deps do
  [
    {:raxol_core, "~> 2.0"}
  ]
end

Quick Start

Create a Buffer

alias Raxol.Core.Buffer

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

# Write text at position
buffer = Buffer.write_at(buffer, 0, 0, "Hello, World!")

# Convert to string for display
IO.puts Buffer.to_string(buffer)

Draw Boxes

alias Raxol.Core.{Buffer, Box}

buffer = Buffer.create_blank_buffer(40, 10)

# Draw a double-line box
buffer = Box.draw_box(buffer, 0, 0, 40, 10, :double)

# Add a title
buffer = Buffer.write_at(buffer, 2, 0, " My Box ", %{bold: true})

IO.puts Buffer.to_string(buffer)

Apply Styles

alias Raxol.Core.{Buffer, Style}

buffer = Buffer.create_blank_buffer(80, 24)

# Create styled text
style = %{
  fg_color: :cyan,
  bg_color: :black,
  bold: true,
  underline: true
}

buffer = Buffer.write_at(buffer, 0, 0, "Styled Text", style)

# Render with ANSI codes
ansi_output = Raxol.Core.Renderer.buffer_to_ansi(buffer)
IO.puts ansi_output

Core Modules

`Raxol.Core.Buffer`

Immutable 2D character buffer with styling support.

Key functions:

create_blank_buffer(width, height) - Create new buffer
write_at(buffer, x, y, text, style \\ %{}) - Write text at position
get_cell(buffer, x, y) - Get cell at position
to_string(buffer) - Convert to plain string
merge(buffer1, buffer2, x, y) - Merge buffers

`Raxol.Core.Renderer`

Convert buffers to various output formats.

Renderers:

buffer_to_ansi(buffer) - ANSI terminal codes
buffer_to_html(buffer) - HTML with inline styles
buffer_to_diff(old, new) - Efficient diff-based updates

`Raxol.Core.Style`

Text styling and color management.

Styles:

Colors: :black, :red, :green, :yellow, :blue, :magenta, :cyan, :white
Attributes: :bold, :italic, :underline, :reverse, :strikethrough
True color: {:rgb, r, g, b}

`Raxol.Core.Box`

ASCII/Unicode box drawing.

Box types:

:single - Single-line box
:double - Double-line box
:rounded - Rounded corners
:heavy - Heavy/bold lines
:ascii - ASCII-only (+, -, |)

Use Cases

Terminal UIs

buffer = Buffer.create_blank_buffer(80, 24)
buffer = Box.draw_box(buffer, 0, 0, 80, 24, :double)
buffer = Buffer.write_at(buffer, 2, 1, "Terminal UI", %{bold: true})

IO.write("\e[2J\e[H")  # Clear screen
IO.puts Renderer.buffer_to_ansi(buffer)

CLI Progress Bars

defmodule ProgressBar do
  alias Raxol.Core.Buffer

  def render(progress, width) do
    buffer = Buffer.create_blank_buffer(width, 1)
    filled = trunc(width * progress)
    bar = String.duplicate("=", filled) <> String.duplicate(" ", width - filled)
    Buffer.write_at(buffer, 0, 0, "[#{bar}]")
  end
end

Custom Renderers

# Use buffers with your own rendering pipeline
buffer = Buffer.create_blank_buffer(80, 24)
buffer = Buffer.write_at(buffer, 0, 0, "Hello")

# Your custom renderer
def my_renderer(buffer) do
  # Convert buffer to your format
  # SVG, PDF, canvas, etc.
end

Web Integration

# Phoenix LiveView
buffer = Buffer.create_blank_buffer(80, 24)
html = Renderer.buffer_to_html(buffer)

# Use in template
<div class="terminal">
  <%= raw html %>
</div>

Architecture

Raxol Core is designed as a pure functional layer with no dependencies:

┌─────────────────────────────┐
│     Your Application        │
│  (Phoenix, CLI, Custom)     │
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│       Raxol Core            │
│  (Buffer, Renderer, Style)  │
│                             │
│  - Pure functions           │
│  - Zero dependencies        │
│  - Immutable data           │
└─────────────────────────────┘

Design Principles

Functional Core, Imperative Shell - Core is pure functional, I/O happens at edges
Zero Dependencies - No external libraries, just Elixir stdlib
Composable - Small, focused functions that compose well
Flexible - Works with any rendering backend

Performance

Benchmarks on 2021 MacBook Pro (M1):

Buffer creation (80x24): ~15μs
Write operations: ~0.5μs
Full render to ANSI: ~280μs
Diff-based update: ~50μs

Target: All operations < 16ms for 60fps rendering.

Package Ecosystem

Raxol Core is part of the modular Raxol framework:

raxol_core (this package) - Buffer primitives
raxol_liveview - Phoenix LiveView integration
raxol_plugin - Plugin system
raxol - Full framework (includes all packages)

When to Use What

Use raxol_core if you want:

Lightweight buffer operations only
Custom rendering pipeline
No framework dependencies
DIY terminal integration

Use raxol_liveview if you want:

Phoenix LiveView terminals
Web-based terminal UIs
Real-time updates

Use raxol if you want:

Full terminal framework
All features included
Enterprise capabilities

Examples

Full examples available in the main repository:

01_hello_buffer - Basic buffer operations
02_box_drawing - Box drawing and styling
03_styled_text - Text styling
04_custom_renderer - Custom rendering

Documentation

Additional documentation available in the main repository:

License

MIT License - See LICENSE file included in this package

Contributing

Contributions welcome! Please visit the main repository for contribution guidelines

Credits

Built by axol.io for raxol.io

Next Page → Changelog - Raxol Core