nish/yaml

A YAML 1.2 parser that keeps where everything came from.

import {
  YAML_ALIAS,
  YAML_BLOCK,
  YAML_BOOL,
  YAML_DOUBLE_QUOTED,
  YAML_ERR_AMBIGUOUS_ANCHOR_NAME,
  YAML_ERR_BAD_ANCHOR,
  YAML_ERR_BAD_BLOCK_HEADER,
  YAML_ERR_BAD_COMMENT,
  YAML_ERR_BAD_DIRECTIVE,
  YAML_ERR_BAD_ESCAPE,
  YAML_ERR_BAD_IMPLICIT_KEY,
  YAML_ERR_BAD_INDENT,
  YAML_ERR_BAD_MERGE,
  YAML_ERR_BAD_PROPERTY,
  YAML_ERR_BAD_SCALAR_CONTENT,
  YAML_ERR_BAD_SCALAR_START,
  YAML_ERR_BAD_TAG,
  YAML_ERR_BAD_TAG_VALUE,
  YAML_ERR_DEPTH_LIMIT,
  YAML_ERR_DUPLICATE_DIRECTIVE,
  YAML_ERR_DUPLICATE_KEY,
  YAML_ERR_MULTIPLE_DOCUMENTS,
  YAML_ERR_RECURSIVE_ALIAS,
  YAML_ERR_TAB_INDENT,
  YAML_ERR_UNEXPECTED_COMMA,
  YAML_ERR_UNEXPECTED_CONTENT,
  YAML_ERR_UNEXPECTED_DIRECTIVE,
  YAML_ERR_UNKNOWN_DIRECTIVE,
  YAML_ERR_UNKNOWN_TAG_HANDLE,
  YAML_ERR_UNRESOLVED_ALIAS,
  YAML_ERR_UNSUPPORTED_YAML_VERSION,
  YAML_ERR_UNTERMINATED_FLOW,
  YAML_ERR_UNTERMINATED_QUOTE,
  YAML_FLOAT,
  YAML_FLOW,
  YAML_FOLDED,
  YAML_INT,
  YAML_LITERAL,
  YAML_MAP,
  YAML_NULL,
  YAML_PAIR,
  YAML_PLAIN,
  YAML_SCALAR,
  YAML_SEQ,
  YAML_SINGLE_QUOTED,
  YAML_STRING,
  YamlOptions,
  YamlStream,
  keyText,
  parseYaml,
  parseYamlWith,
  pathMatch,
  pathNode,
  pathPair,
  yamlErrorName,
} from "nish/yaml";
import { parseYaml, YAML_MAP } from "nish/yaml"

const stream = parseYaml(text)
const root: i32 = stream.documentRoot(0)
if (stream.kind(root) === YAML_MAP) {
  let i: i32 = 0
  while (i < stream.count(root)) {
    const pair: i32 = stream.child(root, i)
    // stream.key(pair), stream.value(pair), stream.text(node) ...
    i += 1
  }
}

A parse never fails. It answers a YamlStream: every document of the text, every node of every document, and every problem found on the way, each with the byte range of the source it is about. A program that only wants the data reads the nodes; a linter, an editor or a schema checker reads the ranges too, and nish/yaml-lines turns a range into the line:column a person reads.

A node is an `i32` handle

A node is an i32 handle into the stream's arrays, one array per field (struct of arrays), and -1 is no node. A node is a range of the source, nothing more, until it is asked for: a scalar's text is decoded, and its type resolved against the core schema, only when a caller reads them. So a parse allocates its arrays and its problems and very little else, and a caller that walks to one key pays to decode one key.

The kinds are YAML_SCALAR, YAML_MAP, YAML_SEQ, YAML_ALIAS and YAML_PAIR. A map's children are its pairs, in source order; a pair's key and value are nodes. A seq's children are its items. An alias's target is the node its anchor named. A map holds the pairs it was written with, and merge keys (<<) are not copied into it: a << key is exempt from the duplicate-key check, its value must be a map, an alias to one or a sequence of those, and pathNode and pathPair look a key a map lacks up in the maps it merges.

Diagnostics

