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
}
}
keyText
The text a map key is matched by in a path and named by in a diagnostic.
parseYaml
Parses a YAML stream with the default options.
parseYamlWith
Parses a YAML stream with options.
pathMatch
How many steps of a path match (see pathNode).
pathNode
The node a path names.
pathPair
The last map pair a path steps through (see pathNode).
yamlErrorName
The name of a diagnostic code, for a message or a log line.
YamlOptions
How parseYamlWith reads a stream.
YamlStream
Every document, node and diagnostic one parse found.
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
streamYamlStreamrequiredThe parsed stream.
nodei32requiredThe 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
textstringrequiredThe YAML source.
returnsYamlStreamThe 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
textstringrequiredThe YAML source.
optionsYamlOptionsrequiredWhat to keep and check, and how deep collections may nest.
returnsYamlStreamThe 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
streamYamlStreamrequiredThe parsed stream.
rooti32requiredThe node the path starts at.
pathstring[]requiredThe steps, outermost first.
returnsi32The 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
streamYamlStreamrequiredThe parsed stream.
rooti32requiredThe node the path starts at, such as a documentRoot.
pathstring[]requiredThe 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
streamYamlStreamrequiredThe parsed stream.
rooti32requiredThe node the path starts at.
pathstring[]requiredThe steps, outermost first.
returnsi32The pair, or -1 for none.
yamlErrorName
The name of a diagnostic code, for a message or a log line.
const yamlErrorName: (code: i32) => string
codei32requiredA YAML_ERR_* code, such as YAML_ERR_DUPLICATE_KEY.
returnsstringThe 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.

