From 299f764e75947222cdb26908f1cecd19797cedce Mon Sep 17 00:00:00 2001 From: Yoshiya Hinosawa Date: Mon, 10 Jun 2024 17:18:54 +0900 Subject: [PATCH 1/7] docs(ini): improve ini docs --- _tools/check_docs.ts | 1 + ini/ini_map.ts | 258 ++++++++++++++++++++++++++++++++++++------- ini/mod.ts | 10 +- ini/parse.ts | 13 ++- ini/stringify.ts | 8 +- 5 files changed, 244 insertions(+), 46 deletions(-) diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index 30bbec93ec7a..4dac5b7e050e 100644 --- a/_tools/check_docs.ts +++ b/_tools/check_docs.ts @@ -46,6 +46,7 @@ const ENTRY_POINTS = [ "../fs/mod.ts", "../html/mod.ts", "../http/mod.ts", + "../ini/mod.ts", "../internal/mod.ts", "../jsonc/mod.ts", "../media_types/mod.ts", diff --git a/ini/ini_map.ts b/ini/ini_map.ts index ba857a40a0f9..205fc09564f1 100644 --- a/ini/ini_map.ts +++ b/ini/ini_map.ts @@ -38,7 +38,28 @@ export type ReviverFunction = ( // deno-lint-ignore no-explicit-any ) => any; -/** Class implementation for fine control of INI data structures. */ +/** + * Class implementation for fine control of INI data structures. + * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const ini = new IniMap(); + * ini.set("section1", "keyA", 100) + * assertEquals(ini.toString(), `[section1] + * keyA=100`) + * + * ini.set('keyA', 25) + * assertEquals(ini.toObject(), { + * keyA: 25, + * section1: { + * keyA: 100, + * }, + * }); + * ``` + */ export class IniMap { #global = new Map(); #sections = new Map(); @@ -160,13 +181,37 @@ export class IniMap { #formatting: FormattingOptions; /** Constructs a new `IniMap`. + * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const ini = new IniMap(); + * ini.set("section1", "keyA", 100) + * assertEquals(ini.toString(), `[section1] + * keyA=100`) + * + * ini.set('keyA', 25) + * assertEquals(ini.toObject(), { + * keyA: 25, + * section1: { + * keyA: 100, + * }, + * }); + * ``` + * * @param formatting Optional formatting options when printing an INI file. */ constructor(formatting?: FormattingOptions) { this.#formatting = this.#cleanFormatting(formatting); } - /** Get the count of key/value pairs. */ + /** + * Gets the count of key/value pairs. + * + * @returns The number of key/value pairs. + */ get size(): number { let size = this.#global.size; for (const { map } of this.#sections.values()) { @@ -175,16 +220,28 @@ export class IniMap { return size; } + /** + * Gets the formatting options. + * + * @returns The formatting options + */ get formatting(): FormattingOptions { return this.#formatting; } - /** Manage comments in the INI. */ + /** Returns the comments in the INI. + * + * @returns The comments + */ get comments(): Comments { return this.#comments; } - /** Clear a single section or the entire INI. */ + /** + * Clears a single section or the entire INI. + * + * @param sectionName The section name to clear + */ clear(sectionName?: string): void { if (sectionName) { const section = this.#sections.get(sectionName); @@ -201,11 +258,18 @@ export class IniMap { } } - /** Delete a global key in the INI. + /** + * Deletes a global key in the INI. + * + * @param key The key to delete * @returns `true` if the key was deleted, `false` if not found. */ delete(key: string): boolean; - /** Delete a section key in the INI. + /** + * Deletes a section key in the INI. + * + * @param section The section + * @param key The key to delete * @returns `true` if the section was deleted, `false` if not found. */ delete(section: string, key: string): boolean; @@ -223,28 +287,59 @@ export class IniMap { return false; } - /** Get a value from a global key in the INI. */ + /** + * Gets a value from a global key in the INI. + * + * @param key The key to get + * @returns The value for the key, or undefined if the key doesn't have a value + */ get(key: string): unknown; - /** Get a value from a section key in the INI. */ + /** Get a value from a section key in the INI. + * + * @param section The section + * @param key The key to get + * @returns The value for the key, or undefined if the key doesn't have a value + */ get(section: string, key: string): unknown; get(keyOrSection: string, noneOrKey?: string): unknown { return this.#getValue(keyOrSection, noneOrKey)?.val; } - /** Check if a global key exists in the INI. */ + /** + * Check if a global key exists in the INI. + * + * @param key The key to check + * @returns `true` if the key has the value, `false` otherwise + */ has(key: string): boolean; - /** Check if a section key exists in the INI. */ + /** Check if a section key exists in the INI. + * + * @param section The section + * @param key The key to check + * @returns `true` if the key has the value in the given section, `false` otherwise + */ has(section: string, key: string): boolean; has(keyOrSection: string, noneOrKey?: string): boolean { return this.#getValue(keyOrSection, noneOrKey) !== undefined; } - /** Set the value of a global key in the INI. */ - // deno-lint-ignore no-explicit-any - set(key: string, value: any): this; - /** Set the value of a section key in the INI. */ - // deno-lint-ignore no-explicit-any - set(section: string, key: string, value: any): this; + /** + * Set the value of a global key in the INI. + * + * @param key The key to set the value + * @param value The value to set + * @returns The map object itself + */ + set(key: string, value: unknown): this; + /** + * Set the value of a section key in the INI. + * + * @param section The section + * @param key The key to set + * @param value The value to set + * @return The map object itself + */ + set(section: string, key: string, value: unknown): this; // deno-lint-ignore no-explicit-any set(keyOrSection: string, valueOrKey: any, value?: any): this { if (typeof valueOrKey === "string" && value !== undefined) { @@ -279,7 +374,11 @@ export class IniMap { return this; } - /** Iterate over each entry in the INI to retrieve key, value, and section. */ + /** + * Iterate over each entry in the INI to retrieve key, value, and section. + * + * @returns The iterator of entries + */ *entries(): Generator< [key: string, value: unknown, section?: string | undefined] > { @@ -415,7 +514,11 @@ export class IniMap { ); } - /** Convert this `IniMap` to a plain object. */ + /** + * Convert this `IniMap` to a plain object. + * + * @returns The object equivalent to this {@code IniMap} + */ toObject(): Record> { const obj: Record> = {}; @@ -448,12 +551,21 @@ export class IniMap { return obj; } - /** Convenience method for `JSON.stringify`. */ + /** + * Convenience method for `JSON.stringify`. + * + * @returns The object equivalent to this {@code IniMap} + */ toJSON(): Record> { return this.toObject(); } - /** Convert this `IniMap` to an INI string. */ + /** + * Convert this `IniMap` to an INI string. + * + * @param replacer The replacer + * @returns Ini string + */ toString(replacer?: ReplacerFunction): string { const replacerFunc: ReplacerFunction = typeof replacer === "function" ? replacer @@ -487,7 +599,13 @@ export class IniMap { }).join(this.#formatting?.lineBreak ?? "\n"); } - /** Parse an INI string in this `IniMap`. */ + /** + * Parse an INI string in this `IniMap`. + * + * @param text The text to parse + * @param reviver The reviver function + * @returns This {@code IniMap} object + */ parse(text: string, reviver?: ReviverFunction): this { if (typeof text !== "string") { throw new SyntaxError(`Unexpected token ${text} in INI at line 0`); @@ -589,15 +707,26 @@ export class IniMap { return this; } - /** Create an `IniMap` from an INI string. */ + /** + * Create an `IniMap` from an INI string. + * + * @param input The input string + * @param options The options to use + * @returns The parsed {@code IniMap} + */ static from( input: string, options?: ParseOptions & FormattingOptions, ): IniMap; - /** Create an `IniMap` from a plain object. */ + /** + * Create an `IniMap` from a plain object. + * + * @param input The input string + * @param formatting The options to use + * @returns The parsed {@code IniMap} + */ static from( - // deno-lint-ignore no-explicit-any - input: Record, + input: Record, formatting?: FormattingOptions, ): IniMap; static from( @@ -635,47 +764,100 @@ export class IniMap { /** Manages comments within the INI file. */ export interface Comments { - /** Clear all comments in the INI. */ + /** + * Clear all comments in the INI. + */ clear(): void; - /** Delete a comment at a specific line in the INI. + /** + * Delete a comment at a specific line in the INI. + * + * @param line The line to delete the comment at * @returns `true` if a comment was deleted, otherwise `false`. */ deleteAtLine(line: number): boolean; - /** Delete a comment before a global key in the INI. + /** + * Delete a comment before a global key in the INI. + * + * @param key The key to delete the comment at * @returns `true` if a comment was deleted, otherwise `false`. */ deleteAtKey(key: string): boolean; - /** Delete a comment before a section key in the INI. + /** + * Delete a comment before a section key in the INI. + * + * @param section The section + * @param key The key to delete the comment at * @returns `true` if a comment was deleted, otherwise `false`. */ deleteAtKey(section: string, key: string): boolean; - /** Delete a comment before a section line in the INI. + /** + * Delete a comment before a section line in the INI. + * + * @param section The section to delete the comment at * @returns `true` if a comment was deleted, otherwise `false`. */ deleteAtSection(section: string): boolean; - /** Get the comment text at a specific line in the INI. + /** + * Get the comment text at a specific line in the INI. + * + * @param line The line to get the comment at * @returns The comment text at the line or `undefined` if not found. */ getAtLine(line: number): string | undefined; - /** Get the comment text before a global key in the INI. + /** + * Get the comment text before a global key in the INI. + * + * @param key The key to get the comment at * @returns The comment text at the provided key or `undefined` if not found. */ getAtKey(key: string): string | undefined; - /** Get the comment text before a section key in the INI. + /** + * Get the comment text before a section key in the INI. + * + * @param section The section + * @param key The key to get the comment at * @returns The comment text at the provided section or `undefined` if not found. */ getAtKey(section: string, key: string): string | undefined; - /** Get the comment text before a section line in the INI. + /** + * Get the comment text before a section line in the INI. + * + * @param section The section to get the comment at * @returns The comment text at the provided section or `undefined` if not found. */ getAtSection(section: string): string | undefined; - /** Set a comment at a specific line in the INI. */ + /** + * Set a comment at a specific line in the INI. + * + * @param line The line to set the comment at + * @param text The comment to set + * @returns The comments object itself + */ setAtLine(line: number, text: string): Comments; - /** Set a comment before a global key in the INI. */ + /** + * Set a comment before a global key in the INI. + * + * @param key The key to set the text at + * @param text The comment to set + * @returns The comments object itself + */ setAtKey(key: string, text: string): Comments; - /** Set a comment before a section key in the INI. */ + /** + * Set a comment before a section key in the INI. + * + * @param section The section + * @param key The key to set the text at + * @param text The comment to set + * @returns The comments object itself + */ setAtKey(section: string, key: string, text: string): Comments; - /** Set a comment before a section line in the INI. */ + /** + * Set a comment before a section line in the INI. + * + * @param section The section to set the comment at + * @param text The comment to set + * @returns The comments object itself + */ setAtSection(section: string, text: string): Comments; } diff --git a/ini/mod.ts b/ini/mod.ts index 6047b96b90b7..49904e713321 100644 --- a/ini/mod.ts +++ b/ini/mod.ts @@ -1,5 +1,6 @@ // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. // This module is browser compatible. + /** * {@linkcode parse} and {@linkcode stringify} for handling * {@link https://en.wikipedia.org/wiki/INI_file | INI} encoded data, such as the @@ -10,8 +11,7 @@ * but will be preserved when using {@linkcode IniMap}. Multi-line values are not supported and will throw a syntax error. * White space padding and lines starting with '#', ';', or '//' will be treated as comments. * - * @example - * ```ts + * ```ts no-assert * import * as ini from "@std/ini"; * const iniFile = `# Example configuration file * Global Key=Some data here @@ -57,8 +57,7 @@ * Optionally, {@linkcode IniMap} may be used for finer INI handling. Using this class will permit preserving * comments, accessing values like a map, iterating over key/value/section entries, and more. * - * @example - * ```ts + * ```ts no-assert * import { IniMap } from "@std/ini"; * const ini = new IniMap(); * ini.set("section1", "keyA", 100) @@ -83,8 +82,7 @@ * The reviver and replacer APIs can be used to extend the behavior of IniMap, such as adding support * for duplicate keys as if they were arrays of values. * - * @example - * ```ts + * ```ts no-assert * import { IniMap } from "@std/ini"; * const iniFile = `# Example of key/value arrays * [section1] diff --git a/ini/parse.ts b/ini/parse.ts index 335d20883dc2..f7c18e28a3ed 100644 --- a/ini/parse.ts +++ b/ini/parse.ts @@ -2,7 +2,18 @@ // This module is browser compatible. import { IniMap, type ParseOptions } from "./ini_map.ts"; -/** Parse an INI config string into an object. Provide formatting options to override the default assignment operator. */ +/** + * Parse an INI config string into an object. Provide formatting options to override the default assignment operator. + * + * @example Usage + * ```ts + * // TODO + * ``` + * + * @param text The text to parse + * @param options The options to use + * @return The parsed object + */ export function parse( text: string, options?: ParseOptions, diff --git a/ini/stringify.ts b/ini/stringify.ts index a44a0e6087af..90492425ba7e 100644 --- a/ini/stringify.ts +++ b/ini/stringify.ts @@ -13,7 +13,13 @@ export interface StringifyOptions extends FormattingOptions { replacer?: ReplacerFunction; } -/** Compile an object into an INI config string. Provide formatting options to modify the output. */ +/** + * Compile an object into an INI config string. Provide formatting options to modify the output. + * + * @param object The object to stringify + * @param options The option to use + * @returns The INI string + */ export function stringify( // deno-lint-ignore no-explicit-any object: any, From 92fb5b380c36a840cfcc99005622d6e254233e33 Mon Sep 17 00:00:00 2001 From: Yoshiya Hinosawa Date: Mon, 10 Jun 2024 18:32:48 +0900 Subject: [PATCH 2/7] docs: add example of parse --- ini/mod.ts | 4 ++-- ini/parse.ts | 43 ++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 44 insertions(+), 3 deletions(-) diff --git a/ini/mod.ts b/ini/mod.ts index 49904e713321..76a4b759edf5 100644 --- a/ini/mod.ts +++ b/ini/mod.ts @@ -21,7 +21,7 @@ * Section Date=1977-05-25 * `; * const parsed = ini.parse(iniFile, { - * reviver: (key, value, section) => { + * reviver(key, value, section) { * if (section === "Section #1") { * if (key === "Section Value") return Number(value); * if (key === "Section Date") return new Date(value); @@ -38,7 +38,7 @@ * // } * * const text = ini.stringify(parsed, { - * replacer: (key, value, section) => { + * replacer(key, value, section) { * if (section === "Section #1" && key === "Section Date") { * return (value as Date).toISOString().split("T")[0]; * } diff --git a/ini/parse.ts b/ini/parse.ts index f7c18e28a3ed..f52744be157f 100644 --- a/ini/parse.ts +++ b/ini/parse.ts @@ -7,7 +7,48 @@ import { IniMap, type ParseOptions } from "./ini_map.ts"; * * @example Usage * ```ts - * // TODO + * import { parse } from "@std/ini/parse"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const parsed = parse(` + * key = value + * + * [section 1] + * foo = Hello + * baz = World + * `); + * + * assertEquals(parsed, { key: "value", "section 1": { foo: "Hello", baz: "World" } }) + * ``` + * + * @example Using custom reviver + * ```ts + * import { parse } from "@std/ini/parse"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const parsed = parse(` + * [section Foo] + * date = 2012-10-10 + * amount = 12345 + * `, { + * reviver(key, value, section) { + * if (section === "section Foo") { + * if (key === "date") { + * return new Date(value); + * } else if (key === "amount") { + * return +value; + * } + * } + * return value; + * } + * }); + * + * assertEquals(parsed, { + * "section Foo": { + * date: new Date("2012-10-10"), + * amount: 12345, + * } + * }) * ``` * * @param text The text to parse From 34a3e35adbe5819f78d94d0925f1f59459831bf2 Mon Sep 17 00:00:00 2001 From: Yoshiya Hinosawa Date: Mon, 10 Jun 2024 19:12:26 +0900 Subject: [PATCH 3/7] docs: add stringify examples --- ini/stringify.ts | 51 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/ini/stringify.ts b/ini/stringify.ts index 90492425ba7e..ed48bbbc40c4 100644 --- a/ini/stringify.ts +++ b/ini/stringify.ts @@ -16,6 +16,57 @@ export interface StringifyOptions extends FormattingOptions { /** * Compile an object into an INI config string. Provide formatting options to modify the output. * + * @example Usage + * ```ts + * import { stringify } from "@std/ini/stringify"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const str = stringify({ + * key1: "value1", + * key2: "value2", + * section1: { + * foo: "bar", + * }, + * section2: { + * hello: "world", + * }, + * }); + * + * assertEquals(str, `key1=value1 + * key2=value2 + * [section1] + * foo=bar + * [section2] + * hello=world`); + * ``` + * + * @example Using replacer option + * ```ts + * import { stringify } from "@std/ini/stringify"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const str = stringify({ + * "section X": { + * date: new Date(), + * }, + * "section Y": { + * name: "John" + * } + * }, { + * replacer(key, value, section) { + * if (section === "section X" && key === "date") { + * return value.toISOString().slice(0, 10); + * } + * return value; + * }, + * }); + * + * assertEquals(str, `[section X] + * date=2024-06-10 + * [section Y] + * name=John`); + * ``` + * * @param object The object to stringify * @param options The option to use * @returns The INI string From da08ab231b3a8f7f30dcb491caac87c681cfe25e Mon Sep 17 00:00:00 2001 From: Yoshiya Hinosawa Date: Mon, 10 Jun 2024 19:54:03 +0900 Subject: [PATCH 4/7] add IniMap examples --- ini/ini_map.ts | 276 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 276 insertions(+) diff --git a/ini/ini_map.ts b/ini/ini_map.ts index 205fc09564f1..ef357575d839 100644 --- a/ini/ini_map.ts +++ b/ini/ini_map.ts @@ -210,6 +210,26 @@ export class IniMap { /** * Gets the count of key/value pairs. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from(` + * key0 = value0 + * key1 = value1 + * + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg + * + * [section 2] + * name = John`); + * + * assertEquals(iniMap.size, 6); // It has 6 keys in total + * ``` + * * @returns The number of key/value pairs. */ get size(): number { @@ -223,6 +243,18 @@ export class IniMap { /** * Gets the formatting options. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from(` + * key0 = value0 + * key1 = value1`); + * + * assertEquals(iniMap.formatting.pretty, true); + * ``` + * * @returns The formatting options */ get formatting(): FormattingOptions { @@ -230,6 +262,26 @@ export class IniMap { } /** Returns the comments in the INI. + * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from(` + * // Hey + * key0 = value0 + * key1 = value1 + * // Hello + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg`); + * + * assertEquals(iniMap.comments.getAtLine(2), "// Hey") + * assertEquals(iniMap.comments.getAtLine(5), "// Hello") + * assertEquals(iniMap.comments.getAtSection("section 1"), "// Hello") + * ``` * * @returns The comments */ @@ -240,6 +292,38 @@ export class IniMap { /** * Clears a single section or the entire INI. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from(` + * key0 = value0 + * key1 = value1 + * + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg + * + * [section 2] + * name = John`); + * + * iniMap.clear("section 1"); + * + * assertEquals(iniMap.toObject(), { + * key0: "value0", + * key1: "value1", + * "section 2": { + * name: "John", + * }, + * }); + * + * iniMap.clear(); // Clears all + * + * assertEquals(iniMap.toObject(), {}); + * ``` + * * @param sectionName The section name to clear */ clear(sectionName?: string): void { @@ -261,6 +345,32 @@ export class IniMap { /** * Deletes a global key in the INI. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from(` + * key0 = value0 + * key1 = value1 + * + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg`); + * + * iniMap.delete("key0"); + * + * assertEquals(iniMap.toObject(), { + * key1: "value1", + * "section 1": { + * foo: "Spam", + * bar: "Ham", + * baz: "Egg", + * }, + * }); + * ``` + * * @param key The key to delete * @returns `true` if the key was deleted, `false` if not found. */ @@ -268,6 +378,38 @@ export class IniMap { /** * Deletes a section key in the INI. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from(` + * key0 = value0 + * key1 = value1 + * + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg + * + * [section 2] + * name = John`); + * + * iniMap.delete("section 1", "foo"); + * iniMap.delete("section 2", "name"); + * + * assertEquals(iniMap.toObject(), { + * key0: "value0", + * key1: "value1", + * "section 1": { + * bar: "Ham", + * baz: "Egg", + * }, + * "section 2": { + * }, + * }); + * ``` + * * @param section The section * @param key The key to delete * @returns `true` if the section was deleted, `false` if not found. @@ -290,11 +432,48 @@ export class IniMap { /** * Gets a value from a global key in the INI. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from(` + * key0 = value0 + * key1 = value1 + * + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg`); + * + * assertEquals(iniMap.get("key0", "value0")); + * assertEquals(iniMap.get("key1", "value1")); + * ``` + * * @param key The key to get * @returns The value for the key, or undefined if the key doesn't have a value */ get(key: string): unknown; /** Get a value from a section key in the INI. + * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from(` + * key0 = value0 + * key1 = value1 + * + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg`); + * + * assertEquals(iniMap.get("section 1", "foo"), "Spam"); + * assertEquals(iniMap.get("section 1", "bar"), "Ham"); + * assertEquals(iniMap.get("section 1", "baz"), "Egg"); + * ``` * * @param section The section * @param key The key to get @@ -308,12 +487,49 @@ export class IniMap { /** * Check if a global key exists in the INI. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assert, assertFalse } from "@std/assert"; + * + * const iniMap = IniMap.from(` + * key0 = value0 + * key1 = value1 + * + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg`); + * + * assert(iniMap.has("key0")); + * assert(iniMap.has("key1")); + * assertFalse(iniMap.has("key2")); + * ``` + * * @param key The key to check * @returns `true` if the key has the value, `false` otherwise */ has(key: string): boolean; /** Check if a section key exists in the INI. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assert, assertFalse } from "@std/assert"; + * + * const iniMap = IniMap.from(` + * key0 = value0 + * key1 = value1 + * + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg`); + * + * assert(iniMap.has("section 1", "foo")); + * assert(iniMap.has("section 1", "bar")); + * assertFalse(iniMap.has("section 1", "hello")); + * ``` * @param section The section * @param key The key to check * @returns `true` if the key has the value in the given section, `false` otherwise @@ -326,6 +542,35 @@ export class IniMap { /** * Set the value of a global key in the INI. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from(` + * key0 = value0 + * key1 = value1 + * + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg`); + * + * iniMap.set("key1", "hello"); + * iniMap.set("hi", "hey"); + * + * assertEquals(iniMap.toObject(), { + * key0: "value0", + * key1: "hello", + * hi: "hey", + * "section 1": { + * foo: "Spam", + * bar: "Ham", + * baz: "Egg", + * }, + * }); + * ``` + * * @param key The key to set the value * @param value The value to set * @returns The map object itself @@ -334,6 +579,37 @@ export class IniMap { /** * Set the value of a section key in the INI. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from(` + * key0 = value0 + * key1 = value1 + * + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg`); + * + * iniMap.set("section 1", "foo", "World"); + * iniMap.set("section X", "name", "John"); + * + * assertEquals(iniMap.toObject(), { + * key0: "value0", + * key1: "value1", + * "section 1": { + * foo: "World", + * bar: "Ham", + * baz: "Egg", + * }, + * "section X": { + * name: "John", + * } + * }); + * ``` + * * @param section The section * @param key The key to set * @param value The value to set From 587c4ad82edbd867668337e5693ce510be1a3a50 Mon Sep 17 00:00:00 2001 From: Yoshiya Hinosawa Date: Mon, 10 Jun 2024 20:03:19 +0900 Subject: [PATCH 5/7] add examples --- ini/ini_map.ts | 174 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) diff --git a/ini/ini_map.ts b/ini/ini_map.ts index ef357575d839..1e480c23ccd3 100644 --- a/ini/ini_map.ts +++ b/ini/ini_map.ts @@ -653,6 +653,29 @@ export class IniMap { /** * Iterate over each entry in the INI to retrieve key, value, and section. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from(` + * key0 = value0 + * key1 = value1 + * + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg`); + * + * assertEquals([...iniMap.entries()], [ + * ["key0", "value0"], + * ["key1", "value1"], + * ["foo", "Spam", "section 1"], + * ["bar", "Ham", "section 1"], + * ["baz", "Egg", "section 1"] + * ]); + * ``` + * * @returns The iterator of entries */ *entries(): Generator< @@ -793,6 +816,31 @@ export class IniMap { /** * Convert this `IniMap` to a plain object. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from(` + * key0 = value0 + * key1 = value1 + * + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg`); + * + * assertEquals(iniMap.toObject(), { + * key0: "value0", + * key1: "value1", + * "section 1": { + * foo: "Spam", + * bar: "Ham", + * baz: "Egg", + * }, + * }); + * ``` + * * @returns The object equivalent to this {@code IniMap} */ toObject(): Record> { @@ -830,6 +878,31 @@ export class IniMap { /** * Convenience method for `JSON.stringify`. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from(` + * key0 = value0 + * key1 = value1 + * + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg`); + * + * assertEquals(iniMap.toJSON(), { + * key0: "value0", + * key1: "value1", + * "section 1": { + * foo: "Spam", + * bar: "Ham", + * baz: "Egg", + * }, + * }); + * ``` + * * @returns The object equivalent to this {@code IniMap} */ toJSON(): Record> { @@ -839,6 +912,33 @@ export class IniMap { /** * Convert this `IniMap` to an INI string. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from(` + * // Hey + * key0 = value0 + * key1 = value1 + * // Hello + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg`); + * + * iniMap.set("section 1", "foo", "Bacon"); + * + * assertEquals(iniMap.toString(), ` + * // Hey + * key0 = value0 + * key1 = value1 + * // Hello + * [section 1] + * foo = Bacon + * bar = Ham + * baz = Egg`) + * ``` * @param replacer The replacer * @returns Ini string */ @@ -878,6 +978,33 @@ export class IniMap { /** * Parse an INI string in this `IniMap`. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = new IniMap(); + * + * iniMap.parse(` + * key0 = value0 + * key1 = value1 + * + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg`); + * + * assertEquals(iniMap.toObject(), { + * key0: "value0", + * key1: "value1", + * "section 1": { + * foo: "Spam", + * bar: "Ham", + * baz: "Egg", + * }, + * }); + * ``` + * * @param text The text to parse * @param reviver The reviver function * @returns This {@code IniMap} object @@ -986,6 +1113,31 @@ export class IniMap { /** * Create an `IniMap` from an INI string. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from(` + * key0 = value0 + * key1 = value1 + * + * [section 1] + * foo = Spam + * bar = Ham + * baz = Egg`); + * + * assertEquals(iniMap.toObject(), { + * key0: "value0", + * key1: "value1", + * "section 1": { + * foo: "Spam", + * bar: "Ham", + * baz: "Egg", + * }, + * }); + * ``` + * * @param input The input string * @param options The options to use * @returns The parsed {@code IniMap} @@ -997,6 +1149,28 @@ export class IniMap { /** * Create an `IniMap` from a plain object. * + * @example Usage + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * const iniMap = IniMap.from({ + * key0: "value0", + * key1: "value1", + * "section 1": { + * foo: "Spam", + * bar: "Ham", + * baz: "Egg", + * }, + * }); + * + * assertEquals(iniMap.toString(), `key0=value0 + * key1=value1 + * [section 1] + * foo=Spam + * bar=Ham + * baz=Egg`); + * ``` * @param input The input string * @param formatting The options to use * @returns The parsed {@code IniMap} From a5b757915aa4108e7be16d3633285551794361b2 Mon Sep 17 00:00:00 2001 From: Yoshiya Hinosawa Date: Mon, 10 Jun 2024 20:08:41 +0900 Subject: [PATCH 6/7] fix --- ini/ini_map.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ini/ini_map.ts b/ini/ini_map.ts index 1e480c23ccd3..f48707e89d06 100644 --- a/ini/ini_map.ts +++ b/ini/ini_map.ts @@ -446,8 +446,8 @@ export class IniMap { * bar = Ham * baz = Egg`); * - * assertEquals(iniMap.get("key0", "value0")); - * assertEquals(iniMap.get("key1", "value1")); + * assertEquals(iniMap.get("key0"), "value0"); + * assertEquals(iniMap.get("key1"), "value1"); * ``` * * @param key The key to get From 97449ff5ab1162e496b752a294e93927ae9afc87 Mon Sep 17 00:00:00 2001 From: Yoshiya Hinosawa Date: Tue, 11 Jun 2024 15:55:00 +0900 Subject: [PATCH 7/7] use assertions --- ini/mod.ts | 80 ++++++++++++++++++++++++------------------------ ini/stringify.ts | 2 +- 2 files changed, 41 insertions(+), 41 deletions(-) diff --git a/ini/mod.ts b/ini/mod.ts index 76a4b759edf5..dfd90bc63377 100644 --- a/ini/mod.ts +++ b/ini/mod.ts @@ -11,15 +11,17 @@ * but will be preserved when using {@linkcode IniMap}. Multi-line values are not supported and will throw a syntax error. * White space padding and lines starting with '#', ';', or '//' will be treated as comments. * - * ```ts no-assert + * ```ts * import * as ini from "@std/ini"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const iniFile = `# Example configuration file * Global Key=Some data here * * [Section #1] * Section Value=42 - * Section Date=1977-05-25 - * `; + * Section Date=1977-05-25`; + * * const parsed = ini.parse(iniFile, { * reviver(key, value, section) { * if (section === "Section #1") { @@ -29,13 +31,14 @@ * return value; * }, * }); - * console.log(parsed); * - * // => - * // { - * // "Global Key": "Some data here", - * // "Section #1": { "Section Value": 42, "Section Date": 1977-05-25T00:00:00.000Z } - * // } + * assertEquals(parsed, { + * "Global Key": "Some data here", + * "Section #1": { + * "Section Value": 42, + * "Section Date": new Date("1977-05-25T00:00:00.000Z"), + * }, + * }); * * const text = ini.stringify(parsed, { * replacer(key, value, section) { @@ -45,51 +48,47 @@ * return value; * }, * }); - * console.log(text); * - * // => - * // Global Key=Some data here - * // [Section #1] - * // Section Value=42 - * // Section Date=1977-05-25 + * assertEquals(text, `Global Key=Some data here + * [Section #1] + * Section Value=42 + * Section Date=1977-05-25`); * ``` * * Optionally, {@linkcode IniMap} may be used for finer INI handling. Using this class will permit preserving * comments, accessing values like a map, iterating over key/value/section entries, and more. * - * ```ts no-assert - * import { IniMap } from "@std/ini"; - * const ini = new IniMap(); - * ini.set("section1", "keyA", 100) - * console.log(ini.toString()) + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * // => - * // [section1] - * // keyA=100 + * const ini = new IniMap(); + * ini.set("section1", "keyA", 100); + * assertEquals(ini.toString(), `[section1] + * keyA=100`); * * ini.set('keyA', 25) - * console.log(ini.toObject()) - * - * // => - * // { - * // keyA: 25, - * // section1: { - * // keyA: 100 - * // } - * // } + * assertEquals(ini.toObject(), { + * keyA: 25, + * section1: { + * keyA: 100 + * } + * }); * ``` * * The reviver and replacer APIs can be used to extend the behavior of IniMap, such as adding support * for duplicate keys as if they were arrays of values. * - * ```ts no-assert - * import { IniMap } from "@std/ini"; + * ```ts + * import { IniMap } from "@std/ini/ini-map"; + * import { assertEquals } from "@std/assert/assert-equals"; + * * const iniFile = `# Example of key/value arrays * [section1] * key1=This key * key1=is non-standard - * key1=but can be captured! - * `; + * key1=but can be captured!`; + * * const ini = new IniMap({ assignment: "=", deduplicate: true }); * ini.parse(iniFile, (key, value, section) => { * if (section) { @@ -105,9 +104,11 @@ * } * return value; * }); - * console.log(ini.get("section1", "key1")); * - * // => [ "This key", "is non-standard", "but can be captured!" ] + * assertEquals( + * ini.get("section1", "key1"), + * ["This key", "is non-standard", "but can be captured!"] + * ); * * const result = ini.toString((key, value) => { * if (Array.isArray(value)) { @@ -117,9 +118,8 @@ * } * return value; * }); - * console.log(result === iniFile); * - * // => true + * assertEquals(result, iniFile); * ``` * * @module diff --git a/ini/stringify.ts b/ini/stringify.ts index ed48bbbc40c4..2acbce28a280 100644 --- a/ini/stringify.ts +++ b/ini/stringify.ts @@ -47,7 +47,7 @@ export interface StringifyOptions extends FormattingOptions { * * const str = stringify({ * "section X": { - * date: new Date(), + * date: new Date("2024-06-10"), * }, * "section Y": { * name: "John"