prism 0.15.1 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 967c414d9d2354dd828368920733b1c81240d1f0c267fdc422d075965f1cec94
-  data.tar.gz: a258399d77a8f4c6ca297fcea435c8b2c167bced045b32d2884f270a9483c33b
+  metadata.gz: 69cdca044f91ad2a198666562fdffd6035323906da465743ebff2cbd34ccac5d
+  data.tar.gz: 3da1460885f7cabda4b1ae6438274ab64a6e966536587d98eab2b3c764d0b6c0
 SHA512:
-  metadata.gz: 104746123657e06d12be6da5ebc6778afda2f94646d3544ff88acd42c5ef2d01f46855f96548360166ee0b4ce6d5164107f7a857c1b52984237421287da4e85c
-  data.tar.gz: d4237da63459ab266d5ee824d680eadef6ee893da5b7fd47960b55f4496630e18b0804b455e51576dd52ab4f085a3eb013d1e08fc7c4577c1ed07441abf6b53e
+  metadata.gz: c01d8b62728fe1cbce99394d683c28b943b7962e6a1fc82d435b3190286612fc4d7e4aaab93a6bef7a75f8acdfa3b5a597acac3295e489a7dd89aada94b29b23
+  data.tar.gz: ce88826e2a46cb18fe5e89b1a7c18c8fba2387b9c9e5625ec9aac5e5bd1449b21f23624bd0a6b526c4a9fa156c679186f8b89c09d0a003d386663f4a6a33269e

data/CHANGELOG.md

@@ -6,6 +6,38 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 ## [Unreleased]
 
