IF Commons GitHub

yaml

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-formats FR-002

YAML 1.2 for data (commons 0001-formats FR-002), read and written with no outside package. The reader takes what data files, front matter and configuration use: block mappings and sequences (a sequence may sit at its key's indentation, and a mapping may begin on a sequence's dash), flow collections over several lines, plain scalars folded over several lines, single- and double-quoted scalars with every escape of YAML 1.2, literal and folded block scalars with their chomping and indentation indicators, comments and one document between --- and .... Plain scalars resolve by the core schema (null, booleans, integers in decimal, octal and hexadecimal, floats with .inf and .nan) or, with the failsafe schema, stay text. It refuses, with the line and column and the reason, what makes data ambiguous or unsafe to read: anchors and aliases (and so no "billion laughs"), tags, complex keys, directives, more than one document, a key given twice and a tab used for indentation. The writer gives block YAML that the reader reads back as the same value. Replaces @std/yaml in erga.

import { parseYaml, toYaml } from "./yaml.ts";
parseYaml("name: skill\ntags: [a, b]\nsteps:\n  - run: build\n    times: 2\n");
// { kind: "ok", value: { name: "skill", tags: ["a", "b"], steps: [{ run: "build", times: 2 }] } }
toYaml({ name: "skill", on: true }); // "name: skill\non: true\n" (YAML 1.2: "on" is only text)

Source: commons/formats/src/yaml.ts

5 of 7 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

formatYamlErrorfunction
function formatYamlError(e: YamlError): string

A YAML error as one line: 3:14: anchors and aliases are not read.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

isPlainSafefunction
function isPlainSafe(s: string): boolean

Whether text can be written as a plain scalar and read back as the same text by the core schema.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

parseYamlfunction
function parseYaml(text: string, options?: YamlOptions): Result<Json, YamlError>

A YAML text read as a JSON value (an empty document is null), or where and why it is not YAML this reader takes.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

resolveCorefunction
function resolveCore(s: string): Json

A plain scalar resolved by YAML 1.2's core schema.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

toYamlfunction
function toYaml(value: Json): string

A value as block YAML, ending in a line break: mappings and sequences by indentation, text plain where it reads back the same, else double-quoted.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

YamlErrortypeno test imports it
type YamlError = { readonly kind: "yaml"; readonly line: number; readonly column: number; readonly message: string };

Where a text stops being YAML this reader takes, and why. Lines and columns count from 1.

YamlOptionstypeno test imports it
type YamlOptions = { readonly schema?: "core" | "failsafe" };

How plain scalars resolve: by YAML 1.2's core schema (the default), or all as text (failsafe).

Titles, headings, exports, tables, columns and requirements. Esc closes.