prism 0.13.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 290f2191f3700e2584cc320e6dd99f78cfbd2cfd82006700f0bf977bfdc30424
+  data.tar.gz: 2886b0f5553307c1cd5d5e963ac03ea66330e2fa7d26cc4684d8f556e52520f5
+SHA512:
+  metadata.gz: 24dc8c15f9693b120e8dfcdf8edf2d3a396e6eb636589eded6dac5b651cc62beee1f9c6464d49b1c93b5666e963755bfc4eb041a020ca9585ab7a0bb10172787
+  data.tar.gz: 272d11c30527f924644c3c97ac2895167798774007919d429b03325926f1853422a56463e7272ae02d4855f54dd1f775ce546065d2d2c78b1187192cce722e48

data/CHANGELOG.md

@@ -0,0 +1,172 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.13.0] - 2023-09-29
+
+### Added
+
+- `BEGIN {}` blocks are only allowed at the top-level, and will now provide a syntax error if they are not.
+- Numbered parameters are not allowed in block parameters, and will now provide a syntax error if they are.
+- Many more Ruby modules and classes are now documented. Also, many have been moved into their own files and autoloaded so that initial boot time of the gem is much faster.
+- `PM_TOKEN_METHOD_NAME` is introduced, used to indicate an identifier that if definitely a method name because it has an `!` or `?` at the end.
+- In the C API, arrays, assocs, and hashes now can have the `PM_NODE_FLAG_STATIC_LITERAL` flag attached if they can be compiled statically. This is used in CRuby, for example, to determine if a `duphash`/`duparray` instruction can be used as opposed to a `newhash`/`newarray`.
+- `Node#type` is introduced, which returns a symbol representing the type of the node. This is useful for case comparisons when you have to compare against multiple types.
+
+### Changed
+
+- **BREAKING**: Everything has been renamed to `prism` instead of `yarp`. The `yp_`/`YP_` prefix in the C API has been changed to `pm_`/`PM_`. For the most part, everything should be find/replaceable.
+- **BREAKING**: `BlockArgumentNode` nodes now go into the `block` field on `CallNode` nodes, in addition to the `BlockNode` nodes that used to be there. Hopefully this makes it more consistent to compile/deal with in general, but it does mean it can be a surprising breaking change.
+- Escaped whitespace in `%w` lists is now properly unescaped.
+- `Node#pretty_print` now respects pretty print indentation.
+- `Dispatcher` was previously firing `_leave` events in the incorrect order. This has now been fixed.
+- **BREAKING**: `Visitor` has now been split into `Visitor` and `Compiler`. The visitor visits nodes but doesn't return anything from the visit methods. It is suitable for taking action based on the tree, but not manipulating the tree itself. The `Compiler` visits nodes and returns the computed value up the tree. It is suitable for compiling the tree into another format. As such, `MutationVisitor` has been renamed to `MutationCompiler`.
+
+## [0.12.0] - 2023-09-15
+
+### Added
+
+- `RegularExpressionNode#options` and `InterpolatedRegularExpressionNode#options` are now provided. These return integers that match up to the `Regexp#options` API.
+- Greatly improved `Node#inspect` and `Node#pretty_print` APIs.
+- `MatchLastLineNode` and `InterpolatedMatchLastLineNode` are introduced to represent using a regular expression as the predicate of an `if` or `unless` statement.
+- `IntegerNode` now has a base flag on it.
+- Heredocs that were previously `InterpolatedStringNode` and `InterpolatedXStringNode` nodes without any actual interpolation are now `StringNode` and `XStringNode`, respectively.
+- `StringNode` now has a `frozen?` flag on it, which respects the `frozen_string_literal` magic comment.
+- Numbered parameters are now supported, and are properly represented using `LocalVariableReadNode` nodes.
+- `ImplicitNode` is introduced, which wraps implicit calls, local variable reads, or constant reads in omitted hash values.
+- `YARP::Dispatcher` is introduced, which provides a way for multiple objects to listen for certain events on the AST while it is being walked. This is effectively a way to implement a more efficient visitor pattern when you have many different uses for the AST.
+
+### Changed
+
+- **BREAKING**: Flags fields are now marked as private, to ensure we can change their implementation under the hood. Actually querying should be through the accessor methods.
+- **BREAKING**: `AliasNode` is now split into `AliasMethodNode` and `AliasGlobalVariableNode`.
+- Method definitions on local variables is now correctly handled.
+- Unary minus precedence has been fixed.
+- Concatenating character literals with string literals is now fixed.
+- Many more invalid syntaxes are now properly rejected.
+- **BREAKING**: Comments now no longer include their trailing newline.
+
+## [0.11.0] - 2023-09-08
+
+### Added
+
+- `Node#inspect` is much improved.
+- `YARP::Pattern` is introduced, which can construct procs to match against nodes.
+- `BlockLocalVariableNode` is introduced to take the place of the locations array on `BlockParametersNode`.
+- `ParseResult#attach_comments!` is now provided to attach comments to locations in the tree.
+- `MultiTargetNode` is introduced as the target of multi writes and for loops.
+- `Node#comment_targets` is introduced to return the list of objects that can have attached comments.
+
+### Changed
+
+- **BREAKING**: `GlobalVariable*Node#name` now returns a symbol.
+- **BREAKING**: `Constant*Node#name` now returns a symbol.
+- **BREAKING**: `BlockParameterNode`, `KeywordParameterNode`, `KeywordRestParameterNode`, `RestParameterNode`, `DefNode` all have their `name` methods returning symbols now.
+- **BREAKING**: `ClassNode#name` and `ModuleNode#name` now return symbols.
+- **BREAKING**: `Location#end_column` is now exclusive instead of inclusive.
+- `Location#slice` now returns a properly encoded string.
+- `CallNode#operator_loc` is now `CallNode#call_operator_loc`.
+- `CallOperatorAndWriteNode` is renamed to `CallAndWriteNode` and its structure has changed.
+- `CallOperatorOrWriteNode` is renamed to `CallOrWriteNode` and its structure has changed.
+
+## [0.10.0] - 2023-09-01
+
+### Added
+
+- `InstanceVariable*Node` and `ClassVariable*Node` objects now have their `name` returning a Symbol. This is because they are now part of the constant pool.
+- `NumberedReferenceReadNode` now has a `number` field, which returns an Integer.
+
+### Changed
+
+- **BREAKING**: Various `operator_id` and `constant_id` fields have been renamed to `operator` and `name`, respectively. See [09d0a144](https://github.com/ruby/yarp/commit/09d0a144dfd519c5b5f96f0b6ee95d256e2cb1a6) for details.
+- `%w`, `%W`, `%i`, `%I`, `%q`, and `%Q` literals can now span around the contents of a heredoc.
+- **BREAKING**: All of the public C APIs that accept the source string now accept `const uint8_t *` as opposed to `const char *`.
+
+## [0.9.0] - 2023-08-25
+
+### Added
+
+- Regular expressions can now be bound by `\n`, `\r`, and a combination of `\r\n`.
+- Strings delimited by `%`, `%q`, and `%Q` can now be bound by `\n`, `\r`, and a combination of `\r\n`.
+- `IntegerNode#value` now returns the value of the integer as a Ruby `Integer`.
+- `FloatNode#value` now returns the value of the float as a Ruby `Float`.
+- `RationalNode#value` now returns the value of the rational as a Ruby `Rational`.
+- `ImaginaryNode#value` now returns the value of the imaginary as a Ruby `Complex`.
+- `ClassNode#name` is now a string that returns the name of just the class, without the namespace.
+- `ModuleNode#name` is now a string that returns the name of just the module, without the namespace.
+- Regular expressions and strings found after a heredoc declaration but before the heredoc body are now parsed correctly.
+- The serialization API now supports shared strings, which should help reduce the size of the serialized AST.
+- `*Node#copy` is introduced, which returns a copy of the node with the given overrides.
+- `Location#copy` is introduced, which returns a copy of the location with the given overrides.
+- `DesugarVisitor` is introduced, which provides a simpler AST for use in tools that want to process fewer node types.
+- `{ClassVariable,Constant,ConstantPath,GlobalVariable,InstanceVariable,LocalVariable}TargetNode` are introduced. These nodes represent the target of writes in locations where a value cannot be provided, like a multi write or a rescue reference.
+- `UntilNode#closing_loc` and `WhileNode#closing_loc` are now provided.
+- `Location#join` is now provided, which joins two locations together.
+- `YARP::parse_lex` and `YARP::parse_lex_file` are introduced to parse and lex in one result.
+
+### Changed
+
+- When there is a magic encoding comment, the encoding of the first token's source string is now properly reencoded.
+- Constants followed by unary `&` are now properly parsed as a call with a passed block argument.
+- Escaping multi-byte characters in a string literal will now properly escape the entire character.
+- `YARP.lex_compat` now has more accurate behavior when a byte-order mark is present in the file.
+- **BREAKING**: `AndWriteNode`, `OrWriteNode`, and `OperatorWriteNode` have been split back up into their `0.7.0` versions.
+- We now properly support spaces between the `encoding` and `=`/`:` in a magic encoding comment.
+- We now properly parse `-> foo: bar do end`.
+
+## [0.8.0] - 2023-08-18
+
+### Added
+
+- Some performance improvements when converting from the C AST to the Ruby AST.
+- Two rust crates have been added: `yarp-sys` and `yarp`. They are as yet unpublished.
+
+### Changed
+
+- Escaped newlines in strings and heredocs are now handled more correctly.
+- Dedenting heredocs that result in empty string nodes will now drop those string nodes from the list.
+- Beginless and endless ranges in conditional expressions now properly form a flip flop node.
+- `%` at the end of files no longer crashes.
+- Location information has been corrected for `if/elsif` chains that have no `else`.
+- `__END__` at the very end of the file was previously parsed as an identifier, but is now correct.
+- **BREAKING**: Nodes that reference `&&=`, `||=`, and other writing operators have been consolidated. Previously, they were separate individual nodes. Now they are a tree with the target being the left-hand side and the value being the right-hand side with a joining `AndWriteNode`, `OrWriteNode`, or `OperatorWriteNode` in the middle. This impacts all of the nodes that match this pattern: `{ClassVariable,Constant,ConstantPath,GlobalVariable,InstanceVariable,LocalVariable}Operator{And,Or,}WriteNode`.
+- **BREAKING**: `BlockParametersNode`, `ClassNode`, `DefNode`, `LambdaNode`, `ModuleNode`, `ParenthesesNode`, and `SingletonClassNode` have had their `statements` field renamed to `body` to give a hint that it might not be a `StatementsNode` (it could also be a `BeginNode`).
+
+## [0.7.0] - 2023-08-14
+
+### Added
+
+- We now have an explicit `FlipFlopNode`. It has the same flags as `RangeNode`.
+- We now have a syntax error when implicit and explicit blocks are passed to a method call.
+- `Node#slice` is now implemented, for retrieving the slice of the source code corresponding to a node.
+- We now support the `utf8-mac` encoding.
+- Predicate methods have been added for nodes that have flags. For example `CallNode#safe_navigation?` and `RangeNode#exclude_end?`.
+- The gem now functions on JRuby and TruffleRuby, thanks to a new FFI backend.
+- Comments are now part of the serialization API.
+
+### Changed
+
+- Autotools has been removed from the build system, so when the gem is installed it will no longer need to go through a configure step.
+- The AST for `foo = *bar` has changed to have an explicit array on the right hand side, rather than a splat node. This is more consistent with how other parsers handle this.
+- **BREAKING**: `RangeNodeFlags` has been renamed to `RangeFlags`.
+- Unary minus on number literals is now parsed as part of the literal, rather than a call to a unary operator. This is more consistent with how other parsers handle this.
+
+## [0.6.0] - 2023-08-09
+
+### Added
+
+- 🎉 Initial release! 🎉
+
+[unreleased]: https://github.com/ruby/prism/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/ruby/prism/compare/v0.12.0...v0.13.0
+[0.12.0]: https://github.com/ruby/prism/compare/v0.11.0...v0.12.0
+[0.11.0]: https://github.com/ruby/prism/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/ruby/prism/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/ruby/prism/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/ruby/prism/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/ruby/prism/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/ruby/prism/compare/d60531...v0.6.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,76 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at opensource@shopify.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

data/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing
+
+Thank you for your interest in contributing to prism! Below are a couple of ways that you can help out.
+
+## Discussions
+
+The discussions page on the GitHub repository are open. If you have a question or want to discuss the project, feel free to open a new discussion or comment on an existing one. This is the best place to ask questions about the project.
+
+## Code
+
+If you want to contribute code, please first open or contribute to a discussion. A lot of the project is in flux, and we want to make sure that you are contributing to the right place. Once you have a discussion going, you can open a pull request with your changes. We will review your code and get it merged in.
+
+### Ruby Features
+
+Pattern matching and endless method definitions should be avoided as long as the latest TruffleRuby release does not support it.
+
+## Tests
+
+We could always use more tests! One of the biggest challenges of this project is building up a big test suite. If you want to contribute tests, feel free to open a pull request. These will get merged in as soon as possible.
+
+The `test` Rake task will not compile libraries or the C extension, and this is intentional (to make testing against an installed version easier). If you want to test your changes, please make sure you're also running either the task:
+
+``` sh
+bundle exec rake
+```
+
+or explicitly running the `compile` task:
+
+``` sh
+bundle exec rake compile test
+# or to just compile the C extension ...
+bundle exec rake compile:prism test
+```
+
+To test the rust bindings (with caveats about setting up your Rust environment properly first):
+
+``` sh
+bundle exec rake compile test:rust
+```
+
+
+## Documentation
+
+We could always use more documentation! If you want to contribute documentation, feel free to open a pull request. These will get merged in as soon as possible. Documenting functions or methods is always useful, but we also need more guides and tutorials. If you have an idea for a guide or tutorial, feel free to open an issue and we can discuss it.
+
+## Developing
+
+To get `clangd` support in the editor for development, generate the compilation database. This command will
+create an ignored `compile_commands.json` file at the project root, which is used by clangd to provide functionality.
+
+You will need `bear` which can be installed on macOS with `brew install bear`.
+
+```sh
+bundle exec rake bear
+```
+
+## Debugging
+
+Some useful rake tasks:
+
+- `test:valgrind` runs the test suite under valgrind to look for illegal memory access or memory leaks
+- `test:gdb` and `test:lldb` run the test suite under those debuggers

data/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2022-present, Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Makefile

@@ -0,0 +1,84 @@
+
+# V=0 quiet, V=1 verbose.  other values don't work.
+V = 0
+V0 = $(V:0=)
+Q1 = $(V:1=)
+Q = $(Q1:0=@)
+ECHO1 = $(V:1=@ :)
+ECHO = $(ECHO1:0=@ echo)
+FUZZ_OUTPUT_DIR = $(shell pwd)/fuzz/output
+
+SOEXT := $(shell ruby -e 'puts RbConfig::CONFIG["SOEXT"]')
+
+CPPFLAGS := -Iinclude
+CFLAGS := -g -O2 -std=c99 -Wall -Werror -Wextra -Wpedantic -Wundef -Wconversion -fPIC -fvisibility=hidden
+CC := cc
+
+HEADERS := $(shell find include -name '*.h')
+SOURCES := $(shell find src -name '*.c')
+SHARED_OBJECTS := $(subst src/,build/shared/,$(SOURCES:.c=.o))
+STATIC_OBJECTS := $(subst src/,build/static/,$(SOURCES:.c=.o))
+
+all: shared static
+
+shared: build/librubyparser.$(SOEXT)
+static: build/librubyparser.a
+
+build/librubyparser.$(SOEXT): $(SHARED_OBJECTS)
+	$(ECHO) "linking $@"
+	$(Q) $(CC) $(DEBUG_FLAGS) $(CFLAGS) -shared -o $@ $(SHARED_OBJECTS)
+
+build/librubyparser.a: $(STATIC_OBJECTS)
+	$(ECHO) "building $@"
+	$(Q) $(AR) $(ARFLAGS) $@ $(STATIC_OBJECTS) $(Q1:0=>/dev/null)
+
+build/shared/%.o: src/%.c Makefile $(HEADERS)
+	$(ECHO) "compiling $@"
+	$(Q) mkdir -p $(@D)
+	$(Q) $(CC) $(DEBUG_FLAGS) -DPRISM_EXPORT_SYMBOLS $(CPPFLAGS) $(CFLAGS) -c -o $@ $<
+
+build/static/%.o: src/%.c Makefile $(HEADERS)
+	$(ECHO) "compiling $@"
+	$(Q) mkdir -p $(@D)
+	$(Q) $(CC) $(DEBUG_FLAGS) $(CPPFLAGS) $(CFLAGS) -c -o $@ $<
+
+build/fuzz.%: $(SOURCES) fuzz/%.c fuzz/fuzz.c
+	$(ECHO) "building $* fuzzer"
+	$(Q) mkdir -p $(@D)
+	$(ECHO) "building main fuzz binary"
+	$(Q) AFL_HARDEN=1 afl-clang-lto $(DEBUG_FLAGS) $(CPPFLAGS) $(CFLAGS) $(FUZZ_FLAGS) -O0 -fsanitize-ignorelist=fuzz/asan.ignore -fsanitize=fuzzer,address -ggdb3 -std=c99 -Iinclude -o $@ $^
+	$(ECHO) "building cmplog binary"
+	$(Q) AFL_HARDEN=1 AFL_LLVM_CMPLOG=1 afl-clang-lto $(DEBUG_FLAGS) $(CPPFLAGS) $(CFLAGS) $(FUZZ_FLAGS) -O0 -fsanitize-ignorelist=fuzz/asan.ignore -fsanitize=fuzzer,address -ggdb3 -std=c99 -Iinclude -o $@.cmplog $^
+
+build/fuzz.heisenbug.%: $(SOURCES) fuzz/%.c fuzz/heisenbug.c
+	$(Q) AFL_HARDEN=1 afl-clang-lto $(DEBUG_FLAGS) $(CPPFLAGS) $(CFLAGS) $(FUZZ_FLAGS) -O0 -fsanitize-ignorelist=fuzz/asan.ignore -fsanitize=fuzzer,address -ggdb3 -std=c99 -Iinclude -o $@ $^
+
+fuzz-debug:
+	$(ECHO) "entering debug shell"
+	$(Q) docker run -it --rm -e HISTFILE=/prism/fuzz/output/.bash_history -v $(shell pwd):/prism -v $(FUZZ_OUTPUT_DIR):/fuzz_output prism/fuzz
+
+fuzz-docker-build: fuzz/docker/Dockerfile
+	$(ECHO) "building docker image"
+	$(Q) docker build -t prism/fuzz fuzz/docker/
+
+fuzz-run-%: FORCE fuzz-docker-build
+	$(ECHO) "generating templates"
+	$(Q) bundle exec rake templates
+	$(ECHO) "running $* fuzzer"
+	$(Q) docker run --rm -v $(shell pwd):/prism prism/fuzz /bin/bash -c "FUZZ_FLAGS=\"$(FUZZ_FLAGS)\" make build/fuzz.$*"
+	$(ECHO) "starting AFL++ run"
+	$(Q) mkdir -p $(FUZZ_OUTPUT_DIR)/$*
+	$(Q) docker run -it --rm -v $(shell pwd):/prism -v $(FUZZ_OUTPUT_DIR):/fuzz_output prism/fuzz /bin/bash -c "./fuzz/$*.sh /fuzz_output/$*"
+FORCE:
+
+fuzz-clean:
+	$(Q) rm -f -r fuzz/output
+
+clean:
+	$(Q) rm -f -r build
+
+.PHONY: clean fuzz-clean
+
+all-no-debug: DEBUG_FLAGS := -DNDEBUG=1
+all-no-debug: OPTFLAGS := -O3
+all-no-debug: all

data/README.md

@@ -0,0 +1,89 @@
+# Prism Ruby parser
+
+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. It is currently being integrated into [CRuby](https://github.com/ruby/ruby), [JRuby](https://github.com/jruby/jruby), [TruffleRuby](https://github.com/oracle/truffleruby), [Sorbet](https://github.com/sorbet/sorbet), and [Syntax Tree](https://github.com/ruby-syntax-tree/syntax_tree).
+
+## Overview
+
+The repository contains the infrastructure for both a shared library (librubyparser) 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 parser on a file or string and prints the syntax tree
+├── config.yml            specification for tokens and nodes in the tree
+├── docs                  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 librubyparser
+├── fuzz                  files related to fuzz testing
+├── include
+│   ├── prism             header files for the shared library
+│   └── prism.h           main header file for the shared library
+├── java                  Java 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
+├── rust
+│   ├── prism             Rustified crate for the shared library
+│   └── prism-sys         FFI binding for Rust
+├── src
+│   ├── enc               various encoding files
+│   ├── 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:
+
+* A C99 compiler
+* autotools (autoconf, automake, libtool)
+* make
+* Ruby 3.3.0-preview1 or later
+
+Once you have these dependencies, run:
+
+```
+bundle install
+```
+
+to fetch the Ruby dependencies. Finally, run:
+
+```
+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.
+
+* [Building](docs/building.md)
+* [Configuration](docs/configuration.md)
+* [Design](docs/design.md)
+* [Encoding](docs/encoding.md)
+* [Fuzzing](docs/fuzzing.md)
+* [Heredocs](docs/heredocs.md)
+* [Mapping](docs/mapping.md)
+* [Ripper](docs/ripper.md)
+* [Ruby API](docs/ruby_api.md)
+* [Serialization](docs/serialization.md)
+* [Testing](docs/testing.md)