+## [0.17.0] - 2023-11-03
+
+### Added
+
+- We now properly support forwarding arguments into arrays, like `def foo(*) = [*]`.
+- We now have much better documentation for the C and Ruby APIs.
+- We now properly provide an error message when attempting to assign to numbered parameters from within regular expression named capture groups, as in `/(?<_1>)/ =~ ""`.
+
+### Changed
+
+- **BREAKING**: `KeywordParameterNode` is split into `OptionalKeywordParameterNode` and `RequiredKeywordParameterNode`. `RequiredKeywordParameterNode` has no `value` field.
+- **BREAKING**: Most of the `Prism::` APIs now accept a bunch of keyword options. The options we now support are: `filepath`, `encoding`, `line`, `frozen_string_literal`, `verbose`, and `scopes`. See [the pull request](https://github.com/ruby/prism/pull/1763) for more details.
+- **BREAKING**: Comments are now split into three different classes instead of a single class, and the `type` field has been removed. They are: `InlineComment`, `EmbDocComment`, and `DATAComment`.
+
+## [0.16.0] - 2023-10-30
+
+### Added
+
+- `InterpolatedMatchLastLineNode#options` and `MatchLastLineNode#options` are added, which are the same methods as are exposed on `InterpolatedRegularExpressionNode` and `RegularExpressionNode`.
+- The project can now be compiled with `wasi-sdk` to expose a WebAssembly interface.
+- `ArgumentsNode#keyword_splat?` is added to indicate if the arguments node has a keyword splat.
+- The C API `pm_prettyprint` has a much improved output which lines up closely with `Node#inspect`.
+- Prism now ships with `RBS` and `RBI` type signatures (in the `/sig` and `/rbi` directories, respectively).
+- `Prism::parse_comments` and `Prism::parse_file_comments` APIs are added to extract only the comments from the source code.
+
+### Changed
+
+- **BREAKING**: `Multi{Target,Write}Node#targets` is split up now into `lefts`, `rest`, and `rights`. This is to avoid having to scan the list in the case that there are splat nodes.
+- Some bugs are fixed on `Multi{Target,Write}Node` accidentally creating additional nesting when not necessary.
+- **BREAKING**: `RequiredDestructuredParameterNode` has been removed in favor of using `MultiTargetNode` in those places.
+- **BREAKING**: `HashPatternNode#assocs` has been renamed to `HashPatternNode#elements`. `HashPatternNode#kwrest` has been renamed to `HashPatternNode#rest`.
+
 ## [0.15.1] - 2023-10-18
 
 ### Changed
@@ -201,7 +233,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 - 🎉 Initial release! 🎉
 
-[unreleased]: https://github.com/ruby/prism/compare/v0.15.1...HEAD
+[unreleased]: https://github.com/ruby/prism/compare/v0.17.0...HEAD
+[0.17.0]: https://github.com/ruby/prism/compare/v0.16.0...v0.17.0
+[0.16.0]: https://github.com/ruby/prism/compare/v0.15.1...v0.16.0
 [0.15.1]: https://github.com/ruby/prism/compare/v0.15.0...v0.15.1
 [0.15.0]: https://github.com/ruby/prism/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/ruby/prism/compare/v0.13.0...v0.14.0

data/Makefile

@@ -13,6 +13,7 @@ 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
+WASI_SDK_PATH := /opt/wasi-sdk
 
 HEADERS := $(shell find include -name '*.h')
 SOURCES := $(shell find src -name '*.c')
@@ -23,6 +24,7 @@ all: shared static
 
 shared: build/librubyparser.$(SOEXT)
 static: build/librubyparser.a
+wasm: javascript/src/prism.wasm
 
 build/librubyparser.$(SOEXT): $(SHARED_OBJECTS)
 	$(ECHO) "linking $@"
@@ -32,6 +34,10 @@ build/librubyparser.a: $(STATIC_OBJECTS)
 	$(ECHO) "building $@"
 	$(Q) $(AR) $(ARFLAGS) $@ $(STATIC_OBJECTS) $(Q1:0=>/dev/null)
 
+javascript/src/prism.wasm: Makefile $(SOURCES) $(HEADERS)
+	$(ECHO) "building $@"
+	$(Q) $(WASI_SDK_PATH)/bin/clang --sysroot=$(WASI_SDK_PATH)/share/wasi-sysroot/ $(DEBUG_FLAGS) -DPRISM_EXPORT_SYMBOLS -D_WASI_EMULATED_MMAN -lwasi-emulated-mman $(CPPFLAGS) $(CFLAGS) -Wl,--export-all -Wl,--no-entry -mexec-model=reactor -o $@ $(SOURCES)
+
 build/shared/%.o: src/%.c Makefile $(HEADERS)
 	$(ECHO) "compiling $@"
 	$(Q) mkdir -p $(@D)
@@ -82,3 +88,9 @@ clean:
 all-no-debug: DEBUG_FLAGS := -DNDEBUG=1
 all-no-debug: OPTFLAGS := -O3
 all-no-debug: all
+
+run: Makefile $(STATIC_OBJECTS) $(HEADERS) test.c
+	$(ECHO) "compiling test.c"
+	$(Q) $(CC) $(CPPFLAGS) $(CFLAGS) $(STATIC_OBJECTS) test.c
+	$(ECHO) "running test.c"
+	$(Q) ./a.out

data/README.md

@@ -1,6 +1,6 @@
 <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/docs/prism.png?raw=true">
+  <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. 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).
@@ -85,7 +85,9 @@ See the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information. We additio
 * [Encoding](docs/encoding.md)
 * [Fuzzing](docs/fuzzing.md)
 * [Heredocs](docs/heredocs.md)
+* [JavaScript](docs/javascript.md)
 * [Mapping](docs/mapping.md)
+* [Releasing](docs/releasing.md)
 * [Ripper](docs/ripper.md)
 * [Ruby API](docs/ruby_api.md)
 * [Serialization](docs/serialization.md)

data/config.yml

@@ -59,11 +59,11 @@ tokens:
   - name: CONSTANT
     comment: "a constant"
   - name: DOT
-    comment: "."
+    comment: "the . call operator"
   - name: DOT_DOT
-    comment: ".."
+    comment: "the .. range operator"
   - name: DOT_DOT_DOT
-    comment: "..."
+    comment: "the ... range operator or forwarding parameter"
   - name: EMBDOC_BEGIN
     comment: "=begin"
   - name: EMBDOC_END
@@ -311,9 +311,9 @@ tokens:
   - name: UCOLON_COLON
     comment: "unary ::"
   - name: UDOT_DOT
-    comment: "unary .."
+    comment: "unary .. operator"
   - name: UDOT_DOT_DOT
-    comment: "unary ..."
+    comment: "unary ... operator"
   - name: UMINUS
     comment: "-@"
   - name: UMINUS_NUM
