keep-a-changelog 2.5.3 → 2.6.0

package/esm/std/ini/_ini_map.js

@@ -0,0 +1,371 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+// This module is browser compatible.
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _IniMap_instances, _IniMap_global, _IniMap_sections, _IniMap_lines, _IniMap_formatting, _IniMap_getOrCreateSection, _IniMap_appendValue, _IniMap_appendOrDeleteLine, _IniMap_readTextLines, _IniMap_cleanFormatting;
+const ASSIGNMENT_MARK = "=";
+function trimQuotes(value) {
+    if (value.startsWith('"') && value.endsWith('"')) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+const NON_WHITESPACE_REGEXP = /\S/;
+/**
+ * Class implementation for fine control of INI data structures.
+ */
+// deno-lint-ignore no-explicit-any
+export class IniMap {
+    /** Constructs a new `IniMap`.
+     *
+     * @param formatting Optional formatting options when printing an INI file.
+     */
+    constructor(formatting) {
+        _IniMap_instances.add(this);
+        _IniMap_global.set(this, new Map());
+        _IniMap_sections.set(this, new Map());
+        _IniMap_lines.set(this, []);
+        _IniMap_formatting.set(this, void 0);
+        __classPrivateFieldSet(this, _IniMap_formatting, __classPrivateFieldGet(this, _IniMap_instances, "m", _IniMap_cleanFormatting).call(this, formatting), "f");
+    }
+    // deno-lint-ignore no-explicit-any
+    set(keyOrSection, valueOrKey, value) {
+        if (typeof valueOrKey === "string" && value !== undefined) {
+            const section = __classPrivateFieldGet(this, _IniMap_instances, "m", _IniMap_getOrCreateSection).call(this, keyOrSection);
+            const exists = section.map.get(valueOrKey);
+            if (exists) {
+                exists.val = value;
+            }
+            else {
+                section.end += 1;
+                const lineValue = {
+                    type: "value",
+                    num: section.end,
+                    sec: section.sec,
+                    key: valueOrKey,
+                    val: value,
+                };
+                __classPrivateFieldGet(this, _IniMap_instances, "m", _IniMap_appendValue).call(this, lineValue);
+                section.map.set(valueOrKey, lineValue);
+            }
+        }
+        else {
+            const lineValue = {
+                type: "value",
+                num: 0,
+                key: keyOrSection,
+                val: valueOrKey,
+            };
+            __classPrivateFieldGet(this, _IniMap_instances, "m", _IniMap_appendValue).call(this, lineValue);
+            __classPrivateFieldGet(this, _IniMap_global, "f").set(keyOrSection, lineValue);
+        }
+        return this;
+    }
+    /**
+     * Convert this `IniMap` to a plain object.
+     *
+     * @returns The object equivalent to this {@code IniMap}
+     */
+    toObject() {
+        const obj = {};
+        for (const { key, val } of __classPrivateFieldGet(this, _IniMap_global, "f").values()) {
+            Object.defineProperty(obj, key, {
+                value: val,
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+        }
+        for (const { sec, map } of __classPrivateFieldGet(this, _IniMap_sections, "f").values()) {
+            const section = {};
+            Object.defineProperty(obj, sec, {
+                value: section,
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+            for (const { key, val } of map.values()) {
+                Object.defineProperty(section, key, {
+                    value: val,
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                });
+            }
+        }
+        return obj;
+    }
+    /**
+     * Convert this `IniMap` to an INI string.
+     *
+     * @param replacer The replacer
+     * @returns Ini string
+     */
+    toString(replacer) {
+        const replacerFunc = typeof replacer === "function"
+            ? replacer
+            : (_key, value, _section) => `${value}`;
+        const pretty = __classPrivateFieldGet(this, _IniMap_formatting, "f")?.pretty ?? false;
+        const assignment = pretty ? ` ${ASSIGNMENT_MARK} ` : ASSIGNMENT_MARK;
+        const lines = __classPrivateFieldGet(this, _IniMap_lines, "f");
+        return lines.map((line) => {
+            switch (line.type) {
+                case "comment":
+                    return line.val;
+                case "section":
+                    return `[${line.sec}]`;
+                case "value":
+                    return line.key + assignment +
+                        replacerFunc(line.key, line.val, line.sec);
+            }
+        }).join(__classPrivateFieldGet(this, _IniMap_formatting, "f")?.lineBreak ?? "\n");
+    }
+    /**
+     * 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, reviver) {
+        if (typeof text !== "string") {
+            throw new SyntaxError(`Unexpected token ${text} in INI at line 0`);
+        }
+        const reviverFunc = typeof reviver === "function"
+            ? reviver
+            : (_key, value, _section) => {
+                if (!isNaN(+value) && !value.includes('"'))
+                    return +value;
+                if (value === "null")
+                    return null;
+                if (value === "true" || value === "false")
+                    return value === "true";
+                return trimQuotes(value);
+            };
+        let lineNumber = 1;
+        let currentSection;
+        for (const line of __classPrivateFieldGet(this, _IniMap_instances, "m", _IniMap_readTextLines).call(this, text)) {
+            const trimmed = line.trim();
+            if (isComment(trimmed)) {
+                __classPrivateFieldGet(this, _IniMap_lines, "f").push({
+                    type: "comment",
+                    num: lineNumber,
+                    val: trimmed,
+                });
+            }
+            else if (isSection(trimmed, lineNumber)) {
+                const sec = trimmed.substring(1, trimmed.length - 1);
+                if (!NON_WHITESPACE_REGEXP.test(sec)) {
+                    throw new SyntaxError(`Unexpected empty section name at line ${lineNumber}`);
+                }
+                currentSection = {
+                    type: "section",
+                    num: lineNumber,
+                    sec,
+                    map: new Map(),
+                    end: lineNumber,
+                };
+                __classPrivateFieldGet(this, _IniMap_lines, "f").push(currentSection);
+                __classPrivateFieldGet(this, _IniMap_sections, "f").set(currentSection.sec, currentSection);
+            }
+            else {
+                const assignmentPos = trimmed.indexOf(ASSIGNMENT_MARK);
+                if (assignmentPos === -1) {
+                    throw new SyntaxError(`Unexpected token ${trimmed[0]} in INI at line ${lineNumber}`);
+                }
+                if (assignmentPos === 0) {
+                    throw new SyntaxError(`Unexpected empty key name at line ${lineNumber}`);
+                }
+                const leftHand = trimmed.substring(0, assignmentPos);
+                const rightHand = trimmed.substring(assignmentPos + 1);
+                if (__classPrivateFieldGet(this, _IniMap_formatting, "f").pretty === undefined) {
+                    __classPrivateFieldGet(this, _IniMap_formatting, "f").pretty = leftHand.endsWith(" ") &&
+                        rightHand.startsWith(" ");
+                }
+                const key = leftHand.trim();
+                const value = rightHand.trim();
+                if (currentSection) {
+                    const lineValue = {
+                        type: "value",
+                        num: lineNumber,
+                        sec: currentSection.sec,
+                        key,
+                        val: reviverFunc(key, value, currentSection.sec),
+                    };
+                    currentSection.map.set(key, lineValue);
+                    __classPrivateFieldGet(this, _IniMap_lines, "f").push(lineValue);
+                    currentSection.end = lineNumber;
+                }
+                else {
+                    const lineValue = {
+                        type: "value",
+                        num: lineNumber,
+                        key,
+                        val: reviverFunc(key, value),
+                    };
+                    __classPrivateFieldGet(this, _IniMap_global, "f").set(key, lineValue);
+                    __classPrivateFieldGet(this, _IniMap_lines, "f").push(lineValue);
+                }
+            }
+            lineNumber += 1;
+        }
+        return this;
+    }
+    static from(
+    // deno-lint-ignore no-explicit-any
+    input, formatting) {
+        const ini = new IniMap(formatting);
+        if (typeof input === "object" && input !== null) {
+            // deno-lint-ignore no-explicit-any
+            const isRecord = (val) => typeof val === "object" && val !== null;
+            // deno-lint-ignore no-explicit-any
+            const sort = ([_a, valA], [_b, valB]) => {
+                if (isRecord(valA))
+                    return 1;
+                if (isRecord(valB))
+                    return -1;
+                return 0;
+            };
+            for (const [key, val] of Object.entries(input).sort(sort)) {
+                if (isRecord(val)) {
+                    for (const [sectionKey, sectionValue] of Object.entries(val)) {
+                        ini.set(key, sectionKey, sectionValue);
+                    }
+                }
+                else {
+                    ini.set(key, val);
+                }
+            }
+        }
+        else {
+            ini.parse(input, formatting?.reviver);
+        }
+        return ini;
+    }
+}
+_IniMap_global = new WeakMap(), _IniMap_sections = new WeakMap(), _IniMap_lines = new WeakMap(), _IniMap_formatting = new WeakMap(), _IniMap_instances = new WeakSet(), _IniMap_getOrCreateSection = function _IniMap_getOrCreateSection(section) {
+    const existing = __classPrivateFieldGet(this, _IniMap_sections, "f").get(section);
+    if (existing) {
+        return existing;
+    }
+    const lineSection = {
+        type: "section",
+        num: __classPrivateFieldGet(this, _IniMap_lines, "f").length + 1,
+        sec: section,
+        map: new Map(),
+        end: __classPrivateFieldGet(this, _IniMap_lines, "f").length + 1,
+    };
+    __classPrivateFieldGet(this, _IniMap_lines, "f").push(lineSection);
+    __classPrivateFieldGet(this, _IniMap_sections, "f").set(section, lineSection);
+    return lineSection;
+}, _IniMap_appendValue = function _IniMap_appendValue(lineValue) {
+    if (__classPrivateFieldGet(this, _IniMap_lines, "f").length === 0) {
+        // For an empty array, just insert the line value
+        lineValue.num = 1;
+        __classPrivateFieldGet(this, _IniMap_lines, "f").push(lineValue);
+    }
+    else if (lineValue.sec) {
+        // For line values in a section, the end of the section is known
+        __classPrivateFieldGet(this, _IniMap_instances, "m", _IniMap_appendOrDeleteLine).call(this, lineValue, LineOp.Add);
+    }
+    else {
+        // For global values, find the line preceding the first section
+        lineValue.num = __classPrivateFieldGet(this, _IniMap_lines, "f").length + 1;
+        for (const [i, line] of __classPrivateFieldGet(this, _IniMap_lines, "f").entries()) {
+            if (line.type === "section") {
+                lineValue.num = i + 1;
+                break;
+            }
+        }
+        // Append the line value at the end of all global values
+        __classPrivateFieldGet(this, _IniMap_instances, "m", _IniMap_appendOrDeleteLine).call(this, lineValue, LineOp.Add);
+    }
+}, _IniMap_appendOrDeleteLine = function _IniMap_appendOrDeleteLine(input, op) {
+    if (op === LineOp.Add) {
+        __classPrivateFieldGet(this, _IniMap_lines, "f").splice(input.num - 1, 0, input);
+    }
+    else {
+        __classPrivateFieldGet(this, _IniMap_lines, "f").splice(input.num - 1, 1);
+    }
+    // If the input is a comment, find the next section if any to update.
+    let updateSection = input.type === "comment";
+    const start = op === LineOp.Add ? input.num : input.num - 1;
+    for (const line of __classPrivateFieldGet(this, _IniMap_lines, "f").slice(start)) {
+        line.num += op;
+        if (line.type === "section") {
+            line.end += op;
+            // If the comment is before the nearest section, don't update the section further.
+            updateSection = false;
+        }
+        if (updateSection) {
+            // if the comment precedes a value in a section, get and update the section end.
+            if (line.type === "value" && line.sec) {
+                const section = __classPrivateFieldGet(this, _IniMap_sections, "f").get(line.sec);
+                if (section) {
+                    section.end += op;
+                    updateSection = false;
+                }
+            }
+        }
+    }
+}, _IniMap_readTextLines = function* _IniMap_readTextLines(text) {
+    const { length } = text;
+    let line = "";
+    for (let i = 0; i < length; i += 1) {
+        const char = text[i];
+        if (char === "\n" || char === "\r") {
+            yield line;
+            line = "";
+            if (char === "\r" && text[i + 1] === "\n") {
+                i++;
+                if (!__classPrivateFieldGet(this, _IniMap_formatting, "f").lineBreak) {
+                    __classPrivateFieldGet(this, _IniMap_formatting, "f").lineBreak = "\r\n";
+                }
+            }
+            else if (!__classPrivateFieldGet(this, _IniMap_formatting, "f").lineBreak) {
+                __classPrivateFieldGet(this, _IniMap_formatting, "f").lineBreak = char;
+            }
+        }
+        else {
+            line += char;
+        }
+    }
+    yield line;
+}, _IniMap_cleanFormatting = function _IniMap_cleanFormatting(options) {
+    return Object.fromEntries(Object.entries(options ?? {}).filter(([key]) => FormattingKeys.includes(key)));
+};
+/** Detect supported comment styles. */
+function isComment(input) {
+    return input === "" ||
+        input.startsWith("#") ||
+        input.startsWith(";") ||
+        input.startsWith("//");
+}
+/** Detect a section start. */
+function isSection(input, lineNumber) {
+    if (input.startsWith("[")) {
+        if (input.endsWith("]")) {
+            return true;
+        }
+        throw new SyntaxError(`Unexpected end of INI section at line ${lineNumber}`);
+    }
+    return false;
+}
+const LineOp = {
+    Del: -1,
+    Add: 1,
+};
+const DummyFormatting = {
+    lineBreak: "\n",
+    pretty: false,
+};
+const FormattingKeys = Object.keys(DummyFormatting);

package/esm/std/ini/mod.d.ts

@@ -0,0 +1,31 @@
+/**
+ * {@linkcode parse} and {@linkcode stringify} for handling
+ * {@link https://en.wikipedia.org/wiki/INI_file | INI} encoded data, such as the
+ * {@link https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s03.html | Desktop Entry specification}.
+ *
+ * ```ts
+ * import { parse, stringify } from "mod.ts";
+ * import { assertEquals } from "../assert/mod.ts";
+ *
+ * const text = `Global Key=Some data here
+ * [Section #1]
+ * Section Value=42
+ * Section Date=1977-05-25`;
+ *
+ * const parsed = parse(text);
+ *
+ * assertEquals(parse(text), {
+ *   "Global Key": "Some data here",
+ *   "Section #1": {
+ *     "Section Value": 42,
+ *     "Section Date": "1977-05-25",
+ *   },
+ * });
+ *
+ * assertEquals(stringify(parsed), text);
+ * ```
+ *
+ * @module
+ */
+export * from "./parse.js";
+export * from "./stringify.js";

package/esm/std/ini/mod.js

@@ -0,0 +1,33 @@
+// Copyright 2018-2025 the Deno authors. 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
+ * {@link https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s03.html | Desktop Entry specification}.
+ *
+ * ```ts
+ * import { parse, stringify } from "mod.ts";
+ * import { assertEquals } from "../assert/mod.ts";
+ *
+ * const text = `Global Key=Some data here
+ * [Section #1]
+ * Section Value=42
+ * Section Date=1977-05-25`;
+ *
+ * const parsed = parse(text);
+ *
+ * assertEquals(parse(text), {
+ *   "Global Key": "Some data here",
+ *   "Section #1": {
+ *     "Section Value": 42,
+ *     "Section Date": "1977-05-25",
+ *   },
+ * });
+ *
+ * assertEquals(stringify(parsed), text);
+ * ```
+ *
+ * @module
+ */
+export * from "./parse.js";
+export * from "./stringify.js";

package/esm/std/ini/parse.d.ts

@@ -0,0 +1,77 @@
+import { type ReviverFunction } from "./_ini_map.js";
+export type { ReviverFunction };
+/** Options for {@linkcode parse}. */
+export interface ParseOptions<T = any> {
+    /**
+     * Provide custom parsing of the value in a key/value pair. Similar to the
+     * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#reviver | reviver}
+     * function in {@linkcode JSON.parse}.
+     */
+    reviver?: ReviverFunction<T>;
+}
+/**
+ * Parse an INI config string into an object.
+ *
+ * Values are parsed as strings by default to preserve data parity from the
+ * original. To parse values as other types besides strings, use
+ * {@linkcode ParseOptions.reviver}.
+ *
+ * Nested sections, repeated key names within a section, and key/value arrays
+ * are not supported. White space padding and lines starting with `#`, `;`, or
+ * `//` will be treated as comments.
+ *
+ * @throws {SyntaxError} If the INI string is invalid or if it contains
+ * multi-line values.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse } from "parse.ts";
+ * import { assertEquals } from "../assert/mod.ts";
+ *
+ * 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 "parse.ts";
+ * import { assertEquals } from "../assert/mod.ts";
+ *
+ * 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
+ * @param options The options to use
+ * @typeParam T The type of the value
+ * @return The parsed object
+ */
+export declare function parse<T = any>(text: string, options?: ParseOptions<T>): Record<string, T | Record<string, T>>;

package/esm/std/ini/parse.js

@@ -0,0 +1,72 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+// This module is browser compatible.
+import { IniMap } from "./_ini_map.js";
+/**
+ * Parse an INI config string into an object.
+ *
+ * Values are parsed as strings by default to preserve data parity from the
+ * original. To parse values as other types besides strings, use
+ * {@linkcode ParseOptions.reviver}.
+ *
+ * Nested sections, repeated key names within a section, and key/value arrays
+ * are not supported. White space padding and lines starting with `#`, `;`, or
+ * `//` will be treated as comments.
+ *
+ * @throws {SyntaxError} If the INI string is invalid or if it contains
+ * multi-line values.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse } from "parse.ts";
+ * import { assertEquals } from "../assert/mod.ts";
+ *
+ * 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 "parse.ts";
+ * import { assertEquals } from "../assert/mod.ts";
+ *
+ * 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
+ * @param options The options to use
+ * @typeParam T The type of the value
+ * @return The parsed object
+ */
+// deno-lint-ignore no-explicit-any
+export function parse(text, options) {
+    return IniMap.from(text, options).toObject();
+}

package/esm/std/ini/stringify.d.ts

@@ -0,0 +1,83 @@
+import { type ReplacerFunction } from "./_ini_map.js";
+/** Options for {@linkcode stringify}. */
+export interface StringifyOptions {
+    /**
+     * Character(s) used to break lines in the config file.
+     *
+     * @default {"\n"}
+     */
+    lineBreak?: "\n" | "\r\n" | "\r";
+    /**
+     * Use a plain assignment char or pad with spaces.
+     *
+     * @default {false}
+     */
+    pretty?: boolean;
+    /**
+     * Provide custom string conversion for the value in a key/value pair.
+     * Similar to the
+     * {@linkcode https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#replacer | replacer}
+     * function in {@linkcode JSON.stringify}.
+     */
+    replacer?: ReplacerFunction;
+}
+export type { ReplacerFunction };
+/**
+ * Compile an object into an INI config string. Provide formatting options to modify the output.
+ *
+ * @example Usage
+ * ```ts
+ * import { stringify } from "stringify.ts";
+ * import { assertEquals } from "../assert/mod.ts";
+ *
+ * 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 "stringify.ts";
+ * import { assertEquals } from "../assert/mod.ts";
+ *
+ * const str = stringify({
+ *   "section X": {
+ *     date: new Date("2024-06-10"),
+ *   },
+ *   "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
+ */
+export declare function stringify(object: any, options?: StringifyOptions): string;