soml-lang 0.0.1 → 0.0.2

data/readme.md

@@ -7,12 +7,12 @@
 
 ## Highlights
 
-- Strict: every rule in the specification is enforced, and every error says what is wrong and where, with the same message as the JavaScript reference implementation
+- Strict: enforces every rule in the specification, with the same error messages as the JavaScript reference implementation
 - Exact: an int is an `Integer`, a float is a `Float`, an instant is a `Time` exact to the nanosecond, and a duration is an exact count of nanoseconds
-- Canonical: `SOML.generate(value, canonical: true)` writes the one canonical form, so equal values give equal text, and without it the member order of a hash is kept
+- Canonical: `SOML.generate(value, canonical: true)` writes the one canonical form, so equal values give equal text
 - Familiar: the API of `json`, with `parse`, `load_file`, `generate`, `symbolize_names:`, and `freeze:`
-- Lossless: `SOML.format` normalizes the layout and `SOML.edit` changes one value, and both keep the comments, member order, and spelling of everything else
-- Safe: linear time and memory on every input shape, no stack overflow on deep input, and every error in a document is a `SOML::ParseError`
+- Lossless: `SOML.format` and `SOML.edit` keep comments, member order, and spelling
+- Safe: linear time and memory on every input, no stack overflow on deep input, and every document error is a `SOML::ParseError`
 - Ractor-safe, with no dependencies
 
 ## Install
@@ -27,7 +27,7 @@ Or in a `Gemfile`:
 gem 'soml-lang'
 ```
 
-Requires Ruby 4.0 or later.
+[On RubyGems](https://rubygems.org/gems/soml-lang). Requires Ruby 4.0 or later.
 
 ## Usage
 
@@ -71,7 +71,7 @@ config[:postgres][:host]
 #=> "db.internal"
 ```
 
-Write a file in binary mode, so that Windows does not turn each line feed into a CRLF, which SOML does not allow:
+Write a file in binary mode, so that Windows does not write CRLF, which SOML does not allow:
 
 ```ruby
 File.binwrite('config.soml', SOML.generate(config))
@@ -91,7 +91,7 @@ File.binwrite('config.soml', SOML.generate(config))
 | array | `Array` | |
 | object | `Hash` with `String` keys, in document order, or `Symbol` keys with `symbolize_names: true` | `Symbol` keys |
 
-An int is an `Integer` and a float is a `Float` in both directions, so `3` and `3.0` keep their types:
+`3` and `3.0` keep their types in both directions:
 
 ```ruby
 SOML.parse("a: 3\nb: 3.0")
@@ -102,14 +102,14 @@ SOML.generate({a: 3, b: 3.0})
 ```
 
 > [!IMPORTANT]
-> Ruby compares `3 == 3.0` as true, so `SOML.parse('a: 3') == SOML.parse('a: 3.0')` is true even though the types differ. `eql?` compares the types too, so `SOML.parse('a: 3').eql?(SOML.parse('a: 3.0'))` is false.
+> In Ruby, `3 == 3.0`, so `SOML.parse('a: 3') == SOML.parse('a: 3.0')` is true. Use `eql?` to also compare the types.
 
-With this mapping, two things always hold:
+Two things always hold:
 
 - `SOML.parse(SOML.generate(value))` equals `value`, for a value made of the types `parse` returns. (A `Time` comes back in UTC, a `Symbol` as a `String`, and `-0.0` as `0.0`.)
-- `SOML.generate(SOML.parse(text), canonical: true)` is the canonical form of `text`, and `SOML.generate(SOML.parse(canonical), canonical: true) == canonical`.
+- `SOML.generate(SOML.parse(text), canonical: true)` is the canonical form of `text`.
 
-An instant is a `Time` in UTC, because the offset is how the instant was written, not part of its value:
+An instant is a `Time` in UTC, because the offset is not part of its value:
 
 ```ruby
 SOML.parse('a: 2026-09-19T14:00:00.123456789+02:00')['a']