@@ -329,12 +329,18 @@ tokens:
   - name: __END__
     comment: "marker for the point in the file at which the parser should stop"
 flags:
+  - name: ArgumentsNodeFlags
+    values:
+      - name: KEYWORD_SPLAT
+        comment: "if arguments contain keyword splat"
+    comment: Flags for arguments nodes.
   - name: CallNodeFlags
     values:
       - name: SAFE_NAVIGATION
         comment: "&. operator"
       - name: VARIABLE_CALL
         comment: "a call that could have been a local variable"
+    comment: Flags for call nodes.
   - name: IntegerBaseFlags
     values:
       - name: BINARY
@@ -345,14 +351,17 @@ flags:
         comment: "0d or no prefix"
       - name: HEXADECIMAL
         comment: "0x prefix"
+    comment: Flags for integer nodes that correspond to the base of the integer.
   - name: LoopFlags
     values:
       - name: BEGIN_MODIFIER
         comment: "a loop after a begin statement, so the body is executed first before the condition"
+    comment: Flags for while and until loop nodes.
   - name: RangeFlags
     values:
       - name: EXCLUDE_END
         comment: "... operator"
+    comment: Flags for range and flip-flop nodes.
   - name: RegularExpressionFlags
     values:
       - name: IGNORE_CASE
@@ -371,10 +380,12 @@ flags:
         comment: "s - forces the Windows-31J encoding"
       - name: UTF_8
         comment: "u - forces the UTF-8 encoding"
+    comment: Flags for regular expression and match last line nodes.
   - name: StringFlags
     values:
       - name: FROZEN
         comment: "frozen by virtue of a `frozen_string_literal` comment"
+    comment: Flags for string nodes.
 nodes:
   - name: AliasGlobalVariableNode
     fields:
@@ -432,6 +443,9 @@ nodes:
     fields:
       - name: arguments
         type: node[]
+      - name: flags
+        type: flags
+        kind: ArgumentsNodeFlags
     comment: |
       Represents a set of arguments to a method or a keyword.
 
@@ -770,10 +784,10 @@ nodes:
     comment: |
       Represents the use of a case statement.
 
-      case true
-      ^^^^^^^^^
-      when false
-      end
+          case true
+          when false
+          end
+          ^^^^^^^^^^
   - name: ClassNode
     fields:
       - name: locals
@@ -811,7 +825,7 @@ nodes:
       Represents the use of the `&&=` operator for assignment to a class variable.
 
           @@target &&= value
-          ^^^^^^^^^^^^^^^^
+          ^^^^^^^^^^^^^^^^^^
   - name: ClassVariableOperatorWriteNode
     fields:
       - name: name
@@ -1176,13 +1190,13 @@ nodes:
       Represents a find pattern in pattern matching.
 
           foo in *bar, baz, *qux
-          ^^^^^^^^^^^^^^^^^^^^^^
+                 ^^^^^^^^^^^^^^^
 
           foo in [*bar, baz, *qux]
-          ^^^^^^^^^^^^^^^^^^^^^^^^
+                 ^^^^^^^^^^^^^^^^^
 
           foo in Foo(*bar, baz, *qux)
-          ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                 ^^^^^^^^^^^^^^^^^^^^
   - name: FlipFlopNode
     fields:
       - name: left
@@ -1233,7 +1247,7 @@ nodes:
 
           def foo(...)
             bar(...)
-            ^^^^^^^^
+                ^^^
           end
   - name: ForwardingParameterNode
     comment: |
@@ -1349,9 +1363,9 @@ nodes:
     fields:
       - name: constant
         type: node?
-      - name: assocs
+      - name: elements
         type: node[]
-      - name: kwrest
+      - name: rest
         type: node?
       - name: opening_loc
         type: location?
@@ -1685,24 +1699,6 @@ nodes:
 
           foo(a: b)
               ^^^^
-  - name: KeywordParameterNode
-    fields:
-      - name: name
-        type: constant
-      - name: name_loc
-        type: location
-      - name: value
-        type: node?
-    comment: |
-      Represents a keyword parameter to a method, block, or lambda definition.
-
-          def a(b:)
-                ^^
-          end
-
-          def a(b: 1)
-                ^^^^
-          end
   - name: KeywordRestParameterNode
     fields:
       - name: name
