nish/yaml-json

One YAML document loaded into a JsonDocument, with every value's and key's source range, so that one validator and one YamlLineIndex serve a JSON text and a YAML text alike:

import {
  YAML_JSON_ERR_DEPTH,
  YAML_JSON_ERR_DOCUMENT,
  YAML_JSON_ERR_EXPANSION,
  YAML_JSON_ERR_MERGE,
  YAML_JSON_ERR_NOT_FINITE,
  YAML_JSON_ERR_NUMBER,
  YAML_JSON_ERR_YAML,
  YAML_JSON_MAX_RADIX_DIGITS,
  YAML_JSON_SCAN_KEYS,
  YamlJsonLoader,
  yamlJsonErrorName,
} from "nish/yaml-json";
import { parseYaml } from "nish/yaml"
import { JsonDocument, JsonLimits } from "nish/json-value"
import { YamlJsonLoader } from "nish/yaml-json"

const stream = parseYaml(text)
const doc = new JsonDocument(new JsonLimits())
const loader = new YamlJsonLoader()
const root = loader.load(stream, 0, doc)
// root < 0: loader.failed, loader.errorStart, loader.errorEnd

load clears the document and builds document d of the stream into it. Every value's start and end are the byte range of the YAML node it came from, as YamlStream.start and end give it (an anchor or a tag in front is not included), and every key's keyStart and keyEnd the range of its key node, quotes included. A key or value the text leaves out, the value of a: or the key of : b, is an empty range at the end of its pair.

Scalars

Scalars follow the core schema the stream resolves: null, booleans, numbers and strings. A number is kept as JSON text, exactly: a + sign is dropped, leading zeros are dropped, .5 is 0.5 and 1. is 1.0, and a 0x or 0o integer is written in decimal, however wide (up to YAML_JSON_MAX_RADIX_DIGITS digits). .inf, -.inf and .nan have no JSON spelling and are YAML_JSON_ERR_NOT_FINITE.

Keys

Keys are keyText's: a string's decoded text, a number's or a boolean's source text, "" for null, a collection's flow text. Two YAML keys that are different nodes can have the same text (1 and "1"); the second follows the document's duplicates, refused by default (JSON_VALUE_ERR_DUPLICATE, at the second key) or holding the last value under JSON_VALUE_DUPLICATE_LAST, as a parse of that JSON would.

Aliases are expanded

Aliases are expanded into copies, and merge keys (<<, when the stream was parsed with merge) are applied as pathNode reads them: the map's own keys first, in order, then each merged map's keys it does not already have, the first map listed winning, searched through its own merge keys. A copied value keeps the ranges of the nodes it was copied from, so an error inside it points at the anchored text, and the copy's root takes the alias's range, where it is used.

An alias bomb is refused before anything is built. The values the document expands to are counted first, from the nodes, with each node's count kept, so the count costs one step per node however far the aliases multiply it. Past the document's maxValues the load is YAML_JSON_ERR_EXPANSION, at the first alias whose copy is the largest (the first whose copy alone is past the limit, in a bomb), or JSON_VALUE_ERR_VALUES when the document has no alias.

A merged map counts all its keys, also those the merging map overrides, so a document within a few values of the limit can be refused for merges that would have fit. The loader's merging is linear too: a map is merged into a given map at most once, however many paths through the merge keys reach it, and the pairs every merge visits and the items of every merge sequence it walks are charged to a budget of maxValues plus the stream's node count, past which the load is YAML_JSON_ERR_EXPANSION at the merge key.

parseYaml's own merge check is not bounded this way: it walks a shared merge sequence once for each merge key that names it.

A merge key's value

A merge key's value is a mapping, an alias to one, or a sequence of those; anything else is refused at the value, by the parser as YAML_ERR_BAD_MERGE (so YAML_JSON_ERR_YAML) and by the loader as YAML_JSON_ERR_MERGE. The text the copies store is bounded too, while they are built: past the document's JsonLimits.maxTotalBytes of string, key and number text, the load is YAML_JSON_ERR_EXPANSION at the outermost alias being copied, or JSON_TOK_ERR_TOTAL_LIMIT at the node when no alias is.