@@ -120,11 +120,11 @@ SOML.parse('a: 2026-09-19T14:00:00.123456789+02:00')['a']
 
 ### SOML.parse(source, symbolize_names: false, freeze: false)
 
-Parse a document. Returns a `Hash` or an `Array`, because a document is always a collection.
+Parse a document. Returns a `Hash` or an `Array`.
 
-`source` is a `String`, or an object with `to_str`. A UTF-8, binary, or US-ASCII string is read as UTF-8, and invalid UTF-8 is a `SOML::ParseError` with its position. A string in another encoding, such as UTF-16, is converted to UTF-8 first, as `JSON.parse` does, and an `EncodingError` is raised when it does not convert.
+`source` is a `String`, or an object with `to_str`. A UTF-8, binary, or US-ASCII string is read as UTF-8. A string in another encoding, such as UTF-16, is converted to UTF-8 first, as `JSON.parse` does.
 
-Raises `SOML::ParseError` when the document is not valid, and `TypeError` when `source` is not a string.
+Raises `SOML::ParseError` when the document is not valid (including invalid UTF-8), `TypeError` when `source` is not a string, and `EncodingError` when it does not convert to UTF-8.
 
 #### symbolize_names
 
@@ -157,9 +157,9 @@ Ractor.shareable?(config)
 
 Read and parse a file. `path` is a `String`, or an object with `to_path`, such as a `Pathname`. The options are those of `SOML.parse`.
 
-The file is read in binary mode, so that a text-mode conversion cannot hide a carriage return, which a document may not contain.
+The file is read in binary mode, so that a text-mode conversion cannot hide a carriage return.
 
-Raises `SOML::ParseError` when the document is not valid, and a `SystemCallError`, such as `Errno::ENOENT`, when the file cannot be read. The error names the file, so that an editor or a terminal can open it at the position:
+Raises `SOML::ParseError` when the document is not valid, and a `SystemCallError`, such as `Errno::ENOENT`, when the file cannot be read. The error names the file, so that an editor or a terminal can open it:
 
 ```ruby
 SOML.load_file('config.soml')
@@ -168,9 +168,7 @@ SOML.load_file('config.soml')
 
 ### SOML.generate(value, canonical: false)
 
-Write a `Hash` or an `Array` as SOML. Members keep the order of their hash, nesting is written with braces and tabs, and the text ends with one line feed. Comments and block strings are never written.
-
-Everything but the order of members follows canonical form, so the text is canonical form when the keys are already sorted. Use `canonical: true` when the text is hashed, signed, or compared.
+Write a `Hash` or an `Array` as SOML. Members keep the order of their hash, nesting uses braces and tabs, and the text ends with one line feed. Everything but the member order follows canonical form. Use `canonical: true` when the text is hashed, signed, or compared.
 
 ```ruby
 SOML.generate({name: 'api', ports: [80, 443], description: 'The edge service'})
@@ -179,14 +177,14 @@ SOML.generate({name: 'api', ports: [80, 443], description: 'The edge service'})
 
 Raises `SOML::GenerateError` for a value that cannot be written:
 
-- a top-level value that is not a `Hash` or an `Array`, because a document is a collection
-- `Float::NAN`, which SOML does not have (use `nil` for a missing value)
+- a top-level value that is not a `Hash` or an `Array`
+- `Float::NAN` (use `nil` for a missing value)
 - an `Integer` outside the 64-bit range
-- a `Time` outside the years 0001 to 9999 in UTC, or with a fraction of a second finer than a nanosecond
-- a string or key with a carriage return, or one that is not valid UTF-8 or does not convert to UTF-8 (a binary or US-ASCII string is read as UTF-8, as `SOML.parse` reads one)
-- a key that is not a `String` or a `Symbol`, because a key is never converted, and two keys that are the same string, such as `:a` and `'a'`
+- a `Time` outside the years 0001 to 9999 in UTC, or finer than a nanosecond
+- a string or key with a carriage return, or that is not valid UTF-8 and does not convert to it
+- a key that is not a `String` or a `Symbol`, and two keys that are the same string, such as `:a` and `'a'`
 - a circular reference, and nesting deeper than 100 levels
