diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index d7536adbb..a5a533303 100644 --- a/_tools/check_docs.ts +++ b/_tools/check_docs.ts @@ -71,6 +71,8 @@ const ENTRY_POINTS = [ "../url/mod.ts", "../uuid/mod.ts", "../webgpu/mod.ts", + "../yaml/parse.ts", + "../yaml/stringify.ts", ] as const; const TS_SNIPPET = /```ts[\s\S]*?```/g; diff --git a/yaml/parse.ts b/yaml/parse.ts index 72355b443..b591ad6f3 100644 --- a/yaml/parse.ts +++ b/yaml/parse.ts @@ -4,8 +4,7 @@ // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. // This module is browser compatible. -import type { Schema } from "./schema.ts"; -import { type CbFunction, load, loadAll } from "./_loader/loader.ts"; +import { load, loadAll } from "./_loader/loader.ts"; import { replaceSchemaNameWithSchemaClass } from "./mod.ts"; /** @@ -24,7 +23,7 @@ export interface ParseOptions { * * Schema class or its name. */ - schema?: string | Schema; + schema?: "core" | "default" | "failsafe" | "json" | "extended" | unknown; /** compatibility with JSON.parse behaviour. */ json?: boolean; /** function to call on warning messages. */ @@ -32,10 +31,28 @@ export interface ParseOptions { } /** - * Parses `content` as single YAML document. + * Parse `content` as single YAML document, and return it. * - * Returns a JavaScript object or throws `YAMLError` on error. - * By default, does not support regexps, functions and undefined. This method is safe for untrusted data. + * This function does not support regexps, functions, and undefined by default. + * This method is safe for parsing untrusted data. + * + * @example Usage + * ```ts + * import { parse } from "@std/yaml/parse"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const data = parse(` + * id: 1 + * name: Alice + * `); + * + * assertEquals(data, { id: 1, name: "Alice" }); + * ``` + * + * @throws {YAMLError} Throws error on invalid YAML. + * @param content YAML string to parse. + * @param options Parsing options. + * @returns Parsed document. */ export function parse(content: string, options?: ParseOptions): unknown { replaceSchemaNameWithSchemaClass(options); @@ -47,9 +64,45 @@ export function parse(content: string, options?: ParseOptions): unknown { * Same as `parse()`, but understands multi-document sources. * Applies iterator to each document if specified, or returns array of documents. * - * @example + * @example Usage * ```ts * import { parseAll } from "@std/yaml/parse"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * parseAll(` + * --- + * id: 1 + * name: Alice + * --- + * id: 2 + * name: Bob + * --- + * id: 3 + * name: Eve + * `, (doc: any) => { + * assertEquals(typeof doc, "object"); + * assertEquals(typeof doc.id, "number"); + * assertEquals(typeof doc.name, "string"); + * }); + * ``` + * + * @param content YAML string to parse. + * @param iterator Function to call on each document. + * @param options Parsing options. + */ +export function parseAll( + content: string, + iterator: (doc: unknown) => void, + options?: ParseOptions, +): void; +/** + * Same as `parse()`, but understands multi-document sources. + * Applies iterator to each document if specified, or returns array of documents. + * + * @example Usage + * ```ts + * import { parseAll } from "@std/yaml/parse"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const data = parseAll(` * --- @@ -62,19 +115,17 @@ export function parse(content: string, options?: ParseOptions): unknown { * id: 3 * name: Eve * `); - * console.log(data); - * // => [ { id: 1, name: "Alice" }, { id: 2, name: "Bob" }, { id: 3, name: "Eve" } ] + * assertEquals(data, [ { id: 1, name: "Alice" }, { id: 2, name: "Bob" }, { id: 3, name: "Eve" }]); * ``` + * + * @param content YAML string to parse. + * @param options Parsing options. + * @returns Array of parsed documents. */ -export function parseAll( - content: string, - iterator: CbFunction, - options?: ParseOptions, -): void; export function parseAll(content: string, options?: ParseOptions): unknown; export function parseAll( content: string, - iteratorOrOption?: CbFunction | ParseOptions, + iteratorOrOption?: ((doc: unknown) => void) | ParseOptions, options?: ParseOptions, ): unknown { if (typeof iteratorOrOption !== "function") { diff --git a/yaml/schema/mod.ts b/yaml/schema/mod.ts index 8061ff20f..2a5beb814 100644 --- a/yaml/schema/mod.ts +++ b/yaml/schema/mod.ts @@ -4,7 +4,6 @@ // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. // This module is browser compatible. -import type { Schema } from "../schema.ts"; import { CORE_SCHEMA } from "./core.ts"; import { DEFAULT_SCHEMA } from "./default.ts"; import { EXTENDED_SCHEMA } from "./extended.ts"; @@ -19,7 +18,9 @@ export { }; export function replaceSchemaNameWithSchemaClass( - options?: { schema?: string | Schema }, + options?: { + schema?: "core" | "default" | "failsafe" | "json" | "extended" | unknown; + }, ) { switch (options?.schema) { case "core": diff --git a/yaml/stringify.ts b/yaml/stringify.ts index dac681e11..9c281c095 100644 --- a/yaml/stringify.ts +++ b/yaml/stringify.ts @@ -4,7 +4,6 @@ // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. // This module is browser compatible. -import type { Schema } from "./schema.ts"; import { dump } from "./_dumper/dumper.ts"; import { replaceSchemaNameWithSchemaClass } from "./mod.ts"; @@ -33,7 +32,7 @@ export type DumpOptions = { * * Schema class or its name. */ - schema?: string | Schema; + schema?: "core" | "default" | "failsafe" | "json" | "extended" | unknown; /** * If true, sort keys when dumping YAML in ascending, ASCII character order. * If a function, use the function to sort the keys. (default: false) @@ -68,6 +67,21 @@ export type DumpOptions = { * Serializes `data` as a YAML document. * * You can disable exceptions by setting the skipInvalid option to true. + * + * @example Usage + * ```ts + * import { stringify } from "@std/yaml/stringify"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const data = { id: 1, name: "Alice" }; + * const yaml = stringify(data); + * + * assertEquals(yaml, "id: 1\nname: Alice\n"); + * ``` + * + * @param data The data to serialize. + * @param options The options for serialization. + * @returns A YAML string. */ export function stringify( data: unknown,