FastRegex

Status: Educational / Incomplete Test Coverage: 775 examples, 22 failures (97.2%) Last Updated: 2026-01-10

A Crystal library that attempts to compile regular expressions to Ragel finite state machines for fast pattern matching. This was a learning project to understand regex engines and Ragel.

⚠️ Known Limitations

FastRegex does not fully implement PCRE2 semantics. Known issues:

• Nested quantifiers with captures: (a*)*, (\d+|\w+)*
• Deeply nested groups: ((a|b)*(c|d)+)+'
• Overlapping character classes in alternations: (\d\d\d)|(\w\w\w)
• Empty alternatives: (a|)

See LESSONS_LEARNED.md for details on what works and what doesn't.

Installation

Add to your shard.yml:

dependencies:
  fastregex:
    github: yourusername/fastregex

Usage

require "fastregex"

# Compile a regex pattern
matcher = FastRegex::Matcher.compile("a+b+")

# Match against input
result = matcher.match("aaabbb")

# Result format: [{match_start, match_length}, {capture1_start, capture1_length}, ...]
puts result  # => [{0, 6}]

CLI Tool

# Test patterns interactively
./bin/regex_tester 'pattern' 'input'

What Works

Most common regex patterns work correctly:

• Literals: abc
• Character classes: \d, \w, \s, .
• Quantifiers: *, +, ?, {n}, {n,m}
• Capturing groups: (abc), (a|b)
• Alternations: a|b|c
• Anchors: ^, $, \b, \B
• Escapes: \\, \t, \n, etc.

Development

# Run tests
make test

# Build binaries
make build

# Format code
make format

Background

This project was an experiment to see if Ragel's finite state machines could provide PCRE2-compatible regex matching with Crystal's performance. We achieved 97% compatibility, but the remaining edge cases revealed fundamental differences between FSM and backtracking approaches.

See LESSONS_LEARNED.md for the full story.

License

MIT License - see LICENSE file for details.