Diagnostics carry a YAML_ERR_* code, whether they are a warning, a message, a byte range and the document they belong to, sorted by where they start. An error means the stream is not valid YAML and the nodes are the parser's best reading of it; a warning means it is valid and probably not what was meant. The codes and their spelling (yamlErrorName) are the ones other YAML tooling reports, so a message from here reads the same as one from there.

Strings are UTF-8, offsets are bytes. Tabs are not indentation (YAML forbids it), and YAML 1.1's booleans (yes, on) are strings, as 1.2 says.

Functions

keyText

The text a map key is matched by in a path and named by in a diagnostic.

const keyText: (stream: YamlStream, node: i32) => string
streamYamlStreamrequired

The parsed stream.

nodei32required

The key node.

returnsstring

A scalar's decoded text (its source text for a number or a boolean, "" for a null), an alias's target's text (*name when it names no anchor), or a collection written as one line of flow text, { a: 1 } or [ a, b ], cut to … past 4096 bytes at a character's start or past nesting depth 64.

parseYaml

Parses a YAML stream with the default options.

const parseYaml: (text: string) => YamlStream
textstringrequired

The YAML source.

returnsYamlStream

The documents, nodes and diagnostics the parse found.

parseYamlWith

Parses a YAML stream with options. Panics when maxDepth is outside 1 to 1000.

const parseYamlWith: (
  text: string,
  options: YamlOptions,
) => YamlStream
textstringrequired

The YAML source.

optionsYamlOptionsrequired

What to keep and check, and how deep collections may nest.

returnsYamlStream

The documents, nodes and diagnostics the parse found.

pathMatch

How many steps of a path match (see pathNode).

const pathMatch: (
  stream: YamlStream,
  root: i32,
  path: string[],
) => i32
streamYamlStreamrequired

The parsed stream.

rooti32required

The node the path starts at.

pathstring[]required

The steps, outermost first.

returnsi32

The matching steps, an empty value's included: path.length when every step matches.

pathNode

The node a path names. Each step is a map key (matched by keyText; of duplicate keys, the last) or a sequence index ("0", no leading zero), through aliases. While the stream merges (YamlOptions.merge), a key a map does not hold is looked for in the maps its << keys name, in order: the map's own keys win, then the first merged map that has it, and the pair found is the one inside that map.

const pathNode: (
  stream: YamlStream,
  root: i32,
  path: string[],
) => i32
streamYamlStreamrequired

The parsed stream.

rooti32required

The node the path starts at, such as a documentRoot.

pathstring[]required

The steps, outermost first.

returnsi32

The node the last matching step reached, as written (an alias is not followed): root itself for an empty path, and -1 when a step lands on an empty value (a:). A chain of more than YAML_ALIAS_HOPS (100) aliases stops the walk at its first alias, which is returned, not -1.

pathPair

The last map pair a path steps through (see pathNode).

const pathPair: (
  stream: YamlStream,
  root: i32,
  path: string[],
) => i32
streamYamlStreamrequired

The parsed stream.

rooti32required

The node the path starts at.

pathstring[]required

The steps, outermost first.

returnsi32

The pair, or -1 for none.

yamlErrorName

The name of a diagnostic code, for a message or a log line.

const yamlErrorName: (code: i32) => string
codei32required

A YAML_ERR_* code, such as YAML_ERR_DUPLICATE_KEY.

returnsstring

The code's name without its prefix, such as "DUPLICATE_KEY", or "" for a number that is not a code.

Classes

YamlOptions

How parseYamlWith reads a stream. Make one with new YamlOptions() and set what differs.

class YamlOptions
Member
new YamlOptions()
firstDocumentOnly: boolean Whether only the first document is read, with MULTIPLE_DOCUMENTS if more follow.
keepComments: boolean Whether the stream keeps the byte range of every comment (commentCount).
maxDepth: i32 How deeply collections may nest before DEPTH_LIMIT; 1 to 1000, and anything else panics.
merge: boolean Whether a plain << key is a merge key: exempt from uniqueKeys, checked to name maps, and followed by paths. The nodes are not changed either way.
uniqueKeys: boolean Whether a map that repeats a key is reported (DUPLICATE_KEY).

YamlStream

Every document, node and diagnostic one parse found. A member marked @internal is the parser's working state, public only so that the parser and the walkers can fill and read it; use the others.