@@ -1915,7 +1911,11 @@ nodes:
           ^^^^^^^^^^^^^^
   - name: MultiTargetNode
     fields:
-      - name: targets
+      - name: lefts
+        type: node[]
+      - name: rest
+        type: node?
+      - name: rights
         type: node[]
       - name: lparen_loc
         type: location?
@@ -1924,11 +1924,15 @@ nodes:
     comment: |
       Represents a multi-target expression.
 
-          a, b, c = 1, 2, 3
-          ^^^^^^^
+          a, (b, c) = 1, 2, 3
+             ^^^^^^
   - name: MultiWriteNode
     fields:
-      - name: targets
+      - name: lefts
+        type: node[]
+      - name: rest
+        type: node?
+      - name: rights
         type: node[]
       - name: lparen_loc
         type: location?
@@ -1982,6 +1986,20 @@ nodes:
 
           $1
           ^^
+  - name: OptionalKeywordParameterNode
+    fields:
+      - name: name
+        type: constant
+      - name: name_loc
+        type: location
+      - name: value
+        type: node
+    comment: |
+      Represents an optional keyword parameter to a method, block, or lambda definition.
+
+          def a(b: 1)
+                ^^^^
+          end
   - name: OptionalParameterNode
     fields:
       - name: name
@@ -2169,19 +2187,17 @@ nodes:
 
           /foo/i
           ^^^^^^
-  - name: RequiredDestructuredParameterNode
+  - name: RequiredKeywordParameterNode
     fields:
-      - name: parameters
-        type: node[]
-      - name: opening_loc
-        type: location
-      - name: closing_loc
+      - name: name
+        type: constant
+      - name: name_loc
         type: location
     comment: |
-      Represents a destructured required parameter node.
+      Represents a required keyword parameter to a method, block, or lambda definition.
 
-          def foo((bar, baz))
-                  ^^^^^^^^^^
+          def a(b: )
+                ^^
           end
   - name: RequiredParameterNode
     fields:
@@ -2205,8 +2221,8 @@ nodes:
     comment: |
       Represents an expression modified with a rescue.
 
-        foo rescue nil
-        ^^^^^^^^^^^^^^
+          foo rescue nil
+          ^^^^^^^^^^^^^^
   - name: RescueNode
     fields:
       - name: keyword_loc
@@ -2228,8 +2244,8 @@ nodes:
 
           begin
           rescue Foo, *splat, Bar => ex
-          ^^^^^^
             foo
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           end
 
       `Foo, *splat, Bar` are in the `exceptions` field.

data/docs/configuration.md

@@ -4,6 +4,8 @@ A lot of code in prism's repository is templated from a single configuration fil
 
 * `ext/prism/api_node.c` - for defining how to build Ruby objects for the nodes out of C structs
 * `include/prism/ast.h` - for defining the C structs that represent the nodes
+* `javascript/src/deserialize.js` - for defining how to deserialize the nodes in JavaScript
+* `javascript/src/nodes.js` - for defining the nodes in JavaScript
 * `java/org/prism/AbstractNodeVisitor.java` - for defining the visitor interface for the nodes in Java
 * `java/org/prism/Loader.java` - for defining how to deserialize the nodes in Java
 * `java/org/prism/Nodes.java` - for defining the nodes in Java

data/docs/fuzzing.md

@@ -25,7 +25,7 @@ fuzz
 
 There are currently three fuzzing targets
 
-- `pm_parse_serialize` (parse)
+- `pm_serialize_parse` (parse)
 - `pm_regexp_named_capture_group_names` (regexp)
 
 Respectively, fuzzing can be performed with

data/docs/javascript.md

