Gladius - High-Performance Typing Trainer Library

Gladius is a comprehensive Rust library for building typing trainer applications. It provides real-time typing analysis, flexible rendering systems, and detailed performance statistics with a focus on accuracy, performance, and ease of use.

🚀 Quick Start

use gladius::TypingSession;

// Create a typing session
let mut session = TypingSession::new("Hello, world!").unwrap();

// Process user input
while let Some((char, result)) = session.input(Some('H')) {
    println!("Typed '{}': {:?}", char, result);
    break; // Just for demo
}

// Get progress and statistics
println!("Progress: {:.1}%", session.completion_percentage());
println!("WPM: {:.1}", session.statistics().measurements.last()
    .map(|m| m.wpm.raw).unwrap_or(0.0));

💡 Key Features

🏃‍♂️ High Performance

• Fast character processing - Amortized O(1) keystroke handling
• O(1) word lookups - Efficient character-to-word mapping
• Optimized statistics - Welford's algorithm for numerical stability
• Memory efficient - Minimal allocations during typing

📊 Comprehensive Statistics

• Words per minute (raw, corrected, actual)
• Input per minute (raw, actual)
• Accuracy percentages (raw, actual)
• Consistency analysis with standard deviation
• Detailed error tracking by character and word
• Real-time measurements at configurable intervals

🎯 Flexible Rendering

• Character-level rendering with typing state information
• Line-based rendering with intelligent word wrapping
• Cursor position tracking across line boundaries
• Unicode support for international characters and emojis
• Generic renderer interface for any UI framework

⚙️ Configurable Behavior

• Measurement intervals for statistics collection
• Line wrapping options (word boundaries vs. character wrapping)
• Newline handling (respect or ignore paragraph breaks)
• Performance tuning for different use cases

🔗 Relationship to OctoType

Gladius serves as the core engine for OctoType, a TUI typing trainer. While OctoType provides the user interface, configuration system, and TUI experience, Gladius handles all the fundamental typing logic:

• Text processing and character management
• Real-time typing statistics calculation
• Input validation and error tracking
• Rendering pipeline for display
• Performance metrics and analysis

This separation allows:

• Reusability: Other applications can use Gladius as a typing engine
• Testing: Core typing logic can be thoroughly tested independently
• Maintainability: Clear separation of concerns between UI and logic
• Performance: Optimized core without UI overhead

📦 Installation

Add Gladius to your Cargo.toml:

[dependencies]
gladius = "0.3.2"

📚 Documentation

Complete API documentation is available at docs.rs/gladius.

🧪 Examples

Basic Typing Session

use gladius::{TypingSession, CharacterResult};

let mut session = TypingSession::new("The quick brown fox").unwrap();

// Process typing input
match session.input(Some('T')) {
    Some((ch, CharacterResult::Correct)) => println!("Correct: {}", ch),
    Some((ch, CharacterResult::Wrong)) => println!("Wrong: {}", ch),
    Some((ch, CharacterResult::Corrected)) => println!("Corrected: {}", ch),
    Some((ch, CharacterResult::Deleted(state))) => println!("Deleted: {} (was {:?})", ch, state),
    None => println!("No input processed"),
}

Custom Configuration

use gladius::{TypingSession, config::Configuration};

let config = Configuration {
    measurement_interval_seconds: 0.5, // More frequent measurements
};

let session = TypingSession::new("Hello, world!")
    .unwrap()
    .with_configuration(config);

Character-level Rendering

use gladius::TypingSession;

let session = TypingSession::new("hello").unwrap();

let rendered: Vec<String> = session.render(|ctx| {
    let cursor = if ctx.has_cursor { " |" } else { "" };
    let state = match ctx.character.state {
        gladius::State::Correct => "✓",
        gladius::State::Wrong => "✗",
        gladius::State::None => "·",
        _ => "?",
    };
    format!("{}{}{}", ctx.character.char, state, cursor)
});

⚡ Performance Characteristics

🛡️ Thread Safety

Gladius types are not thread-safe by design for maximum performance. Each typing session should be used on a single thread. Multiple sessions can run concurrently on different threads.

🔧 Minimum Supported Rust Version (MSRV)

Gladius supports Rust 1.88.0 and later.

🤝 Contributing

If you have an idea, bug-report or alike, feel free to open an issue or PR - It's more than welcome!

📄 License

Licensed under the MIT License. See LICENSE for details.

Why "Gladius"?

Gladius is the Latin word for a small sword, but in biology, it's the name for the internal, feather-shaped shell of a squid.

Since gladius is the core library of OctoType, this name felt very fitting.