-- an object of any other class, such as a `Date` (write it as a string), a `Rational`, or an `ActiveSupport::Duration` (use a `SOML::Duration`). A `Struct`, `Data`, `Set`, or `Pathname` is not converted, because it would read back as another class, and the message names the conversion to use, such as `to_h`
+- an object of any other class, such as a `Date` (write it as a string), a `Rational`, or an `ActiveSupport::Duration` (use a `SOML::Duration`). A `Struct`, `Data`, `Set`, or `Pathname` is not converted, because it would read back as another class. The message names the conversion to use, such as `to_h`.
 
 The message says where the value is:
 
@@ -200,7 +198,7 @@ SOML.generate({servers: [{ratio: Float::NAN}]})
 Type: `Boolean`\
 Default: `false`
 
-Whether to write canonical form, with the members of each object sorted by key. Canonical form is unique for a value: two equal values give the same text, so it can be hashed, signed, or compared.
+Whether to write canonical form, with the members of each object sorted by key. Two equal values give the same canonical text.
 
 ```ruby
 SOML.generate({name: 'api', ports: [80, 443], description: 'The edge service'}, canonical: true)
@@ -211,7 +209,7 @@ SOML.generate({name: 'api', ports: [80, 443], description: 'The edge service'},
 
 Format a document. Returns the document with its layout normalized, ending with one line feed.
 
-The layout follows the [formatter](https://github.com/soml-lang/soml/blob/main/spec.md#formatting) in the specification: one tab per level, every member and item on its own line with no commas, and no trailing whitespace or runs of blank lines. A container whose brackets are on one line stays on one line, as in `ports: [80, 443]`. Put a line break anywhere inside it to give it one member or item per line. Comments, member order, block strings, and the spelling of every value stay as they are, so the value never changes. Inside a block comment, only trailing whitespace and runs of blank lines change.
+The layout follows the [formatter](https://github.com/soml-lang/soml/blob/main/spec.md#formatting) in the specification: one tab per level, every member and item on its own line with no commas, and no trailing whitespace or runs of blank lines. A container on one line stays on one line, as in `ports: [80, 443]`. Put a line break anywhere inside it to split it. Comments, member order, block strings, and the spelling of every value stay as they are.
 
 `source` is read as `SOML.parse` reads it, with the same errors.
 
@@ -223,19 +221,19 @@ SOML.format("pool: {\nmin: 2, max: 16}")
 #=> "pool: {\n\tmin: 2\n\tmax: 16\n}\n"
 ```
 
-In detail, as the specification states:
+In detail:
 
-- A block comment that a value follows on the same line, as in `1, /* note */ 2`, stays in front of that value when each item goes on its own line.
-- One space follows each `:`, as in canonical form.
-- A value on the line after its `key:` moves up to that line, unless a comment comes between them. Then it stays on its own line, one level deeper than the key, and the blank lines between them are removed.
-- A block string begins on the line after its key, and its delimiters and content have the indentation of that line. Its lines are not otherwise changed.
+- A block comment before a value on the same line, as in `1, /* note */ 2`, stays in front of that value.
+- One space follows each `:`.
+- A value on the line after its `key:` moves up to that line, unless a comment comes between them. Then it stays on its own line, one level deeper than the key.
+- A block string begins on the line after its key, indented to that line. Its lines are not otherwise changed.
 - There are no blank lines at the start of the file or directly inside brackets.
 
-### SOML.edit(source, path, value)
+### SOML.edit(source, path, value) and SOML.edit(source, path, delete: true)
 
-Change one value in a document, and keep everything else as it is written: comments, member order, layout, and the spelling of every other value. For tools that update a config file, such as a dependency bumper or a `set` command.
+Change one value in a document, and keep everything else as it is written: comments, member order, layout, and spelling. For tools that update a config file, such as a dependency bumper or a `set` command.
 
