lib-ruby-parser
lib-ruby-parser
is a Ruby parser written in Rust.
Basic usage:
use ;
Features
TLDR; it's fast, it's precise, and it has a beautiful interface.
Comparison with Ripper
/RubyVM::AST
:
- It's based on MRI's
parse.y
, and so it returns exactly the same sequence of tokens. - It's been tested on top 300 gems (by total downlads, that's about 3M LOC),
rubyspec
andruby/ruby
repos and there's no difference withRipper.lex
. - It's ~3 times faster than
Ripper
(withjemalloc
), Ripper parses 3.9M LOC in ~16s,lib-ruby-parser
does it in ~6.5s. That's ~600K LOC/s. You can find some benchmarks in thebench/
directory, they don't include IO and GC. - It has a much, much better interface. AST is strongly typed and well documented.
- It doesn't throw away information about tokens. All nodes have information about their source locations.
Comparison with whitequark/parser:
- It's much faster (the same corpus of 3M LOC can be parsed in 180s on the same machine)
- It has a very similar interface (both in terms of AST structure and errors reporting)
- However, AST is strongly typed, and so if something is nullable it's explicitly defined and documented.
- What's important, it doesn't depend on Ruby
Grammar versioning
lib-ruby-parser
follows MRI/master. There are no plans to support multiple versions like it's done in whitequark/parser
.
Library versioning
Ruby version | lib-ruby-parser version |
---|---|
3.0.0 | 3.0.0+ |
Encodings
By default lib-ruby-parser
can only parse source files encoded in UTF-8
or ASCII-8BIT/BINARY
.
It's possible to pass a decoder
function in ParserOptions
that takes a recognized (by the library) encoding and a byte array. It must return a UTF-8 encoded byte array or an error:
use ;
use ;
let options = ParserOptions ;
let mut parser = new;
let ParserResult = parser.do_parse;
assert_eq!
Invalid string values
Ruby doesn't require string literals to be valid in their encodings. This is why the following code is valid:
# encoding: utf-8
Byte sequence 255
is invalid in UTF-8, but MRI ignores it.
But not all languages support it, and this is why string and symbol nodes encapsulate a custom StringValue
instead of a plain String
.
If your language supports invalid strings you can use raw .bytes
of this StringValue
. For example, a Ruby wrapper for this library could do that.
If your language doesn't support it, better call .to_string_lossy()
that replaces all unsupported chars with a special U+FFFD REPLACEMENT CHARACTER (�)
.
Regexes
Ruby constructs regexes from literals during parsing to:
- validate them
- declare local variables if regex is used for matching AND it contains named captures
To mirror this behavior lib-ruby-parser
uses Onigurama to compile, validate and parse regex literals.
This feature is disabled by default, but you can add it by enabling "onig"
feature.
Bison
The grammar of lib-ruby-parser
is built using a custom bison skeleton that was written for this project.
For development you need the latest version of Bison installed locally. Of course, it's not necessary for release builds from crates.io (because compiled parser.rs
is included into release build AND build.rs
that converts it is excluded).
If you use it from GitHub directly you also need Bison (because parser.rs
is under gitignore)
Bindings for other languages
Profiling
You can use parse
example:
Benchmarking
A codebase of 3.9M LOCs can be generated using a download.rb
script:
Then, run a script that compares Ripper
and lib-ruby-parser
(attached results are from Feb 2021):
)
)
)
)
)
)
)
)
)
)
)
Profile-guided optimization
# Build recording executable
RUSTFLAGS="-Cprofile-generate= /target/pgo/pgo.profraw"
# Record raw profiling data
# Merge profiled data
# Build optimized executable
RUSTFLAGS="-Cprofile-use= /target/pgo/pgo.profraw/merged.profdata"
PGO, No LTO:
No PGO, LTO=fat:
The diff seems to be too small to use this feature.
When both PGO and LTO are enabled building a parse
example gives a bunch of LLVM errors about wrong types of functions (like expected a Function or null
).
If you know how to fix them, please open an issue.
Fuzz testing
First, make sure to switch to nightly:
Then install cargo-fuzz
:
And run the fuzzer (change the number of --jobs
as you need or remove it to run only 1 parallel process):