Nesting

Nesting is held to maxDepth, JSON_WRITER_MAX_DEPTH (64) by default, counting copies, so that every loaded document can be written back as JSON; deeper is YAML_JSON_ERR_DEPTH, at the node that is one too deep.

A document with an error diagnostic is YAML_JSON_ERR_YAML, at the first one's range, and loads nothing: a node the parser gave up on has no value to load. Warnings are not errors.

A failed load clears the document and answers the code, which is also in failed, with the range it is about in errorStart and errorEnd. yamlJsonErrorName names a code. A map of n keys costs O(n) steps: the loader finds repeated keys itself, with a hash map past YAML_JSON_SCAN_KEYS keys, and adds each member through JsonDocument's internal append, where set would scan the members for every key it adds. Every member it adds is a value it has just made, which is the check append skips.

Every name here is yamlJson-prefixed, because a std/ module is compiled into the program that imports it and the symbol namespace is flat (std/README.md). Every offset, count and code is an i32, and the module runs under the Node prelude, where offsets count UTF-16 code units, as the stream's do.

Functions

yamlJsonErrorName

A load failure's name, for a message.

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

A YAML_JSON_ERR_* code, as failed holds it.

returnsstring

The code's name without the YAML_JSON_ERR_ prefix, such as "DEPTH"; "" for any other code.

Classes

YamlJsonLoader

Loads documents of a YamlStream into a JsonDocument. Keeps its scratch, in private fields, from one load to the next; use load and the result fields.

class YamlJsonLoader
Member
new YamlJsonLoader() A loader that holds collections to JSON_WRITER_MAX_DEPTH, so whatever it loads can be written back out.
errorEnd: i32 One past the last byte the failure is about; -1 after a load that succeeds.
errorStart: i32 The first byte the failure is about; -1 after a load that succeeds.
failed: i32 The last load's code: 0, a YAML_JSON_ERR_* code or a JSON_VALUE_ERR_* code.
maxDepth: i32 How deeply collections may nest, counting copies; JSON_WRITER_MAX_DEPTH so the result can be written.
load(stream: YamlStream, d: i32, doc: JsonDocument): JsonValue Clears doc and loads document d of stream into it. Nothing is kept from a load that fails.

Limits

256

YAML_JSON_MAX_RADIX_DIGITS: i32

The most digits a 0x or 0o integer may have, which is JSON_DEFAULT_MAX_NUMBER_BYTES: writing one in decimal costs its digit count times its decimal length, so a limit keeps a long one from costing the square of the text.

Constants

-44

YAML_JSON_ERR_DEPTH: i32

Collections nest deeper than maxDepth, counting copies.

-40

YAML_JSON_ERR_DOCUMENT: i32

Document d is not in the stream.

-43

YAML_JSON_ERR_EXPANSION: i32

The aliases and merge keys expand the document past maxValues; the range is the first largest alias's.

-46

YAML_JSON_ERR_MERGE: i32

A merge key's value is not a mapping or a sequence of mappings; the range is the value's. parseYaml refuses these itself (YAML_ERR_BAD_MERGE, a load's YAML_JSON_ERR_YAML); this is the loader's own check of the stream it is given.

-42

YAML_JSON_ERR_NOT_FINITE: i32

.inf, -.inf or .nan, which JSON cannot spell.

-45

YAML_JSON_ERR_NUMBER: i32

A 0x or 0o integer with more than YAML_JSON_MAX_RADIX_DIGITS digits.

-41

YAML_JSON_ERR_YAML: i32

The document has an error diagnostic; the range is the first one's.

16

YAML_JSON_SCAN_KEYS: i32

Up to this many keys a map's keys are compared with each other; past it, through a hash map.