yaml 2.8.2 → 3.0.0-0

package/README.md

@@ -14,7 +14,7 @@ It has no external dependencies and runs on Node.js as well as modern browsers.
 For the purposes of versioning, any changes that break any of the documented endpoints or APIs will be considered semver-major breaking changes.
 Undocumented library internals may change between minor versions, and previous APIs may be deprecated (but not removed).
 
-The minimum supported TypeScript version of the included typings is 3.9;
+The minimum supported TypeScript version of the included typings is 5.9;
 for use in earlier versions you may need to set `skipLibCheck: true` in your config.
 This requirement may be updated between minor versions of the library.
 
@@ -25,13 +25,11 @@ For build instructions and contribution guidelines, see [docs/CONTRIBUTING.md](d
 To install:
 
 ```sh
-npm install yaml
+npm install --save-exact yaml@next
 # or
 deno add jsr:@eemeli/yaml
 ```
 
-**Note:** These docs are for `yaml@2`. For v1, see the [v1.10.0 tag](https://github.com/eemeli/yaml/tree/v1.10.0) for the source and [eemeli.org/yaml/v1](https://eemeli.org/yaml/v1/) for the documentation.
-
 ## API Overview
 
 The API provided by `yaml` has three layers, depending on how deep you need to go: [Parse & Stringify](https://eemeli.org/yaml/#parse-amp-stringify), [Documents](https://eemeli.org/yaml/#documents), and the underlying [Lexer/Parser/Composer](https://eemeli.org/yaml/#parsing-yaml).
@@ -41,53 +39,80 @@ A [command-line tool](https://eemeli.org/yaml/#command-line-tool) is also includ
 
 ### Parse & Stringify
 
-```js
-import { parse, stringify } from 'yaml'
-```
+As far as possible, these functions work the same as `JSON.parse` and `JSON.stringify`.
 
 - [`parse(str, reviver?, options?): value`](https://eemeli.org/yaml/#yaml-parse)
 - [`stringify(value, replacer?, options?): string`](https://eemeli.org/yaml/#yaml-stringify)
 
-### Documents
+```js
+import { parse, stringify } from 'yaml'
+
+parse('[ true, false, maybe, null, 3.14159 ]')
+// [ true, false, 'maybe', null, 3.14159 ]
+
+stringify([true, false, 'maybe', null, 3.14159])
+// `- true
+// - false
+// - maybe
+// - null
+// - 3.14159
+// `
+
+stringify({ number: 3, plain: 'string', block: 'two\nlines\n' })
+// `number: 3
+// plain: string
+// block: |
+//   two
+//   lines
+// `
+```
+
+```yaml
+# file.yml
+YAML:
+  - A human-readable data serialization language
+  - https://en.wikipedia.org/wiki/YAML
+yaml:
+  - A complete JavaScript implementation
+  - https://www.npmjs.com/package/yaml
+```
 
-<!-- prettier-ignore -->
 ```js
-import {
-  Document,
-  isDocument,
-  parseAllDocuments,
-  parseDocument
-} from 'yaml'
+import fs from 'node:fs'
+import { parse } from 'yaml'
+
+const file = fs.readFileSync('./file.yml', 'utf8')
+parse(file)
+// { YAML:
+//   [ 'A human-readable data serialization language',
+//     'https://en.wikipedia.org/wiki/YAML' ],
+//   yaml:
+//   [ 'A complete JavaScript implementation',
+//     'https://www.npmjs.com/package/yaml' ] }
 ```
 
+### Documents
+
 - [`Document`](https://eemeli.org/yaml/#documents)
   - [`constructor(value, replacer?, options?)`](https://eemeli.org/yaml/#creating-documents)
-  - [`#contents`](https://eemeli.org/yaml/#content-nodes)
+  - [`#value`](https://eemeli.org/yaml/#content-nodes)
   - [`#directives`](https://eemeli.org/yaml/#stream-directives)
   - [`#errors`](https://eemeli.org/yaml/#errors)
   - [`#warnings`](https://eemeli.org/yaml/#errors)
-- [`isDocument(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
 - [`parseAllDocuments(str, options?): Document[]`](https://eemeli.org/yaml/#parsing-documents)
 - [`parseDocument(str, options?): Document`](https://eemeli.org/yaml/#parsing-documents)
 
-### Content Nodes
-
 <!-- prettier-ignore -->
 ```js
 import {
-  isAlias, isCollection, isMap, isNode,
-  isPair, isScalar, isSeq, Scalar,
-  visit, visitAsync, YAMLMap, YAMLSeq
+  Document,
+  parseAllDocuments,
+  parseDocument
 } from 'yaml'
 ```
 
-- [`isAlias(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
-- [`isCollection(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
-- [`isMap(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
-- [`isNode(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
-- [`isPair(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
-- [`isScalar(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
-- [`isSeq(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
+### Content Nodes
+
 - [`new Scalar(value)`](https://eemeli.org/yaml/#scalar-values)
 - [`new YAMLMap()`](https://eemeli.org/yaml/#collections)
 - [`new YAMLSeq()`](https://eemeli.org/yaml/#collections)
@@ -97,70 +122,25 @@ import {
 - [`visit(node, visitor)`](https://eemeli.org/yaml/#finding-and-modifying-nodes)
 - [`visitAsync(node, visitor)`](https://eemeli.org/yaml/#finding-and-modifying-nodes)
 
-### Parsing YAML
-
+<!-- prettier-ignore -->
 ```js
-import { Composer, Lexer, Parser } from 'yaml'
+import {
+  Scalar,
+  visit,
+  visitAsync,
+  YAMLMap,
+  YAMLSeq
+} from 'yaml'
 ```
 
+### Lexer, Concrete Syntax Tree, and AST Composer
+
 - [`new Lexer().lex(src)`](https://eemeli.org/yaml/#lexer)
 - [`new Parser(onNewLine?).parse(src)`](https://eemeli.org/yaml/#parser)
 - [`new Composer(options?).compose(tokens)`](https://eemeli.org/yaml/#composer)
 
-## YAML.parse
-
-```yaml
-# file.yml
-YAML:
-  - A human-readable data serialization language
-  - https://en.wikipedia.org/wiki/YAML
-yaml:
-  - A complete JavaScript implementation
-  - https://www.npmjs.com/package/yaml
-```
-
-```js
-import fs from 'fs'
-import YAML from 'yaml'
-
-YAML.parse('3.14159')
-// 3.14159
-
-YAML.parse('[ true, false, maybe, null ]\n')
-// [ true, false, 'maybe', null ]
-
-const file = fs.readFileSync('./file.yml', 'utf8')
-YAML.parse(file)
-// { YAML:
-//   [ 'A human-readable data serialization language',
-//     'https://en.wikipedia.org/wiki/YAML' ],
-//   yaml:
-//   [ 'A complete JavaScript implementation',
-//     'https://www.npmjs.com/package/yaml' ] }
-```
-
-## YAML.stringify
-
 ```js
-import YAML from 'yaml'
-
-YAML.stringify(3.14159)
-// '3.14159\n'
-
-YAML.stringify([true, false, 'maybe', null])
-// `- true
-// - false
-// - maybe
-// - null
-// `
-
-YAML.stringify({ number: 3, plain: 'string', block: 'two\nlines\n' })
-// `number: 3
-// plain: string
-// block: |
-//   two
-//   lines
-// `
+import { Composer, Lexer, Parser } from 'yaml'
 ```
 
 ---

package/{bin.mjs → bin.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { UserError, cli, help } from './dist/cli.mjs'
+import { UserError, cli, help } from './dist/cli.js'
 
 cli(process.stdin, error => {
   if (error instanceof UserError) {

package/dist/chunk-BYypO7fO.js

@@ -0,0 +1,18 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll as t };

package/dist/cli.d.ts

@@ -1,8 +1,11 @@
-export declare const help = "yaml: A command-line YAML processor and inspector\n\nReads stdin and writes output to stdout and errors & warnings to stderr.\n\nUsage:\n  yaml          Process a YAML stream, outputting it as YAML\n  yaml cst      Parse the CST of a YAML stream\n  yaml lex      Parse the lexical tokens of a YAML stream\n  yaml valid    Validate a YAML stream, returning 0 on success\n\nOptions:\n  --help, -h    Show this message.\n  --json, -j    Output JSON.\n  --indent 2    Output pretty-printed data, indented by the given number of spaces.\n  --merge, -m   Enable support for \"<<\" merge keys.\n\nAdditional options for bare \"yaml\" command:\n  --doc, -d     Output pretty-printed JS Document objects.\n  --single, -1  Require the input to consist of a single YAML document.\n  --strict, -s  Stop on errors.\n  --visit, -v   Apply a visitor to each document (requires a path to import)\n  --yaml 1.1    Set the YAML version. (default: 1.2)";
-export declare class UserError extends Error {
-    static ARGS: number;
-    static SINGLE: number;
-    code: number;
-    constructor(code: number, message: string);
+//#region src/cli.d.ts
+declare const help: string;
+declare class UserError extends Error {
+  static ARGS: number;
+  static SINGLE: number;
+  code: number;
+  constructor(code: number, message: string);
 }
-export declare function cli(stdin: NodeJS.ReadableStream, done: (error?: Error) => void, argv?: string[]): Promise<void>;
+declare function cli(stdin: NodeJS.ReadableStream, done: (error?: Error) => void, argv?: string[]): Promise<void>;
+//#endregion
+export { UserError, cli, help };

package/dist/cli.js

@@ -0,0 +1,181 @@
+import { n as visit } from "./directives-CG6n4xSM.js";
+import { i as lex, n as Composer, o as prettyToken, r as Parser, t as LineCounter, u as prettifyError } from "./line-counter-TFl552k_.js";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+
+//#region src/cli.ts
+const help = `\
+yaml: A command-line YAML processor and inspector
+
+Reads stdin and writes output to stdout and errors & warnings to stderr.
+
+Usage:
+  yaml          Process a YAML stream, outputting it as YAML
+  yaml cst      Parse the CST of a YAML stream
+  yaml lex      Parse the lexical tokens of a YAML stream
+  yaml valid    Validate a YAML stream, returning 0 on success
+
+Options:
+  --help, -h    Show this message.
+  --json, -j    Output JSON.
+  --indent 2    Output pretty-printed data, indented by the given number of spaces.
+  --merge, -m   Enable support for "<<" merge keys.
+
+Additional options for bare "yaml" command:
+  --doc, -d     Output pretty-printed JS Document objects.
+  --single, -1  Require the input to consist of a single YAML document.
+  --strict, -s  Stop on errors.
+  --visit, -v   Apply a visitor to each document (requires a path to import)
+  --yaml 1.1    Set the YAML version. (default: 1.2)`;
+var UserError = class extends Error {
+	static ARGS = 2;
+	static SINGLE = 3;
+	code;
+	constructor(code, message) {
+		super(`Error: ${message}`);
+		this.code = code;
+	}
+};
+async function cli(stdin, done, argv) {
+	let args;
+	try {
+		args = parseArgs({
+			args: argv,
+			allowPositionals: true,
+			options: {
+				doc: {
+					type: "boolean",
+					short: "d"
+				},
+				help: {
+					type: "boolean",
+					short: "h"
+				},
+				indent: {
+					type: "string",
+					short: "i"
+				},
+				merge: {
+					type: "boolean",
+					short: "m"
+				},
+				json: {
+					type: "boolean",
+					short: "j"
+				},
+				single: {
+					type: "boolean",
+					short: "1"
+				},
+				strict: {
+					type: "boolean",
+					short: "s"
+				},
+				visit: {
+					type: "string",
+					short: "v"
+				},
+				yaml: {
+					type: "string",
+					default: "1.2"
+				}
+			}
+		});
+	} catch (error) {
+		return done(new UserError(UserError.ARGS, error.message));
+	}
+	const { positionals: [mode], values: opt } = args;
+	let indent = Number(opt.indent);
+	stdin.setEncoding("utf-8");
+	switch (opt.help || mode) {
+		case true:
+			console.log(help);
+			break;
+		case "lex": {
+			const chunks = [];
+			stdin.on("data", (chunk) => chunks.push(chunk));
+			stdin.on("end", () => {
+				const data = [];
+				for (const tok of lex(chunks.join(""))) if (opt.json) data.push(tok);
+				else console.log(prettyToken(tok));
+				if (opt.json) console.log(JSON.stringify(data, null, indent));
+				done();
+			});
+			break;
+		}
+		case "cst": {
+			const chunks = [];
+			stdin.on("data", (chunk) => chunks.push(chunk));
+			stdin.on("end", () => {
+				const data = [];
+				for (const tok of new Parser().parse(chunks.join(""))) if (opt.json) data.push(tok);
+				else console.dir(tok, { depth: null });
+				if (opt.json) console.log(JSON.stringify(data, null, indent));
+				done();
+			});
+			break;
+		}
+		case void 0:
+		case "valid": {
+			const visitor = opt.visit ? (await import(resolve(opt.visit))).default : null;
+			let source = "";
+			stdin.on("data", (chunk) => source += chunk);
+			stdin.on("end", () => {
+				const lineCounter = new LineCounter();
+				const composer = new Composer({
+					version: opt.yaml,
+					merge: opt.merge
+				});
+				const parser = new Parser(lineCounter.addNewLine);
+				let hasDoc = false;
+				let reqDocEnd = false;
+				const data = [];
+				for (const tok of parser.parse(source)) composer.next(tok);
+				for (const doc of composer.end(false)) {
+					if (hasDoc && opt.single) return done(new UserError(UserError.SINGLE, "Input stream contains multiple documents"));
+					for (const error of doc.errors) {
+						prettifyError(source, lineCounter)(error);
+						if (opt.strict || mode === "valid") return done(error);
+						console.error(error);
+					}
+					for (const warning of doc.warnings) {
+						prettifyError(source, lineCounter)(warning);
+						console.error(warning);
+					}
+					if (visitor) visit(doc, visitor);
+					if (mode === "valid") doc.toJS();
+					else if (opt.json) data.push(doc);
+					else if (opt.doc) {
+						Object.defineProperties(doc, {
+							options: { enumerable: false },
+							schema: { enumerable: false }
+						});
+						console.dir(doc, { depth: null });
+					} else {
+						if (reqDocEnd) console.log("...");
+						try {
+							indent ||= 2;
+							const str = doc.toString({ indent });
+							console.log(str.endsWith("\n") ? str.slice(0, -1) : str);
+						} catch (error) {
+							done(error);
+						}
+					}
+					hasDoc = true;
+					reqDocEnd = !doc.directives?.docEnd;
+				}
+				if (opt.single && !hasDoc) return done(new UserError(UserError.SINGLE, "Input stream contained no documents"));
+				if (mode !== "valid" && opt.json) console.log(JSON.stringify(opt.single ? data[0] : data, null, indent));
+				done();
+			});
+			break;
+		}
+		default: {
+			const msg = `Unknown command: ${JSON.stringify(mode)}`;
+			done(new UserError(UserError.ARGS, msg));
+		}
+	}
+}
+
+//#endregion
+export { UserError, cli, help };