Raxol Core

View Source

Hex.pm Documentation

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

  1. Functional Core, Imperative Shell - Core is pure functional, I/O happens at edges
  2. Zero Dependencies - No external libraries, just Elixir stdlib
  3. Composable - Small, focused functions that compose well
  4. 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