A read never panics: a handle that names no node (-1, or one past the stream), or a read that does not fit the node's kind (count of a scalar, intValue of a string), answers a default — -1 for a node or an offset, 0, false or "" otherwise — as each method says.

class YamlStream
Member
new YamlStream(text: string) An empty stream over text, for the parser to fill; get a parsed one from parseYaml.
errors: i32 How many of the diagnostics are errors; the same as errorCount().
merge: boolean Whether a plain << key is a merge key, as YamlOptions.merge said; paths follow merge keys while it is.
source: string The text the stream was parsed from; every offset is into it.
warnings: i32 How many of the diagnostics are warnings; the same as warningCount().
anchor(n: i32): string Node n's anchor name.
boolValue(n: i32): boolean A boolean scalar's value.
child(n: i32, i: i32): i32 One child of a map or a seq.
comment(i: i32): string Comment i's text.
commentCount(): i32 How many comments the stream kept.
commentEnd(i: i32): i32 Where comment i ends.
commentStart(i: i32): i32 Where comment i starts.
count(n: i32): i32 How many children node n has.
diagnosticCode(i: i32): i32 What diagnostic i is about.
diagnosticCount(): i32 How many diagnostics the parse found, errors and warnings, in order of where they start.
diagnosticDocument(i: i32): i32 The document diagnostic i was found in.
diagnosticEnd(i: i32): i32 Where diagnostic i's range ends.
diagnosticIsWarning(i: i32): boolean Whether diagnostic i is a warning rather than an error.
diagnosticMessage(i: i32): string Diagnostic i's message, for a person.
diagnosticStart(i: i32): i32 Where diagnostic i's range starts.
documentCount(): i32 How many documents the stream holds.
documentEnd(d: i32): i32 Where document d ends.
documentRoot(d: i32): i32 Document d's root node.
documentStart(d: i32): i32 Where document d starts.
end(n: i32): i32 Where node n's source ends.
errorCount(): i32 How many of the diagnostics are errors.
floatValue(n: i32): f64 A number scalar's value.
intValue(n: i32): i64 An integer scalar's value.
key(pair: i32): i32 A pair's key.
kind(n: i32): i32 What node n is.
resolved(n: i32): i32 Node n with an alias followed.
start(n: i32): i32 Where node n's source starts, its anchor and tag not included.
style(n: i32): i32 How node n is written.
tag(n: i32): string Node n's tag, resolved.
target(n: i32): i32 The node an alias names.
text(n: i32): string A scalar's text, decoded: quotes and escapes undone, lines folded, a block scalar's indentation and chomping applied. A \u surrogate pair is one character; a lone surrogate escape is kept as its three bytes, which are not UTF-8. Decoded on every call; keep the result.
type(n: i32): i32 A scalar's core-schema type. Untagged, a plain scalar is typed from its text and a quoted or block scalar is a string. Under a !!null, !!bool or !!int tag it is that type when its text (decoded, for a quoted or block scalar) reads as one, and a string otherwise; under !!float an int or float text is a float. Any other tag, !!str included, makes it a string.
value(pair: i32): i32 A pair's value.
warningCount(): i32 How many of the diagnostics are warnings.

Constants

4

YAML_ALIAS: i32

An alias (*name); target is the anchored node.

6

YAML_BLOCK: i32

An indented collection.

1

YAML_BOOL: i32

true or false.

2

YAML_DOUBLE_QUOTED: i32

A "..." scalar, the one style with escapes.

1

YAML_ERR_AMBIGUOUS_ANCHOR_NAME: i32

Warning: an anchor or alias name ends in :, which YAML reads as part of the name.

2

YAML_ERR_BAD_ANCHOR: i32

An anchor or alias whose name is empty or runs on into a flow indicator.

3

YAML_ERR_BAD_BLOCK_HEADER: i32

A block scalar header that is not | or > with at most one indentation digit and one chomping indicator.

4

YAML_ERR_BAD_COMMENT: i32

A # that no whitespace precedes, so it cannot start a comment.

5

YAML_ERR_BAD_DIRECTIVE: i32

A %YAML directive with a bad version or content after it; as a warning, a %TAG directive missing its handle or prefix.

6

YAML_ERR_BAD_ESCAPE: i32

A double-quoted escape that is not one: an unknown letter, the wrong count of hex digits, or a code point past U+10FFFF.

