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
yamlJsonErrorName
A load failure's name, for a message.
YamlJsonLoader
Loads documents of a YamlStream into a JsonDocument.
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
codei32requiredA YAML_JSON_ERR_* code, as failed holds it.
returnsstringThe 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.

