nish/yaml-write

A JSON value written as YAML text that parseYaml reads back as the same tree.

import {
  stringifyYaml,
} from "nish/yaml-write";
import { JsonDocument } from "nish/json-value"
import { JsonLimits } from "nish/json-tokenizer"
import { stringifyYaml } from "nish/yaml-write"

const doc = new JsonDocument(new JsonLimits())
const root = doc.parseText('{"name":"tea","on":"yes","ports":[80,443],"tags":{}}')
stringifyYaml(doc, root)
// name: tea
// "on": "yes"
// ports:
//   - 80
//   - 443
// tags: {}
Block style

An object is a block map and an array a block sequence, indented two spaces a level, members in their order; an empty one is {} or []. A sequence item that is itself a collection starts on the item's line (- a: 1). null, true and false are written as themselves and a number as its text, which the core schema reads as an integer or a float. The text ends with a line break.

A string is plain unless it could read as something else

It is written double-quoted

  • when it is empty;
  • when it reads as null, a boolean or a number under YAML 1.2 or YAML 1.1 (~, null, yes, on, y, true in any case; anything starting with a digit, or a sign or . and then a digit; .inf and .nan, signed or not);
  • when it starts with an indicator (@, `, \, *, &, !, |, >, %, ', ", #, ,, [, ], {, }, or -, ? or : before a space or the end) or with --- or ...;
  • when it holds : or # or ends in :;
  • when it starts or ends with a space;
  • when it holds a control character, a line break, U+2028, U+2029, U+FEFF, U+FFFE or U+FFFF;
  • and, as a key, when it is <<, which YAML reads as a merge key.

Keys and values follow the same rule. A quoted string escapes ", \ and every character just listed, so it stays on one line. A key whose written form runs past the 1024 bytes YAML allows an implicit key is written as an explicit one, ? key and then : value.

What it answers

The YAML text, or "" when v names no value or the tree nests deeper than JSON_WRITER_MAX_DEPTH collections, the limit stringify keeps: a parsed tree never does, and a built one is refused rather than recursed into without bound.

A string is written as its UTF-8 bytes. Under Node a string is UTF-16 and each unit is read as a byte, so non-ASCII text differs from the native build, as it does in nish/json-value's builders.

Functions

stringifyYaml

A value as block YAML text that parseYaml reads back as the same tree. See the module comment for the rule that quotes a string.

const stringifyYaml: (
  doc: JsonDocument,
  v: JsonValue,
) => string
docJsonDocumentrequired

The document that holds v.

vJsonValuerequired

The value to write, usually the document's root.

returnsstring

The text, ending in a line break; "" when v names no value or nests deeper than JSON_WRITER_MAX_DEPTH collections.