Prism Ruby parser

<h1 align="center">Prism Ruby parser</h1>
<div align="center">
  <img alt="Prism Ruby parser" height="256px" src="https://github.com/ruby/prism/blob/main/doc/images/prism.png?raw=true">
</div>

This is a parser for the Ruby programming language. It is designed to be portable, error tolerant, and maintainable. It is written in C99 and has no dependencies.

## Overview

The repository contains the infrastructure for both a shared library (libprism) and a native CRuby extension. The shared library has no bindings to CRuby itself, and so can be used by other projects. The native CRuby extension links against `ruby.h`, and so is suitable in the context of CRuby.

```
.
├── Makefile              configuration to compile the shared library and native tests
├── Rakefile              configuration to compile the native extension and run the Ruby tests
├── bin
│   ├── lex               runs the lexer on a file or string, prints the tokens, and compares to ripper
│   ├── parse             runs the parse on a file or string and prints the AST
│   └── prism             a CLI for development and debugging
├── config.yml            specification for tokens and nodes in the tree
├── doc                   documentation website
├── docs                  markdown documentation about the project
├── ext
│   └── prism
│       ├── extconf.rb    configuration to generate the Makefile for the native extension
│       └── extension.c   the native extension that interacts with libprism
├── fuzz                  files related to fuzz testing
├── gemfiles              gemfiles used by different Ruby versions in CI
├── include
│   ├── prism             header files for the shared library
│   └── prism.h           main header file for the shared library
├── java                  Java bindings for the shared library
├── java-wasm             Java WASM bindings for the shared library
├── javascript            JavaScript WASM bindings for the shared library
├── lib
│   ├── prism             Ruby library files
│   └── prism.rb          main entrypoint for the Ruby library
├── rakelib               various Rake tasks for the project
├── rbi                   RBI type signatures for the Ruby library
├── rust
│   ├── ruby-prism        Rustified crate for the shared library
│   └── ruby-prism-sys    FFI binding for Rust
├── sample
│   └── prism             Sample code that uses the Ruby API for documentation purposes
├── sig                   RBS type signatures for the Ruby library
├── src
│   ├── util              various utility files
│   └── prism.c           main entrypoint for the shared library
├── templates             contains ERB templates generated by templates/template.rb
│   └── template.rb       generates code from the nodes and tokens configured by config.yml
└── test
    └── prism
        ├── fixtures      Ruby code used for testing
        └── snapshots     snapshots of generated syntax trees corresponding to fixtures
```

## Getting started

To compile the shared library, you will need:

* C99 compiler
* GNU make
* Ruby 2.7.0 or later

Once you have these dependencies, run:

```
bundle install
```

to fetch the Ruby dependencies. Finally, run:

```
bundle exec rake compile
```

to compile the shared library. It will be built in the `build` directory. To test that everything is working, run:

```
bin/parse -e "1 + 2"
```

to see the syntax tree for the expression `1 + 2`.

## Contributing

See the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. We additionally have documentation about the overall design of the project as well as various subtopics.

* [Build system](docs/build_system.md)
* [Configuration](docs/configuration.md)
* [CRuby compilation](docs/cruby_compilation.md)
* [Design](docs/design.md)
* [Encoding](docs/encoding.md)
* [Fuzzing](docs/fuzzing.md)
* [Heredocs](docs/heredocs.md)
* [JavaScript](docs/javascript.md)
* [Local variable depth](docs/local_variable_depth.md)
* [Mapping](docs/mapping.md)
* [Parser translation](docs/parser_translation.md)
* [Parsing rules](docs/parsing_rules.md)
* [Releasing](docs/releasing.md)
* [Ripper translation](docs/ripper_translation.md)
* [Ruby API](docs/ruby_api.md)
* [RubyParser translation](docs/ruby_parser_translation.md)
* [Serialization](docs/serialization.md)
* [Testing](docs/testing.md)

## Examples

Prism has been integrated into the majority of Ruby runtimes, many libraries, and some applications. Below is a list of some of the projects that use Prism:

### Runtimes

* [CRuby](https://github.com/ruby/ruby/pull/7964) (via C)
* [Garnet](https://github.com/camertron/garnet-js) (via WASM)
* [JRuby](https://github.com/jruby/jruby/pull/8103) (via Java)
* [Natalie](https://github.com/natalie-lang/natalie/pull/1213) (via C++ and Ruby)
* [Opal](https://github.com/opal/opal/pull/2642) (via Ruby and WASM)
* [TruffleRuby](https://github.com/oracle/truffleruby/issues/3117) (via Java)

### Libraries

* [dispersion](https://github.com/joeldrapper/dispersion)
* [minifyrb](https://github.com/koic/minifyrb)
* [packwerk](https://github.com/Shopify/packwerk/pull/388) (via parser translator)
* [rbi](https://github.com/Shopify/rbi)
* [rails](https://github.com/rails/rails)
  * [parsing renders](https://github.com/rails/rails/pull/49438)
  * [parsing rdoc](https://github.com/rails/rails/pull/50870)
  * [parsing tests](https://github.com/rails/rails/pull/51006)
* [repl_type_completor](https://github.com/ruby/repl_type_completor)
* [rubocop](https://docs.rubocop.org/rubocop/configuration.html#setting-the-parser-engine) (via parser translator)
* [ruby-lsp](https://github.com/Shopify/ruby-lsp)
* [smart_todo](https://github.com/Shopify/smart_todo/pull/69)
* [sorbet-eraser](https://github.com/kddnewton/sorbet-eraser/pull/25)
* [synvert](https://github.com/xinminlabs/synvert-core-ruby)
* [typeprof](https://github.com/ruby/typeprof)

### Applications

* [gem.sh](https://github.com/marcoroth/gem.sh/pull/96)