Aurora 🎨

"Because life is too short for black and white terminals" 🌈

A powerful terminal formatting and rendering library for Elixir

Aurora is a comprehensive, dependency-free library for terminal formatting, ANSI colors, and text rendering. Transform your terminal output into a colorful, professional experience with minimal effort.

🌟 Overview

Aurora provides a complete solution for terminal text formatting with:

🚀 Potential

While Aurora already provides extensive functionality, the library has significant untapped potential:

The modular design makes it easy to add new capabilities, whether through the library API or CLI commands.

📦 Installation

As a Dependency

Add Aurora to your mix.exs:

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

Then run:

mix deps.get

As a CLI Tool

Build the executable:

mix escript.build

This generates the ./aurora executable.

🎯 Quick Start

Library Usage

# Basic messages
Aurora.Printer.success("Operation completed")
Aurora.Printer.error("An error occurred")
Aurora.Printer.warning("Important warning")
Aurora.Printer.info("Useful information")

# Formatted text
Aurora.Format.format("Hello World!", color: :primary) |> IO.puts()

# Tables
Aurora.Printer.table(
  ["Name", "Age", "Role"],
  [["John", "25", "Developer"], ["Jane", "30", "Designer"]]
)

# Interactive components
name = Aurora.Printer.question("What is your name?")
if Aurora.Printer.yesno("Continue?") == :yes do
  # ...
end

CLI Usage

# Formatted text
./aurora --text="Hello World!" --color=primary --bold

# Messages
./aurora --success="Operation completed"
./aurora --error="An error occurred"

# Tables
./aurora --table --headers="Name,Age" --row="John,25" --row="Jane,30"

# Color conversion
./aurora --convert --from="#FF0000" --to=rgb

📚 Core Features

Color Management

Aurora provides comprehensive color management with multiple formats, manipulation, blending, palette generation, color scheme calculation, and WCAG contrast detection.

Color Formats

Aurora supports multiple color formats with automatic conversion:

Example:

# Automatic format conversion
color = Aurora.Color.to_color_info("#FF0000")
color = Aurora.Color.to_color_info({255, 0, 0})
color = Aurora.Color.to_color_info(:primary)

# Color manipulation
lighter = Aurora.Color.lighten(color, 2)  # 2 tones lighter
darker = Aurora.Color.darken(color, 3)   # 3 tones darker

# Blend colors
mixed = Aurora.Color.blend("#FF0000", "#0000FF", 0.5)  # Mix red and blue

# Generate palettes
{shades, base, tints} = Aurora.Color.generate_palette(color, 5, 5)
shades_only = Aurora.Color.generate_shades(color, 5)
tints_only = Aurora.Color.generate_tints(color, 5)

# Calculate color schemes
analogous = Aurora.Color.analogous(color, 2, 30.0)  # Adjacent colors
mono = Aurora.Color.monochromatic(color, 5)  # Same hue, different saturation/lightness
triad = Aurora.Color.triadic(color)  # 3 equidistant colors
complement = Aurora.Color.complementary(color)  # Opposite color
split_comp = Aurora.Color.split_complementary(color, 30.0)  # Split-complementary
square_colors = Aurora.Color.square(color)  # 4 equidistant colors
compound_colors = Aurora.Color.compound(color, 60.0)  # Tetradic scheme
tones = Aurora.Color.tones(color, 9)  # Tonal variations

# WCAG contrast detection
ratio = Aurora.Color.contrast_ratio(white, black)  # 21.0 (maximum)
meets_aaa = Aurora.Color.meets_contrast_ratio?(white, black, :AAA, :normal)  # true
level = Aurora.Color.contrast_level(white, black)  # :AAA_large

# Apply colors
colored = Aurora.Color.apply_color("Hello!", :primary)
background = Aurora.Color.apply_background_color("Text", :error)

Text Formatting

Comprehensive text formatting with alignment, indentation, and effects:

# Basic formatting
chunk = %Aurora.Structs.ChunkText{text: "Hello world", color: :primary}
format_info = %Aurora.Structs.FormatInfo{chunks: [chunk], align: :center}
result = Aurora.Format.format(format_info)

# Multiple chunks with different colors
chunks = [
  %Aurora.Structs.ChunkText{text: "Error: ", color: :error},
  %Aurora.Structs.ChunkText{text: "File not found", color: :warning}
]
result = Aurora.Format.format(chunks)

ANSI Effects

Apply various text effects:

# Single effect
Aurora.Effects.apply_effect("Hello", :bold)

# Multiple effects
Aurora.Effects.apply_multiple_effects("Hello", [:bold, :underline])

# From EffectInfo struct
effects = %Aurora.Structs.EffectInfo{bold: true, italic: true}
Aurora.Effects.apply_effect_info("Hello", effects)

Gradients

Apply beautiful gradients to text:

# Horizontal gradient
Aurora.Color.apply_gradient("Hello", [:red, :blue])

# Vertical gradient
Aurora.Color.apply_gradient("Hello", [:red, :blue], orientation: :vertical)

# Reverse gradient
Aurora.Color.apply_gradient("Hello", [:red, :blue], orientation: :reverse)

# Logo formatting with gradients
lines = ["  ████  ", " ██████ ", "████████"]
{formatted, _hexes} = Aurora.Format.format_logo(lines, gradient_orientation: :horizontal)

Tables

Create formatted tables with advanced options:

headers = ["Name", "Age", "Role"]
rows = [
  [%Aurora.Structs.ChunkText{text: "John", color: :primary},
   %Aurora.Structs.ChunkText{text: "25", color: :secondary}],
  [%Aurora.Structs.ChunkText{text: "Jane", color: :primary},
   %Aurora.Structs.ChunkText{text: "30", color: :secondary}]
]

Aurora.Printer.table(headers, rows,
  table_align: :center,
  header_align: [:left, :center, :right]
)

Interactive Components

Build interactive CLI interfaces:

# Simple question
name = Aurora.Printer.question("What is your name?")

# Question with options
editor = Aurora.Printer.question_with_options(
  "Which editor do you prefer?",
  [{"vscode", "VS Code"}, {"nvim", "Neovim"}]
)

# Yes/No confirmation
if Aurora.Printer.yesno("Continue?") == :yes do
  # ...
end

# Menu
Aurora.Printer.menu("Options", ["Option 1", "Option 2", "Option 3"])

JSON Formatting

Syntax-highlighted JSON output:

data = %{name: "John", age: 30, active: true}
formatted = Aurora.Format.JSON.format_json(data)
IO.puts(formatted)

🖥️ CLI Reference

Basic Commands

# Text formatting
./aurora --text="Hello" --color=primary --bold

# Messages
./aurora --success="Operation completed"
./aurora --error="An error occurred"
./aurora --warning="Be careful"
./aurora --info="Processing..."

# Components
./aurora --header="Welcome" --align=center
./aurora --separator --char="=" --color=primary
./aurora --breadcrumbs --items="Home,Projects,Aurora"
./aurora --bar --current=50 --total=100

# Tables
./aurora --table --headers="Name,Age" --row="John,25" --row="Jane,30"

# Color conversion
./aurora --convert --from="#FF0000" --to=rgb

Getting Help

# General help
./aurora --help

# Command-specific help
./aurora --text --help
./aurora --message --help
./aurora --table --help
./aurora --convert --help

# Examples
./aurora --examples

Raw Mode

Capture ANSI codes for use in scripts:

result=$(./aurora --text="Success" --color=success --bold --raw)
echo "$result"

🎨 Available Colors

Basic Colors

Status Colors

Special Colors

✨ Available Effects

📖 API Documentation

Main Modules

Key Functions

Color Module

Format Module

Effects Module

Printer Module

🔧 Development

Running Tests

mix test

Code Quality

mix quality

Building Documentation

mix docs

Building Executable

mix escript.build

📊 Architecture

Aurora follows a modular architecture:

This architecture makes it easy to:

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Submit a pull request

📄 License

Apache 2.0 - See LICENSE for details.

🙏 Acknowledgments

Aurora is part of the Ypsilon project ecosystem, designed to provide powerful, elegant tools for Elixir developers.

Made with ❤️ for colorful terminals everywhere