@@ -0,0 +1,90 @@
+# JavaScript
+
+Prism provides bindings to JavaScript out of the box.
+
+## Node
+
+To use the package from node, install the `@ruby/prism` dependency:
+
+```sh
+npm install @ruby/prism
+```
+
+Then import the package:
+
+```js
+import { loadPrism } from "@ruby/prism";
+```
+
+Then call the load function to get a parse function:
+
+```js
+const parse = await loadPrism();
+```
+
+## Browser
+
+To use the package from the browser, you will need to do some additional work. The [javascript/example.html](javascript/example.html) file shows an example of running Prism in the browser. You will need to instantiate the WebAssembly module yourself and then pass it to the `parsePrism` function.
+
+First, get a shim for WASI since not all browsers support it yet.
+
+```js
+import { WASI } from "https://unpkg.com/@bjorn3/browser_wasi_shim@latest/dist/index.js";
+```
+
+Next, import the `parsePrism` function from `@ruby/prism`, either through a CDN or by bundling it with your application.
+
+```js
+import { parsePrism } from "https://unpkg.com/@ruby/prism@latest/src/parsePrism.js";
+```
+
+Next, fetch and instantiate the WebAssembly module. You can access it through a CDN or by bundling it with your application.
+
+```js
+const wasm = await WebAssembly.compileStreaming(fetch("https://unpkg.com/@ruby/prism@latest/src/prism.wasm"));
+```
+
+Next, instantiate the module and initialize WASI.
+
+```js
+const wasi = new WASI([], [], []);
+const instance = await WebAssembly.instantiate(wasm, { wasi_snapshot_preview1: wasi.wasiImport });
+wasi.initialize(instance);
+```
+
+Finally, you can create a function that will parse a string of Ruby code.
+
+```js
+function parse(source) {
+  return parsePrism(instance.exports, source);
+}
+```
+
+## API
+
+Now that we have access to a `parse` function, we can use it to parse Ruby code:
+
+```js
+const parseResult = parse("1 + 2");
+```
+
+A ParseResult object is very similar to the Prism::ParseResult object from Ruby. It has the same properties: `value`, `comments`, `magicComments`, `errors`, and `warnings`. Here we can serialize the AST to JSON.
+
+```js
+console.log(JSON.stringify(parseResult.value, null, 2));
+```
+
+## Building
+
+To build the WASM package yourself, first obtain a copy of `wasi-sdk`. You can retrieve this here: <https://github.com/WebAssembly/wasi-sdk>. Next, run:
+
+```sh
+make wasm WASI_SDK_PATH=path/to/wasi-sdk
+```
+
+This will generate `javascript/src/prism.wasm`. From there, you can run the tests to verify everything was generated correctly.
+
+```sh
+cd javascript
+node test
+```

data/docs/releasing.md

@@ -0,0 +1,27 @@
+# Releasing
+
+To release a new version of Prism, perform the following steps:
+
+## Preparation
+
+* Update the CHANGELOG.md file.
+  * Add a new section for the new version at the top of the file.
+  * Fill in the relevant changes — it may be easiest to click the link for the `Unreleased` heading to find the commits.
+  * Update the links at the bottom of the file.
+* Update the version in the following files:
+  * `prism.gemspec` in the `Gem::Specification#version=` method call
+  * `ext/prism/extension.h` in the `EXPECTED_PRISM_VERSION` macro
+  * `include/prism/version.h` in the version macros
+  * `javascript/package.json` in the `version` field
+  * `rust/prism-sys/tests/utils_tests.rs` in the `version_test` function
+  * `templates/java/org/prism/Loader.java.erb` in the `load` function
+  * `templates/javascript/src/deserialize.js.erb` in the version constants
+  * `templates/lib/prism/serialize.rb.erb` in the version constants
+* Run `bundle install` to update the `Gemfile.lock` file.
+* Update `rust/prism-sys/Cargo.toml` to match the new version and run `cargo build`
+* Update `rust/prism/Cargo.toml` to match the new version and run `cargo build`
+* Commit all of the updated files.
+
+## Publishing
+
+* Run `bundle exec rake release` to publish the gem to [rubygems.org](rubygems.org). Note that you must have access to the `prism` gem to do this.

data/docs/ruby_api.md

@@ -23,3 +23,5 @@ The full API is documented below.
 * `Prism.parse_lex(source)` - parse the syntax tree corresponding to the given source string and return it within a parse result, along with the tokens
 * `Prism.parse_lex_file(filepath)` - parse the syntax tree corresponding to the given source file and return it within a parse result, along with the tokens
 * `Prism.load(source, serialized)` - load the serialized syntax tree using the source as a reference into a syntax tree
