Ibex

Gem CI Docs License

Ibex is a Pure Ruby LR parser generator. It reads racc-compatible grammar files, generates parsers with the familiar do_parse / yyparse API, and requires no native extension.

The shortest path is the Getting Started guide: install the gem, try the calculator grammar, and then choose the compatible or extended contract you need. You can also inspect a grammar in the browser without uploading its source.

Release status

Ibex is pre-1.0. The v1.0 publication decision is on hold pending an independent review of the published error-experience evidence; feature development continues. The default compatible mode and its current IR contracts are the conservative adoption baseline. See the release status and stability policy for the human-readable boundaries.

R001: HOLD — awaiting_independent_review.

The current whole-library steep stats result is 28,836 typed calls and 2,734 untyped calls out of 31,610 (91.2% typed). The generated signature tree contains 492 explicit untyped occurrences across 39 files.

Install

Add the generator to an application or tool project:

gem install ibex
# or, in a Gemfile:
bundle add ibex

Applications that only run generated parsers can depend on the smaller runtime:

bundle add ibex-runtime

First parser

Save this as calculator.y:

class Calculator
token NUM
preclow
  left '+'
  left '*'
prechigh
rule
  expr : expr '+' expr { result = val[0] + val[2] }
       | expr '*' expr { result = val[0] * val[2] }
       | NUM { result = val[0] }
end
---- inner
def parse_tokens(tokens)
  @tokens = tokens
  do_parse
end

def next_token
  @tokens.shift
end
---- footer
if $PROGRAM_NAME == __FILE__
  tokens = [[:NUM, 2], ['+', nil], [:NUM, 3], ['*', nil], [:NUM, 4]]
  puts Calculator.new.parse_tokens(tokens)
end

Generate and run it:

ibex -o calculator.rb calculator.y
ruby calculator.rb
# 14

The generated parser uses compact immutable tables and depends on ibex-runtime. Use -E when a single self-contained generated file is more convenient. Use --check in CI to detect stale generated output.

Choose a contract

Surface Use it for Maturity
Compatible mode Existing racc grammars and conservative migrations Stable baseline
Extended mode EBNF, imports, generated lexers, trees, types, and tooling Preview; explicit opt-in
Browser playground and incremental CST sessions Local analysis and evaluation Preview/Experimental; bounded

The default frontend remains unchanged unless a grammar opts into pragma extended or the command line uses --mode=extended. Read the grammar reference, racc migration guide, and maturity audit before adopting a Preview or Experimental surface.

IELR is also explicit: --algorithm=ielr uses the conservative partition strategy by default, while --ielr-strategy=direct enables the experimental LR(0)-based construction. Direct IELR is profiled and reviewable, but it is not the default release strategy; see the IELR guide.

Trust boundary

Static frontend, formatting, documentation, LSP, IR, verification, and browser analysis treat grammar actions and user sections as opaque source. Generated parsers and semantic parses execute application Ruby and are not sandboxes. The playground runs in a local Web Worker, does not upload grammar source, and never executes parser actions or user-code sections. Its limits and non-goals are documented in the playground guide.

Where to go next

Development

Clone the repository only when you need to contribute or run the complete quality suite:

git clone https://github.com/ydah/ibex.git
cd ibex
bundle install
bundle exec rake
npm ci
npm run test:site

The development guide lists the focused frontend, type, evidence, browser, and workflow checks.

Decisions and evidence

The public reference also indexes the direct IELR decision, direct multi-entry decision, verifier trust boundary, and the error-experience review status. These records scope claims to their evidence and revision; they do not change the compatible installation path above.

Ibex is available under the MIT License.