7

YAML_ERR_BAD_IMPLICIT_KEY: i32

An implicit key that does not fit on one line, or runs more than 1024 bytes before its :.

8

YAML_ERR_BAD_INDENT: i32

A quoted scalar or flow collection continued on a line not indented deeper than its parent, or a block scalar whose leading blank line is indented deeper than its first content line.

9

YAML_ERR_BAD_MERGE: i32

A << merge whose value is not a map, an alias to one, or a sequence of those.

10

YAML_ERR_BAD_PROPERTY: i32

A node with two anchors or two tags, an alias with an anchor or tag, or node properties written before a ? explicit key indicator on its line.

11

YAML_ERR_BAD_SCALAR_CONTENT: i32

A plain scalar that holds : , which only a key may.

12

YAML_ERR_BAD_SCALAR_START: i32

A plain scalar that starts with an indicator character, or a flow entry that starts with -.

13

YAML_ERR_BAD_TAG: i32

A tag that is empty or not well formed.

14

YAML_ERR_BAD_TAG_VALUE: i32

Warning: a !! core tag on the wrong kind of node (!!map on a scalar, say), which only warns, or a scalar whose text its !!int, !!float, !!bool or !!null tag cannot read, which is kept as a string.

15

YAML_ERR_DEPTH_LIMIT: i32

Collections nested deeper than maxDepth; the parse stops there.

16

YAML_ERR_DUPLICATE_DIRECTIVE: i32

A second %YAML directive in one document; as a warning, a %TAG handle declared twice.

17

YAML_ERR_DUPLICATE_KEY: i32

A map that repeats a key, when uniqueKeys asks for the check.

18

YAML_ERR_MULTIPLE_DOCUMENTS: i32

Warning: the stream has more documents than the first, which firstDocumentOnly left unread.

19

YAML_ERR_RECURSIVE_ALIAS: i32

An alias inside the node its anchor names.

20

YAML_ERR_TAB_INDENT: i32

A tab used to indent; YAML indents with spaces only.

21

YAML_ERR_UNEXPECTED_COMMA: i32

A , in a flow collection with no entry before it.

22

YAML_ERR_UNEXPECTED_CONTENT: i32

Text where no node may start, such as after the end of a node or a document marker inside a flow collection.

23

YAML_ERR_UNEXPECTED_DIRECTIVE: i32

A directive that no ... precedes or no --- follows.

24

YAML_ERR_UNKNOWN_DIRECTIVE: i32

Warning: a directive other than %YAML and %TAG; it is skipped.

25

YAML_ERR_UNKNOWN_TAG_HANDLE: i32

A tag whose handle no %TAG directive declared.

26

YAML_ERR_UNRESOLVED_ALIAS: i32

An alias with no anchor of that name before it.

27

YAML_ERR_UNSUPPORTED_YAML_VERSION: i32

Warning: a %YAML version other than 1.2; the document is parsed as 1.2.

28

YAML_ERR_UNTERMINATED_FLOW: i32

A flow collection with no closing ] or }.

29

YAML_ERR_UNTERMINATED_QUOTE: i32

A quoted scalar with no closing quote.

3

YAML_FLOAT: i32

A number with a fraction or exponent, an infinity (.inf, -.inf) or not-a-number (.nan).

5

YAML_FLOW: i32

A [...] or {...} collection, or the one-pair map [a: b] holds.

4

YAML_FOLDED: i32

A > block scalar.

2

YAML_INT: i32

An integer: decimal, 0o octal or 0x hex.

3

YAML_LITERAL: i32

A | block scalar.

2

YAML_MAP: i32

A mapping; its children are YAML_PAIR nodes.

0

YAML_NULL: i32

A scalar's core-schema type, from type; -1 for a node that is not a scalar.

5

YAML_PAIR: i32

One key and value of a mapping.

0

YAML_PLAIN: i32

A plain scalar, or a node with no style of its own (an alias, a pair).

1

YAML_SCALAR: i32

A scalar: plain, quoted or a block scalar.

3

YAML_SEQ: i32

A sequence; its children are its items.

1

YAML_SINGLE_QUOTED: i32

A '...' scalar.

4

YAML_STRING: i32

Every other scalar; a quoted or block scalar is one unless a !! core tag that fits its text says otherwise.