-The value at `path` is replaced, or added when it does not exist yet. `SOML.edit(source, path, delete: true)` removes it instead. Only the changed part of the text is rewritten, and an edit to a formatted document leaves it formatted.
+The value at `path` is replaced, or added when it does not exist. `delete: true` removes it instead. Only the changed part of the text is rewritten, so a formatted document stays formatted.
 
 ```ruby
 SOML.edit("name: 'api' # The service\nport: 8080\n", ['port'], 9090)
@@ -254,28 +252,28 @@ Read and write the file in binary mode, as for `SOML.generate`:
 File.binwrite('config.soml', SOML.edit(File.binread('config.soml'), ['postgres', 'port'], 5433))
 ```
 
-- A new value is written as `SOML.generate` writes it, in canonical form except that its members keep their order, at the indentation of its line. So `0xFF` that is replaced by `255` is written `255`. In a container that is on one line, it is written on one line too, so `[1, 2]` with a new item `{a: 3}` becomes `[1, 2, {a: 3}]`.
+- A new value is written as `SOML.generate` writes it (keeping member order), at the indentation of its line. So `0xFF` replaced by `255` is written `255`. In a one-line container, it is written on one line too, so `[1, 2]` with a new item `{a: 3}` becomes `[1, 2, {a: 3}]`.
 - A new member goes after the last member of its object. Missing objects on the way are created.
-- A new item can be added at the end of an array, with the index that is its length.
-- A new member or item goes on its own line without a comma, after the comments that the one before it owns (see below), and the commas of the other members and items stay as they are. When something follows the member or item before it on the same line, such as the closing bracket of the one-line container `{a: 1}`, it goes on that line after a comma, as in `{a: 1, b: 2}`. In an empty `[]` or `{}`, it goes on a line of its own, unless that container is inside a container on one line, so `a: [1, []]` becomes `a: [1, [2]]`.
-- A removed member or item takes the comments it owns, which in a formatted document are the ones that `SOML.format` keeps with it: the comments after it on its line, also after its comma when nothing else follows there, and the block comments before it on its line, after the comma or bracket before it. So removing `2` from `[1, /* note */ 2]` gives `[1]`. A comment on a line of its own belongs to no member or item, so it stays. A removed member or item also removes its lines when nothing else is on them. A line that a block comment after it continues onto counts as one of its lines. Removing every item of a container closes it up to `[]` or `{}`, unless a comment is left inside.
-- A removed member or item takes its comma with it. When the removed items are the last ones and have no comma after them, they take the comma directly before them instead, when only spaces, tabs, and the comments they own are between, so `[1, 2]` becomes `[1]`.
+- A new item can be added at the end of an array, at the index that is its length.
+- A new member or item goes on its own line without a comma, after the comments that the one before it owns (see below). The commas of the others stay as they are. When something follows the one before it on the same line, such as the `}` of `{a: 1}`, it goes on that line after a comma, as in `{a: 1, b: 2}`. In an empty `[]` or `{}`, it goes on its own line, unless that container is inside a one-line container, so `a: [1, []]` becomes `a: [1, [2]]`.
+- A removed member or item takes the comments it owns, which are the ones `SOML.format` keeps with it: the comments after it on its line (also after its comma), and the block comments before it on its line. So removing `2` from `[1, /* note */ 2]` gives `[1]`. A comment on a line of its own stays. Its lines are removed when nothing else is on them, including a line that a block comment after it continues onto. Removing every item of a container closes it up to `[]` or `{}`, unless a comment is left inside.
+- A removed member or item takes its comma with it. When it is the last one without a comma after it, it takes the comma directly before it instead, so `[1, 2]` becomes `[1]`.
 - Removing the only member of a document without braces leaves `{}`.
 
-Comments inside a value that is replaced or removed are removed with it. In a layout that `SOML.format` never writes, such as an item after a closing block string delimiter on its line, a new item can be indented differently from its neighbors, but the document is always valid and has the right value.
+Comments inside a replaced or removed value are removed with it. In a layout that `SOML.format` never writes, such as an item after a closing block string delimiter on its line, a new item can be indented differently from its neighbors, but the document is always valid.
 
