Merge pull request #249 from eemeli/normal-flow

Split flow collections into items in Parser
eemeli · Apr 1, 2021 · bdd47ad · bdd47ad
2 parents 4fa8de1 + 9340ef7
commit bdd47ad
Show file tree

Hide file tree

Showing 11 changed files with 356 additions and 266 deletions.
diff --git a/docs/07_parsing_yaml.md b/docs/07_parsing_yaml.md
@@ -187,10 +187,17 @@ Some of the most common node properties include:
 | `offset`              | `number`        | The start index within the source string or character stream.                                                                                 |
 | `source`              | `string`        | A raw string representation of the node's value, including all newlines and indentation.                                                      |
 | `indent`              | `number`        | The indent level of the current line; mostly just for internal use.                                                                           |
-| `items`               | `{ ... }[]`     | The contents of a collection; shape depends on the collection type, and may include `key: Token` and `value: Token`.                          |
+| `items`               | `Item[]`        | The contents of a collection; exact shape depends on the collection type.                                                                     |
 | `start`, `sep`, `end` | `SourceToken[]` | Content before, within, and after "actual" values. Includes item and collection indicators, anchors, tags, comments, as well as other things. |
 
-As an implementation detail, block and flow collections are parsed and presented rather differently due to their structural differences.
+Collection items contain some subset of the following properties:
+
+| Item property | Type            | Description                                                                                                                |
+| ------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `start`       | `SourceToken[]` | Always defined. Content before the actual value. May include comments that are later assigned to the preceding item.       |
+| `key`         | `Token ⎮ null`  | Set for key/value pairs only, so never used in block sequences.                                                            |
+| `sep`         | `SourceToken[]` | Content between the key and the value. If defined, indicates that the `key` logically exists, even if its value is `null`. |
+| `value`       | `Token ⎮ null`  | The value. Normally set, but may be left out for e.g. explicit keys with no matching value.                                |
 
 ### Counting Lines
 

diff --git a/docs/08_errors.md b/docs/08_errors.md
@@ -28,6 +28,7 @@ To identify errors for special handling, you should primarily use `code` to diff
 | `BAD_DIRECTIVE`          | Only the `%YAML` and `%TAG` directives are supported, and they need to follow the specified strucutre.                                                                       |
 | `BAD_DQ_ESCAPE`          | Double-quotes strings may include `\` escaped content, but that needs to be valid.                                                                                           |
 | `BAD_INDENT`             | Indentation is important in YAML, and collection items need to all start at the same level. Block scalars are also picky about their leading content.                        |
+| `BAD_PROP_ORDER`         | Anchors and tags must be placed after the `?`, `:` and `-` indicators.                                                                                                       |
 | `BAD_SCALAR_START`       | Plain scalars cannot start with a block scalar indicator, or one of the two reserved characters: `@` and <code>`</code>. To fix, use a block or quoted scalar for the value. |
 | `BLOCK_AS_IMPLICIT_KEY`  | There's probably something wrong with the indentation, or you're trying to parse something like `a: b: c`, where it's not clear what's the key and what's the value.         |
 | `BLOCK_IN_FLOW`          | YAML scalars and collections both have block and flow styles. Flow is allowed within block, but not the other way around.                                                    |
@@ -40,7 +41,6 @@ To identify errors for special handling, you should primarily use `code` to diff
 | `MULTIPLE_ANCHORS`       | A node is only allowed to have one anchor.                                                                                                                                   |
 | `MULTIPLE_DOCS`          | A YAML stream may include multiple documents. If yours does, you'll need to use `parseAllDocuments()` to work with it.                                                       |
 | `MULTIPLE_TAGS`          | A node is only allowed to have one tag.                                                                                                                                      |
-| `PROP_BEFORE_SEP`        | For an explicit key, anchors and tags must be after the `?` indicator                                                                                                        |
 | `TAB_AS_INDENT`          | Only spaces are allowed as indentation.                                                                                                                                      |
 | `TAG_RESOLVE_FAILED`     | Something went wrong when resolving a node's tag with the current schema.                                                                                                    |
 | `UNEXPECTED_TOKEN`       | A token was encountered in a place where it wasn't expected.                                                                                                                 |