Parsanol

Installation

Add Parsanol to your Rust or Ruby project in minutes.

R

Rust

Add to Cargo.toml

Features

Feature Default Description
ruby No Ruby FFI bindings (magnus, rb-sys)
wasm No WebAssembly bindings (wasm-bindgen)
serde Yes Serialization support

Feature Flags

rb

Ruby

Add to Gemfile

Or Install Directly

Prebuilt Platform Gems

RubyGems resolves a prebuilt gem for your platform — no Rust toolchain needed. Each carries the Ruby extension and a pure-portable cdylib (lib/parsanol/native/) that backs the ffi tier (native parsing on TruffleRuby; a fallback for MRI).

  • x86_64-linux, x86_64-linux-musl, aarch64-linux, aarch64-linux-musl
  • arm-linux, arm-linux-musl (32-bit armv7)
  • arm64-darwin, x86_64-darwin (macOS 11+)
  • x64-mingw-ucrt, aarch64-mingw-ucrt (Windows)

Ruby 3.2–4.0 per gem. JRuby installs the binary-free source gem and runs the pure-Ruby engine.

Requirements

  • Ruby 3.2 or later
  • Prebuilt platform gem: nothing else — no Rust, no compilers
  • Source gem fallback: Rust toolchain to compile the extension (or let the ffi tier / pure-Ruby engine serve you)
W

WebAssembly

NPM Package

Usage in Browser

Verify Installation

Rust

Ruby

Choosing a Backend

Parsanol offers three parsing backends, each optimized for different use cases. Choose based on your grammar complexity and memory requirements.

P

Packrat

Default backend. Memoizes all parse results for O(n) time complexity.

✓ Full feature support
✓ Captures & dynamic atoms
✓ Complex grammars
~ Memory: O(n × rules)
Best for: Captures, dynamic atoms, complex grammars
VM

Bytecode VM

Stack-based virtual machine. Minimal memory, fast for simple patterns.

✓ 10-32x faster for expressions
✓ Memory: O(depth) only
✓ Simple patterns
~ Dynamic atoms use fallback
Best for: Simple patterns, memory-constrained, expressions
S

Streaming

Chunk-based parsing for large files. Bounded memory regardless of input size.

✓ Parse GB files in MB RAM
✓ Works with captures
✓ Bounded memory
~ ~5-10% overhead
Best for: Large files (logs, CSV, JSON streams)

Quick Decision Guide

  • • Using captures or dynamic atoms? → Use Packrat (default)
  • • Memory-constrained environment? → Use Bytecode VM
  • • Files larger than available RAM? → Use Streaming
  • • Simple patterns only? → Bytecode VM is fastest

Troubleshooting

"linker 'cc' not found"

Install a C compiler. On Ubuntu: sudo apt install build-essential. On macOS: xcode-select --install.

"cargo not found"

Install Rust: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Native extension fails to compile

Ensure you have the correct Rust target installed: rustup target add x86_64-unknown-linux-gnu

← Introduction Your First Parser →