keep-a-changelog 2.6.0 → 2.6.2

package/esm/deps/jsr.io/@std/ini/0.225.2/ini_map.d.ts

@@ -0,0 +1,756 @@
+/** Options for providing formatting marks. */
+export interface FormattingOptions {
+    /** The character used to assign a value to a key; defaults to '='. */
+    assignment?: string;
+    /** Character(s) used to break lines in the config file; defaults to '\n'. Ignored on parse. */
+    lineBreak?: "\n" | "\r\n" | "\r";
+    /** Mark to use for setting comments; expects '#', ';', '//', defaults to '#' unless another mark is found. */
+    commentChar?: "#" | ";" | "//";
+    /** Use a plain assignment char or pad with spaces; defaults to false. Ignored on parse. */
+    pretty?: boolean;
+    /** Filter duplicate keys from INI string output; defaults to false to preserve data parity. */
+    deduplicate?: boolean;
+}
+/** Options for parsing INI strings. */
+export interface ParseOptions {
+    /** Provide custom parsing of the value in a key/value pair. */
+    reviver?: ReviverFunction;
+}
+/** Function for replacing JavaScript values with INI string values. */
+export type ReplacerFunction = (key: string, value: any, section?: string) => string;
+/** Function for replacing INI values with JavaScript values. */
+export type ReviverFunction = (key: string, value: any, section?: string) => any;
+/**
+ * Class implementation for fine control of INI data structures.
+ *
+ * @example Usage
+ * ```ts
+ * import { IniMap } from "@std/ini";
+ * import { assertEquals } from "@std/assert";
+ *
+ * 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 declare class IniMap {
+    #private;
+    /** Constructs a new `IniMap`.
+     *
+     * @example Usage
+     * ```ts
+     * import { IniMap } from "@std/ini";
+     * import { assertEquals } from "@std/assert";
+     *
+     * 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);
+    /**
+     * Gets the count of key/value pairs.
+     *
+     * @example Usage
+     * ```ts
+     * import { IniMap } from "@std/ini/ini-map";
+     * import { assertEquals } from "@std/assert";
+     *
+     * 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;
+    /**
+     * Gets the formatting options.
+     *
+     * @example Usage
+     * ```ts
+     * import { IniMap } from "@std/ini/ini-map";
+     * import { assertEquals } from "@std/assert";
+     *
+     * const iniMap = IniMap.from(`
+     * key0 = value0
+     * key1 = value1`);
+     *
+     * assertEquals(iniMap.formatting.pretty, true);
+     * ```
+     *
+     * @returns The formatting options
+     */
+    get formatting(): FormattingOptions;
+    /** Returns the comments in the INI.
+     *
+     * @example Usage
+     * ```ts
+     * import { IniMap } from "@std/ini/ini-map";
+     * import { assertEquals } from "@std/assert";
+     *
+     * 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
+     */
+    get comments(): Comments;
+    /**
+     * Clears a single section or the entire INI.
+     *
+     * @example Usage
+     * ```ts
+     * import { IniMap } from "@std/ini/ini-map";
+     * import { assertEquals } from "@std/assert";
+     *
+     * 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;
+    /**
+     * Deletes a global key in the INI.
+     *
+     * @example Usage
+     * ```ts
+     * import { IniMap } from "@std/ini/ini-map";
+     * import { assertEquals } from "@std/assert";
+     *
+     * 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.
+     */
+    delete(key: string): boolean;
+    /**
+     * Deletes a section key in the INI.
+     *
+     * @example Usage
+     * ```ts
+     * import { IniMap } from "@std/ini/ini-map";
+     * import { assertEquals } from "@std/assert";
+     *
+     * 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.
+     */
+    delete(section: string, key: string): boolean;
+    /**
+     * 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";
+     *
+     * 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";
+     *
+     * 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
+     * @returns The value for the key, or undefined if the key doesn't have a value
+     */
+    get(section: string, key: string): unknown;
+    /**
+     * 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
+     */
+    has(section: string, key: string): boolean;
+    /**
+     * 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";
+     *
+     * 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
+     */
+    set(key: string, value: unknown): this;
+    /**
+     * 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";
+     *
+     * 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
+     * @return The map object itself
+     */
+    set(section: string, key: string, value: unknown): this;
+    /**
+     * 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";
+     *
+     * 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<[
+        key: string,
+        value: unknown,
+        section?: string | undefined
+    ]>;
+    /**
+     * Convert this `IniMap` to a plain object.
+     *
+     * @example Usage
+     * ```ts
+     * import { IniMap } from "@std/ini/ini-map";
+     * import { assertEquals } from "@std/assert";
+     *
+     * 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<string, unknown | Record<string, unknown>>;
+    /**
+     * Convenience method for `JSON.stringify`.
+     *
+     * @example Usage
+     * ```ts
+     * import { IniMap } from "@std/ini/ini-map";
+     * import { assertEquals } from "@std/assert";
+     *
+     * 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<string, unknown | Record<string, unknown>>;
+    /**
+     * Convert this `IniMap` to an INI string.
+     *
+     * @example Usage
+     * ```ts
+     * import { IniMap } from "@std/ini/ini-map";
+     * import { assertEquals } from "@std/assert";
+     *
+     * 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
+     */
+    toString(replacer?: ReplacerFunction): string;
+    /**
+     * Parse an INI string in this `IniMap`.
+     *
+     * @example Usage
+     * ```ts
+     * import { IniMap } from "@std/ini/ini-map";
+     * import { assertEquals } from "@std/assert";
+     *
+     * 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
+     */
+    parse(text: string, reviver?: ReviverFunction): this;
+    /**
+     * Create an `IniMap` from an INI string.
+     *
+     * @example Usage
+     * ```ts
+     * import { IniMap } from "@std/ini/ini-map";
+     * import { assertEquals } from "@std/assert";
+     *
+     * 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}
+     */
+    static from(input: string, options?: ParseOptions & FormattingOptions): IniMap;
+    /**
+     * Create an `IniMap` from a plain object.
+     *
+     * @example Usage
+     * ```ts
+     * import { IniMap } from "@std/ini/ini-map";
+     * import { assertEquals } from "@std/assert";
+     *
+     * 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}
+     */
+    static from(input: Record<string, unknown>, formatting?: FormattingOptions): IniMap;
+}
+/** Manages comments within the INI file. */
+export interface Comments {
+    /**
+     * Clear all comments in the INI.
+     */
+    clear(): void;
+    /**
+     * 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.
+     *
+     * @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.
+     *
+     * @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.
+     *
+     * @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.
+     *
+     * @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.
+     *
+     * @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.
+     *
+     * @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.
+     *
+     * @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.
+     *
+     * @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.
+     *
+     * @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.
+     *
+     * @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.
+     *
+     * @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;
+}
+//# sourceMappingURL=ini_map.d.ts.map