+* `Prism.parse_comments(source)` - parse the comments corresponding to the given source string and return them
+* `Prism.parse_file_comments(source)` - parse the comments corresponding to the given source file and return them

data/docs/serialization.md

@@ -72,6 +72,7 @@ The header is structured like the following table:
 | `1` | patch version number |
 | `1` | 1 indicates only semantics fields were serialized, 0 indicates all fields were serialized (including location fields) |
 | string | the encoding name |
+| varint | the start line |
 | varint | number of comments |
 | comment* | comments |
 | varint | number of magic comments |
@@ -136,56 +137,54 @@ typedef struct {
   size_t capacity;
 } pm_buffer_t;
 
-// Initialize a pm_buffer_t with its default values.
-bool pm_buffer_init(pm_buffer_t *);
-
 // Free the memory associated with the buffer.
 void pm_buffer_free(pm_buffer_t *);
 
 // Parse and serialize the AST represented by the given source to the given
 // buffer.
-void pm_parse_serialize(const uint8_t *source, size_t length, pm_buffer_t *buffer, const char *metadata);
+void pm_serialize_parse(pm_buffer_t *buffer, const uint8_t *source, size_t length, const char *data);
 ```
 
-Typically you would use a stack-allocated `pm_buffer_t` and call `pm_parse_serialize`, as in:
+Typically you would use a stack-allocated `pm_buffer_t` and call `pm_serialize_parse`, as in:
 
 ```c
 void
 serialize(const uint8_t *source, size_t length) {
-  pm_buffer_t buffer;
-  if (!pm_buffer_init(&buffer)) return;
+  pm_buffer_t buffer = { 0 };
+  pm_serialize_parse(&buffer, source, length, NULL);
 
-  pm_parse_serialize(source, length, &buffer, NULL);
   // Do something with the serialized string.
 
   pm_buffer_free(&buffer);
 }
 ```
 
-The final argument to `pm_parse_serialize` controls the metadata of the source.
-This includes the filepath that the source is associated with, and any nested local variables scopes that are necessary to properly parse the file (in the case of parsing an `eval`).
-Note that no `varint` are used here to make it easier to produce the metadata for the caller, and also serialized size is less important here.
-The metadata is a serialized format itself, and is structured as follows:
+The final argument to `pm_serialize_parse` is an optional string that controls the options to the parse function. This includes all of the normal options that could be passed to `pm_parser_init` through a `pm_options_t` struct, but serialized as a string to make it easier for callers through FFI. Note that no `varint` are used here to make it easier to produce the data for the caller, and also serialized size is less important here. The format of the data is structured as follows:
 
-| # bytes | field |
-| --- | --- |
-| `4` | the size of the filepath string |
-| | the filepath string |
-| `4` | the number of local variable scopes |
+| # bytes | field                      |
+| ------- | -------------------------- |
+| `4`     | the length of the filepath |
+| ...     | the filepath bytes         |
+| `4`     | the line number            |
+| `4`     | the length the encoding    |
+| ...     | the encoding bytes         |
+| `1`     | frozen string literal      |
+| `1`     | suppress warnings          |
+| `4`     | the number of scopes       |
+| ...     | the scopes                 |
 
-Then, each local variable scope is encoded as:
+Each scope is layed out as follows:
 
-| # bytes | field |
-| --- | --- |
-| `4` | the number of local variables in the scope |
-| | the local variables |
+| # bytes | field                      |
+| ------- | -------------------------- |
+| `4`     | the number of locals       |
+| ...     | the locals                 |
 
-Each local variable within each scope is encoded as:
+Each local is layed out as follows:
 
-| # bytes | field |
-| --- | --- |
-| `4` | the size of the local variable name |
-| | the local variable name |
+| # bytes | field                      |
+| ------- | -------------------------- |
+| `4`     | the length of the local    |
+| ...     | the local bytes            |
 
-The metadata can be `NULL` (as seen in the example above).
-If it is not null, then a minimal metadata string would be `"\0\0\0\0\0\0\0\0"` which would use 4 bytes to indicate an empty filepath string and 4 bytes to indicate that there were no local variable scopes.
+The data can be `NULL` (as seen in the example above).