-Removing a value that does not exist (a missing member, a missing object or array on the way, or an index at or past the end of its array) changes nothing, so removing the same path twice is safe. The result has the same bytes as `source` exactly when nothing was removed, so `SOML.edit(source, path, delete: true).b == source.b` tells whether something was. The `.b` is needed because a source read in binary mode is not `==` to the UTF-8 result when it has a character that is not ASCII.
+Removing a value that does not exist (a missing member, a missing object or array on the way, or an index at or past the end of its array) changes nothing, so it is safe to remove the same path twice. Use `SOML.edit(source, path, delete: true).b == source.b` to tell whether something was removed. The `.b` is needed because a source read in binary mode is not `==` to the UTF-8 result when it has non-ASCII characters.
 
 The result is parsed before it is returned, so a bug in `SOML.edit` raises a `RuntimeError` rather than returning a broken document.
 
 Raises:
 
 - `SOML::ParseError` when `source` is not a valid document, the same as `SOML.parse`
-- `TypeError` when `source` is not a string, when `path` is not a non-empty array of keys and array indexes, when it leads through a value that is not an object or an array, or when it has a key where an array is or an index where an object is
-- `IndexError` when a value is set at an index past the end of its array, or at an index under a value that does not exist
-- `SOML::GenerateError` for a value or a key that `SOML.generate` cannot write, and when the change would nest the document more than 100 levels deep. Its path is the place in the document.
-- `ArgumentError` when both a value and `delete: true` are given, or neither
-- `EncodingError` when `source` is in an encoding other than UTF-8, binary, or US-ASCII, and does not convert to UTF-8, as for `SOML.parse`
+- `TypeError` when `source` is not a string, when `path` is not a member node, a value node, or a non-empty array of keys and indexes, when it leads through a scalar, or when it has a key where an array is or an index where an object is
+- `IndexError` when a value is set at an index past the end of its array, or at an index under a missing value
+- `SOML::GenerateError` for a value or a key that `SOML.generate` cannot write, and when the change would nest more than 100 levels deep. Its path is the place in the document.
+- `ArgumentError` when both a value and `delete: true` are given, or neither, or when `path` is the root node or a node that is not in `source`
+- `EncodingError` as for `SOML.parse`
 
 ```ruby
 SOML.edit('ports: [80]', ['ports', 5], 443)
@@ -284,9 +282,9 @@ SOML.edit('ports: [80]', ['ports', 5], 443)
 
 #### path
 
-Type: `Array<String | Symbol | Integer>`
+Type: `Array<String | Symbol | Integer>`, or a node from `SOML.parse_tree`
 
-The keys and array indexes that lead to the value, such as `['servers', 0, 'port']`.
+The keys and array indexes that lead to the value, such as `['servers', 0, 'port']`, or a member or value node from `SOML.parse_tree(source)` (see [Autofixes](#autofixes)).
 
 #### value
 
@@ -513,18 +511,18 @@ SOML.generate({timeout: SOML::Duration.from_seconds(5.minutes.to_r)})
 
 ## Benchmark
 
-The time to read and write each of the shared [benchmark fixtures](https://github.com/soml-lang/soml/blob/main/benchmark/readme.md), which hold the same data in SOML, JSON, and TOML, in CPU time on an Apple M-series machine with Ruby 4.0 and YJIT, which this gem is written for. The machine was busy, so the numbers are rough. Lower is better.
+CPU time to read and write the shared [benchmark fixtures](https://github.com/soml-lang/soml/blob/main/benchmark/readme.md), which hold the same data in SOML, JSON, and TOML, on an Apple M-series machine with Ruby 4.0 and YJIT. The numbers are rough. Lower is better.
 
-| | this gem | `json` | `oj` | `toml-rb` |
+| | this gem | `toml-rb` | `json` | `oj` |
 |---|---|---|---|---|
-| Read `service` (3 KB) | 78 µs | 10 µs | 11 µs | 174 µs |
-| Read `platform` (35 KB) | 0.61 ms | 0.10 ms | 0.07 ms | 1.2 ms |
-| Read `earthquakes` (733 KB) | 14 ms | 2.2 ms | 2.8 ms | 51 ms |
-| Write `service` | 51 µs | 8 µs | 8 µs | 105 µs |
-| Write `platform` | 0.34 ms | 0.06 ms | 0.03 ms | 0.65 ms |
-| Write `earthquakes` | 15 ms | 2.1 ms | 3.2 ms | 26 ms |
+| Read `service` (3 KB) | 78 µs | 174 µs | 10 µs | 11 µs |
+| Read `platform` (35 KB) | 0.61 ms | 1.2 ms | 0.10 ms | 0.07 ms |
+| Read `earthquakes` (733 KB) | 14 ms | 51 ms | 2.2 ms | 2.8 ms |
+| Write `service` | 51 µs | 105 µs | 8 µs | 8 µs |
+| Write `platform` | 0.34 ms | 0.65 ms | 0.06 ms | 0.03 ms |
+| Write `earthquakes` | 15 ms | 26 ms | 2.1 ms | 3.2 ms |
 
-`json` and `oj` are C extensions, and `toml-rb` is pure Ruby, like this gem. The script also compares `tomlib`, `perfect_toml`, and `tomlrb`, and times `SOML.format` and `SOML.edit` on each fixture:
+`toml-rb` is pure Ruby, like this gem, and `json` and `oj` are C extensions. The script also compares `tomlib`, `perfect_toml`, and `tomlrb`, and times `SOML.format`, `SOML.edit`, and `SOML.parse_tree` on each fixture:
 
 ```sh
 bundle config set --local with benchmark
