diff --git a/crypto/crypto.ts b/crypto/crypto.ts index 398d202d2c22..98b43334e39c 100644 --- a/crypto/crypto.ts +++ b/crypto/crypto.ts @@ -57,7 +57,6 @@ * - `MD4` (collidable and length-extendable) * - `MD5` (collidable and length-extendable) * - `SHA-1` (collidable and length-extendable) - * ``` * * @example * ```ts diff --git a/front_matter/any.ts b/front_matter/any.ts index 84e354aa2acd..a0f55477966b 100644 --- a/front_matter/any.ts +++ b/front_matter/any.ts @@ -8,6 +8,28 @@ import { import { parse as parseYAML } from "../yaml/parse.ts"; import { parse as parseTOML } from "../toml/parse.ts"; +/** + * Extracts and parses {@link https://yaml.org | YAML}, {@link https://toml.io | + * TOML}, or {@link https://www.json.org/ | JSON} from the metadata of front + * matter content, depending on the format. + * + * @example + * ```ts + * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/any.ts"; + * + * const output = `---json + * { + * "title": "Three dashes marks the spot" + * } + * --- + * Hello, world!`; + * const result = extract(output); + * + * result.frontMatter; // '{\n "title": "Three dashes marks the spot"\n}' + * result.body; // "Hello, world!" + * result.attrs; // { title: "Three dashes marks the spot" } + * ``` + */ export const extract: Extractor = createExtractor({ yaml: parseYAML as Parser, toml: parseTOML as Parser, diff --git a/front_matter/json.ts b/front_matter/json.ts index 3849f55c553a..5f475e4ddadb 100644 --- a/front_matter/json.ts +++ b/front_matter/json.ts @@ -6,6 +6,27 @@ import { type Parser, } from "./create_extractor.ts"; +/** + * Extracts and parses {@link https://www.json.org/ | JSON } from the metadata + * of front matter content. + * + * @example + * ```ts + * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/json.ts"; + * + * const output = `---json + * { + * "title": "Three dashes marks the spot" + * } + * --- + * Hello, world!`; + * const result = extract(output); + * + * result.frontMatter; // '{\n "title": "Three dashes marks the spot"\n}' + * result.body; // "Hello, world!" + * result.attrs; // { title: "Three dashes marks the spot" } + * ``` + */ export const extract: Extractor = createExtractor({ json: JSON.parse as Parser, }); diff --git a/front_matter/mod.ts b/front_matter/mod.ts index 9e5585d8f5e9..167278877e2d 100644 --- a/front_matter/mod.ts +++ b/front_matter/mod.ts @@ -1,117 +1,62 @@ +// deno-lint-ignore-file no-unused-vars // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. // Copyright (c) Jason Campbell. MIT license /** * Extracts * {@link https://daily-dev-tips.com/posts/what-exactly-is-frontmatter/ | front matter} - * from strings. - * - * {@linkcode createExtractor} and {@linkcode test} functions - * to handle many forms of front matter. - * - * Adapted from + * from strings. Adapted from * {@link https://github.com/jxson/front-matter/blob/36f139ef797bd9e5196a9ede03ef481d7fbca18e/index.js | jxson/front-matter}. * - * Supported formats: - * - * - [`YAML`](./front_matter/yaml.ts) - * - [`TOML`](./front_matter/toml.ts) - * - [`JSON`](./front_matter/json.ts) + * ## Supported formats * - * ### Basic usage - * - * example.md - * - * ```markdown - * --- - * module: front_matter - * tags: - * - yaml - * - toml - * - json - * --- - * - * deno is awesome - * ``` - * - * example.ts + * ### JSON * * ```ts - * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/any.ts"; * import { test } from "https://deno.land/std@$STD_VERSION/front_matter/test.ts"; + * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/json.ts"; * - * const str = await Deno.readTextFile("./example.md"); + * const str = "---json\n{\"and\": \"this\"}\n---\ndeno is awesome"; + * const result = extract(str); * - * if (test(str)) { - * console.log(extract(str)); - * } else { - * console.log("document doesn't contain front matter"); - * } + * test(str); // true + * result.frontMatter; // "{\"and\": \"this\"}" + * result.body; // "deno is awesome" + * result.attrs; // { and: "this" } * ``` * - * ```sh - * $ deno run ./example.ts + * {@linkcode extractJson | extract} and {@linkcode test} support the following delimiters. + * + * ```markdown + * ---json * { - * frontMatter: "module: front_matter\ntags:\n - yaml\n - toml\n - json", - * body: "deno is awesome", - * attrs: { module: "front_matter", tags: [ "yaml", "toml", "json" ] } + * "and": "this" * } + * --- * ``` * - * The above example recognizes any of the supported formats, extracts metadata and - * parses accordingly. Please note that in this case both the [YAML](#yaml) and - * [TOML](#toml) parsers will be imported as dependencies. - * - * If you need only one specific format then you can import the file named - * respectively from [here](./front_matter). - * - * ### Advanced usage - * - * ```ts - * import { test as _test } from "https://deno.land/std@$STD_VERSION/front_matter/test.ts"; - * import { - * createExtractor, - * Parser, - * } from "https://deno.land/std@$STD_VERSION/front_matter/mod.ts"; - * import { parse } from "https://deno.land/std@$STD_VERSION/toml/parse.ts"; - * - * const extract = createExtractor({ - * "toml": parse as Parser, - * "json": JSON.parse as Parser, - * }); - * - * export function test(str: string): boolean { - * return _test(str, ["toml", "json"]); + * ```markdown + * { + * "is": "JSON" * } * ``` * - * In this setup `extract()` and `test()` will work with TOML and JSON and only. - * This way the YAML parser is not loaded if not needed. You can cherry-pick which - * combination of formats are you supporting based on your needs. - * - * ### Delimiters + * ### TOML * - * #### YAML - * - * ```markdown - * --- - * these: are - * --- - * ``` + * ```ts + * import { test } from "https://deno.land/std@$STD_VERSION/front_matter/test.ts"; + * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/toml.ts"; * - * ```markdown - * ---yaml - * all: recognized - * --- - * ``` + * const str = "---toml\nmodule = 'front_matter'\n---\ndeno is awesome"; + * const result = extract(str); * - * ```markdown - * = yaml = - * as: yaml - * = yaml = + * test(str); // true + * result.frontMatter; // "module = 'front_matter'" + * result.body; // "deno is awesome" + * result.attrs; // { module: "front_matter" } * ``` * - * #### TOML + * {@linkcode extractToml | extract} and {@linkcode test} support the following delimiters. * * ```markdown * ---toml @@ -133,24 +78,46 @@ * +++ * ``` * - * #### JSON + * ### YAML + * + * ```ts + * import { test } from "https://deno.land/std@$STD_VERSION/front_matter/test.ts"; + * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/yaml.ts"; + * + * const str = "---yaml\nmodule: front_matter\n---\ndeno is awesome"; + * const result = extract(str); + * + * test(str); // true + * result.frontMatter; // "module: front_matter" + * result.body; // "deno is awesome" + * result.attrs; // { module: "front_matter" } + * ``` + * + * {@linkcode extractYaml | extract} and {@linkcode test} support the following delimiters. + * + * ```front_matter + * --- + * these: are + * --- + * ``` * * ```markdown - * ---json - * { - * "and": "this" - * } + * ---yaml + * all: recognized * --- * ``` * * ```markdown - * { - * "is": "JSON" - * } + * = yaml = + * as: yaml + * = yaml = * ``` * * @module */ +import { extract as extractJson } from "./json.ts"; +import { extract as extractToml } from "./toml.ts"; +import { extract as extractYaml } from "./yaml.ts"; export * from "./create_extractor.ts"; export * from "./test.ts"; diff --git a/front_matter/test.ts b/front_matter/test.ts index ff2cad27f6d3..76b4bd3eb635 100644 --- a/front_matter/test.ts +++ b/front_matter/test.ts @@ -2,7 +2,7 @@ import { EXTRACT_REGEXP_MAP } from "./_formats.ts"; -type Format = "yaml" | "toml" | "json" | "unknown"; +export type Format = "yaml" | "toml" | "json" | "unknown"; /** * Tests if a string has valid front matter. Supports YAML, TOML and JSON. @@ -11,19 +11,17 @@ type Format = "yaml" | "toml" | "json" | "unknown"; * @param formats A list of formats to test for. Defaults to all supported formats. * * ```ts - * import { test } from "https://deno.land/std@$STD_VERSION/front_matter/mod.ts"; - * import { assert } from "https://deno.land/std@$STD_VERSION/assert/assert.ts"; + * import { test } from "https://deno.land/std@$STD_VERSION/front_matter/test.ts"; * - * assert(test("---\ntitle: Three dashes marks the spot\n---\n")); - * assert(test("---toml\ntitle = 'Three dashes followed by format marks the spot'\n---\n")); - * assert(test("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\n")); - * - * assert(!test("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\n", ["yaml"])); + * test("---\ntitle: Three dashes marks the spot\n---\n"); // true + * test("---toml\ntitle = 'Three dashes followed by format marks the spot'\n---\n"); // true + * test("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\n"); // true + * test("---json\n{\"title\": \"Three dashes followed by format marks the spot\"}\n---\n", ["yaml"]); // false * ``` */ export function test( str: string, - formats?: ("yaml" | "toml" | "json" | "unknown")[], + formats?: Format[], ): boolean { if (!formats) { formats = Object.keys(EXTRACT_REGEXP_MAP) as Format[]; diff --git a/front_matter/toml.ts b/front_matter/toml.ts index 4cb50d018ad9..fa293873ee24 100644 --- a/front_matter/toml.ts +++ b/front_matter/toml.ts @@ -7,6 +7,25 @@ import { } from "./create_extractor.ts"; import { parse } from "../toml/parse.ts"; +/** + * Extracts and parses {@link https://toml.io | TOML} from the metadata of + * front matter content. + * + * @example + * ```ts + * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/toml.ts"; + * + * const output = `---toml + * title = "Three dashes marks the spot" + * --- + * Hello, world!`; + * const result = extract(output); + * + * result.frontMatter; // 'title = "Three dashes marks the spot"' + * result.body; // "Hello, world!" + * result.attrs; // { title: "Three dashes marks the spot" } + * ``` + */ export const extract: Extractor = createExtractor({ ["toml"]: parse as Parser, }); diff --git a/front_matter/yaml.ts b/front_matter/yaml.ts index 847f4b719fd6..bac071175fc1 100644 --- a/front_matter/yaml.ts +++ b/front_matter/yaml.ts @@ -7,6 +7,25 @@ import { } from "./create_extractor.ts"; import { parse } from "../yaml/parse.ts"; +/** + * Extracts and parses {@link https://yaml.org | YAML} from the metadata of + * front matter content. + * + * @example + * ```ts + * import { extract } from "https://deno.land/std@$STD_VERSION/front_matter/yaml.ts"; + * + * const output = `---yaml + * title: Three dashes marks the spot + * --- + * Hello, world!`; + * const result = extract(output); + * + * result.frontMatter; // 'title: Three dashes marks the spot' + * result.body; // "Hello, world!" + * result.attrs; // { title: "Three dashes marks the spot" } + * ``` + */ export const extract: Extractor = createExtractor({ ["yaml"]: parse as Parser, });