FastANSI v0.1.0 [ALPHA] — High-Performance ANSI & VT Escape Sequence Parser for Java

---

⚡ A zero-dependency, zero-allocation UTF-16 ANSI and VT100/VT220/Xterm escape sequence parser for Java, engineered for ultra-high-performance TUI layouts, terminal graphics, and console telemetry pipelines.

FastANSI is the dedicated high-speed text processing substrate of the FastJava ecosystem. It introduces a highly optimized, stack-free procedural state machine designed to parse raw terminal output streams containing styles, cursor movements, and custom colors into structured cell representations at the physical hardware level.

By operating with absolutely exactly zero object allocations on the Java heap, FastANSI is 100% garbage-collection-free and suited to run in demanding, high-throughput console-composing pipelines.

---

Watch the JMH Benchmark

---

Table of Contents

• Why FastANSI?
• Key Features
• Performance
• API Quick Reference
• Installation
• Documentation
• Platform Support
• Related Projects
• License

---

Why FastANSI?

The mission is to establish the fastest, most comprehensive escape sequence parser in the JVM universe. FastANSI enables terminal viewports to consume raw external ANSI dumps dynamically, process global terminal styling, and support custom 24-bit True Color rendering with zero garbage collection overhead.

---

Quick Start

import fastansi.FastANSI;

public class Demo {
    public static void main(String[] args) {
        String ansiStream = "Hello \033[1;31mRed Bold\033[0m Text!";

        FastANSI.parse(ansiStream, new FastANSI.ANSIListener() {
            @Override
            public void onText(CharSequence text, int start, int end) {
                System.out.println("Text: " + text.subSequence(start, end));
            }

            @Override
            public void onReset() {
                System.out.println("Reset Styles");
            }

            @Override
            public void onBold(boolean enable) {
                System.out.println("Bold: " + enable);
            }

            @Override
            public void onForegroundColor(int colorType, int r, int g, int b) {
                System.out.println("FG Color - Type: " + colorType + ", R:" + r);
            }

            // ... Implement other low-overhead cursor & mode callbacks
        });
    }
}

---

Key Features

• 🚫 Zero Dependencies — Completely standalone, lightweight, pure Java 17 library.
• ⚡ Zero Heap Allocation — Renders cell properties purely using coordinate pointers (start, end) and primitives, avoiding all standard String splits or regex overhead.
• 🎨 Complete Color & Style Support — Full parsing of standard SGR parameters (bold, italic, underlines, standard 4-bit, 8-bit index, and 24-bit True Color RGB).
• 📏 Cursor & Erase Commands — Recognizes all standard VT navigation codes (Cursor up/down/forward/backward, cursor absolute, display/line erasing).
• 📺 Private & OSC Operating Modes — Detects alternate screen buffers (?1049h/l), cursor display toggles (?25h/ l), and window title adjustments via Operating System Commands (OSC).

---

Performance

FastANSI is rigorously profiled using JMH to guarantee zero overhead. Watch the JMH Benchmark

Benchmark: Stripping ANSI escape codes from a text string.

Operation	Standard Regex (replaceAll)	FastANSI State Engine	Speedup	Allocations (GC)
Strip ANSI String	~478 ns / op	~99 ns / op	~4.8x	Zero

Measured on Windows 11, Intel Core i5-1135G7 (Surface Pro 8), JDK 25.0.1. The engine bypasses Thread.sleep via FastDWM to guarantee zero-jitter native heartbeats even under GC pressure.

---

API Quick Reference

Method	Description	Path
parse(input, listener)	Parses a text stream procedurally, triggering corresponding callbacks on the listener.	Reference →
fg(r, g, b) / fg(idx)	Generates 24-bit TrueColor or 8-bit index foreground ANSI escape sequences.	FastANSI.java
bg(r, g, b) / bg(idx)	Generates 24-bit TrueColor or 8-bit index background ANSI escape sequences.	FastANSI.java
cursorTo(row, col)	Generates cursor absolute positioning escape codes.	FastANSI.java

Tip

See REFERENCE.md for complete callback listings, SGR color codes, and parsed parameters.

---

Installation

FastANSI is pure-Java and has zero external dependencies.

Option 1: Maven (Recommended)

Add the JitPack repository and the dependency to your pom.xml:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>
<dependencies>
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastANSI</artifactId>
        <version>v0.1.0</version>
    </dependency>
</dependencies>

Option 2: Gradle (via JitPack)

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.andrestubbe:FastANSI:v0.1.0'
}

Option 3: Direct Download (No Build Tool)

Download the latest JAR directly to add it to your classpath:

1. 📦 fastansi-v0.1.0.jar (The Core Library)

---

Documentation

• REFERENCE.md: Exhaustive catalog of SGR styles, OSC window parameters, and callback contracts.
• PHILOSOPHIE.md: Zero-allocation and low-overhead processing designs.
• ROADMAP.md: Planned milestone features and performance extensions.
• CHANGELOG.md: Planned milestone features and performance extensions.

---

Platform Support

Platform	Status
Windows 10/11	✅ Fully Supported
Linux	✅ Fully Supported
macOS	✅ Fully Supported

---

License

MIT License — See LICENSE file for details.

---

Related Projects

• FastFileIndex - Binary file indexing with mmap support
• FastFileSearch - Prefix Trie, N-Gram index, and Ranking engine
• FastFileWatch - USN Journal-based live file monitoring
• FastCore - Unified JNI loader and platform abstraction

---

Part of the FastJava Ecosystem — Making the JVM faster. Small package. Maximum speed. Zero bloat. 🚀📋