@@ -532,11 +530,67 @@ bundle install
 bundle exec ruby --yjit bench/benchmark.rb
 ```
 
+## Syntax tree
+
+`SOML.parse_tree(source)` returns a deeply frozen `SOML::Tree` with `source` (a UTF-8 copy), `body` (an object or array), `tokens`, and `comments`. It accepts the same inputs and raises the same errors as `SOML.parse`, without freezing the caller's string. Only valid documents are supported; there is no recovery from incomplete editor input.
+
+```ruby
+tree = SOML.parse_tree('port: 0x1F90 # Default')
+node = tree.body.members.first.value
+
+node.kind #=> :integer
+node.value #=> 8080
+node.radix #=> 16
+tree.source.byteslice(node.start...node.finish) #=> "0x1F90"
+tree.position(node.start) #=> [1, 7]
+```
+
+Every node, token, and comment has `start` and exclusive `finish` UTF-8 byte offsets into `tree.source`. Use `byteslice` to read spans. Collections include their brackets; a bare root object spans its first key through its last value. `position(byte_offset)` returns one-based `[line, column]`, counting Unicode characters, including tabs as one character. It accepts character boundaries through EOF, raising `TypeError` for non-integers and `ArgumentError` for invalid offsets. Unlike tree spans, `ParseError#offset` counts characters.
+
+`each_node` yields the body and its descendants in source order, parents before children and member keys before values; without a block it returns an Enumerator. Tokens and comments are separate, each in source order. Node constructors are internal.
+
+| Class under `SOML::Tree` | `type` | Fields besides `start` and `finish` |
+|---|---|---|
+| `ObjectNode` | `:object` | `members`, `braced` |
+| `ArrayNode` | `:array` | `elements` |
+| `MemberNode` | `:member` | `key`, `value` (a node) |
+| `KeyNode` | `:key` | `value` (decoded string), `style` (`:bare`, `:literal`, or `:escaped`) |
+| `ScalarNode` | `:scalar` | `kind`, `value` (decoded), `block`, `style`, `radix` |
+| `Comment` | `:line` or `:block` | `value` (text without delimiters) |
+| `Token` | See below | `value` (original source text) |
+
+Scalar kinds are `:string`, `:integer`, `:float`, `:boolean`, `:null`, `:instant`, and `:duration`, with the same Ruby values as `SOML.parse`. Strings have `style: :literal` or `:escaped` and a `block` boolean; integers have `radix: 2`, `8`, `10`, or `16`. Otherwise, `style` and `radix` are `nil`, and `block` is `false`.
+
+### Syntax highlighting
+
+Token types are `:punctuator` (`{}[]:,`), `:bare_key`, `:string`, `:integer`, `:float`, `:keyword` (`true`, `false`, `null`), `:instant`, and `:duration`. Quoted keys and whole block strings are string tokens; escapes stay within strings. Infinities are floats. Use key nodes to distinguish quoted keys from string values.
+
+```ruby
+(tree.tokens + tree.comments).sort_by(&:start).each do |token|
+	text = tree.source.byteslice(token.start...token.finish)
+	# Highlight text using token.type, preserving whitespace between spans.
+end
+```
+
+Tokens never overlap and exclude whitespace and comments. When rendering HTML, escape all source text, including comments and gaps.
+
+### Autofixes
+
+`SOML.edit` accepts a member or non-root value node in place of a path, using its existing comment and layout rules. Members select their value for replacement and the whole member for deletion. Keys, tokens, comments, and the root collection are not accepted.
+
+```ruby
+source = "port: 0x1F90 # Default\n"
+node = SOML.parse_tree(source).body.members.first.value
+SOML.edit(source, node, 9090)
+#=> "port: 9090 # Default\n"
+```
+
+Nodes must come from the same source text. Reparse after editing before selecting another node. For spelling fixes, apply non-overlapping span replacements from the end backwards to `tree.source.b`, restore UTF-8 with `force_encoding(Encoding::UTF_8)`, then validate with `SOML.parse`.
+
 ## Limits
 
 - **Nesting is limited to 100 levels**, as the specification requires, in reading and in writing. Every array and object is one level, including the document's own collection.
-- **The gem name.** The name `soml` on RubyGems belongs to an unrelated format, which also defines `module SOML`, so the two gems cannot be loaded in one process.
-- **The syntax tree is not public yet.** `SOML.format` and `SOML.edit` use one, and the [JavaScript](https://github.com/soml-lang/soml-javascript), [Python](https://github.com/soml-lang/soml-python), and [Rust](https://github.com/soml-lang/soml-rust) implementations have a public one, for tools such as linters.
+- **The gem name.** The gem is [`soml-lang`](https://rubygems.org/gems/soml-lang), because `soml` on RubyGems is an unrelated format. It also defines `module SOML`, so the two gems cannot be loaded together.
 
 ## Development
 

data/sig/soml.rbs

@@ -17,15 +17,21 @@ module SOML
 	# Write a hash or an array as SOML, keeping the member order of each hash, or as canonical form with `canonical: true`.
 	def self.generate: (Hash[untyped, untyped] | Array[untyped] value, ?canonical: boolish) -> String
 
+	# Parse a document into a read-only syntax tree for linters and other tools.
+	def self.parse_tree: (string source) -> Tree
+
 	# Format a document, keeping its comments, member order, and spelling.
 	def self.format: (string source) -> String
 
 	# A key in an object or an index in an array.
 	type path_segment = String | Symbol | Integer
 
+	# What `edit` changes: the keys and indexes that lead to a value, or a member or a non-root value node from `parse_tree` of the same source.
+	type edit_target = Array[path_segment] | Tree::MemberNode | Tree::ObjectNode | Tree::ArrayNode | Tree::ScalarNode
+
 	# Change one value in a document, and keep everything else as it is written.
-	def self.edit: (string source, Array[path_segment] path, untyped value, ?delete: false) -> String
-		| (string source, Array[path_segment] path, delete: true) -> String
+	def self.edit: (string source, edit_target path, untyped value, ?delete: false) -> String
+		| (string source, edit_target path, delete: true) -> String
 
 	# Whether a key can be written without quotes, as a bare key. A key is a `String` or a `Symbol`, so anything else gives false.
 	def self.bare_key?: (untyped key) -> bool
@@ -140,4 +146,94 @@ module SOML
 
 		def deconstruct_keys: (Array[Symbol]? keys) -> { nanoseconds: Integer }
 	end
+
+	# A read-only syntax tree, from `parse_tree`. Every offset is a UTF-8 byte offset into `source`, and `finish` is exclusive.
+	class Tree
+		# A node of the tree.
+		type node = ObjectNode | ArrayNode | MemberNode | KeyNode | ScalarNode
+
+		# A `# ...` comment or a `/* ... */` comment, with its text without the delimiters.
+		class Comment < Struct[untyped]
+			attr_reader type: :line | :block
+			attr_reader start: Integer
+			attr_reader finish: Integer
+			attr_reader value: String
+		end
+
+		# A lexical token, with its source text.
+		class Token < Struct[untyped]
+			attr_reader type: :punctuator | :bare_key | :string | :integer | :float | :keyword | :instant | :duration
+			attr_reader start: Integer
+			attr_reader finish: Integer
+			attr_reader value: String
+		end
+
+		# An object, written with braces or, only at the top level, without them.
+		class ObjectNode < Struct[untyped]
+			attr_reader members: Array[MemberNode]
+			attr_reader braced: bool
+			attr_reader start: Integer
+			attr_reader finish: Integer
+			def type: () -> :object
+		end
+
+		class ArrayNode < Struct[untyped]
+			attr_reader elements: Array[ObjectNode | ArrayNode | ScalarNode]
+			attr_reader start: Integer
+			attr_reader finish: Integer
+			def type: () -> :array
+		end
+
+		# A `key: value` member.
+		class MemberNode < Struct[untyped]
+			attr_reader key: KeyNode
+			attr_reader value: ObjectNode | ArrayNode | ScalarNode
+			attr_reader start: Integer
+			attr_reader finish: Integer
+			def type: () -> :member
+		end
+
+		# A key, with its decoded string and how it is written.
+		class KeyNode < Struct[untyped]
+			attr_reader value: String
+			attr_reader start: Integer
+			attr_reader finish: Integer
+			attr_reader style: :bare | :literal | :escaped
+			def type: () -> :key
+		end
+
+		# A value that is not a collection, with its decoded value and how it is written.
+		class ScalarNode < Struct[untyped]
+			attr_reader block: bool
+			attr_reader start: Integer
+			attr_reader finish: Integer
+			attr_reader kind: :string | :integer | :float | :boolean | :null | :instant | :duration
+			attr_reader value: String | Integer | Float | bool | nil | Time | Duration
+			attr_reader style: (:literal | :escaped)?
+			attr_reader radix: (2 | 8 | 10 | 16)?
+			def type: () -> :scalar
+		end
+
+		# The source, in UTF-8.
+		attr_reader source: String
+
+		# The document's collection.
+		attr_reader body: ObjectNode | ArrayNode
+
+		# Every comment, in source order.
+		attr_reader comments: Array[Comment]
+
+		# Every lexical token, in source order.
+		attr_reader tokens: Array[Token]
+
+		# `lean` is internal, for `format` and `edit`.
+		def initialize: (string source, ?lean: boolish) -> void
+
+		# Yield the body and all its descendants in source order.
+		def each_node: () { (node) -> void } -> self
+			| () -> Enumerator[node, self]
+
+		# The 1-based line and column of a byte offset in `source`.
+		def position: (Integer byte_offset) -> [Integer, Integer]
+	end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: soml-lang
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Sindre Sorhus
@@ -11,7 +11,8 @@ date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: A strict parser and a generator for SOML that keeps member order or writes
   canonical form, with exact integers, instants, and durations, and an error message
-  that says what is wrong and where.
+  that says what is wrong and where. With a formatter, an editor that keeps comments
+  and layout, and a syntax tree for linters.
 email:
 - sindresorhus@gmail.com
 executables: []
@@ -37,6 +38,7 @@ licenses:
 metadata:
   source_code_uri: https://github.com/soml-lang/soml-ruby
   bug_tracker_uri: https://github.com/soml-lang/soml-ruby/issues
+  changelog_uri: https://github.com/soml-lang/soml-ruby/releases
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: