pronouny 0.4.0 → 1.0.0

package/README.md

@@ -1,115 +1,275 @@
 # Pronouny
 
-**Pronouny** is a typed library intended to make programmatically resolving English pronouns easier.
+**Pronouny** is a small, typed library that makes programmatically resolving English pronouns easy. It ships as both ESM and CommonJS, has zero runtime dependencies, and is designed to be extended.
 
 ## Installation
 
-To install, simply run `npm install pronouny`.
+```sh
+npm install pronouny
+```
 
-## Usage
+## Quick start
 
 ```ts
-// Single import
 import Pronouny from "pronouny";
 
-// Create a new instance of Pronouny. All config is optional.
-// Below are defaults.
+const p = new Pronouny();
+
+const vayne = {
+	username: "vaynegarden",
+	pronouns: p.set("she/they"),
+};
+
+console.log(vayne.pronouns.parse`${vayne.username} updated ${"their"} status.`);
+// "vaynegarden updated her status." or "...their status.", chosen
+// consistently for the whole sentence.
+```
+
+## Concepts
+
+Pronouny has three classes:
+
+| Class            | What it is                                                          |
+| ---------------- | ------------------------------------------------------------------- |
+| **`Pronouny`**   | The resolver. Registers pronouns and turns strings into `Pronoun`s. |
+| **`Pronoun`**    | A single pronoun with all five grammatical forms.                   |
+| **`PronounSet`** | An ordered set of `Pronoun`s for one entity (e.g. `she/they`).      |
+
+Every pronoun has five **forms**:
+
+| Form                   | Example (`she`) | Aliases accepted on input |
+| ---------------------- | --------------- | ------------------------- |
+| `subject`              | she             |                           |
+| `object`               | her             |                           |
+| `possessive`           | hers            |                           |
+| `possessiveDeterminer` | her             | `possessiveAdjective`     |
+| `reflexive`            | herself         | `intensive`               |
+
+## Configuration
+
+All configuration is optional. The defaults are shown below, and any
+option can be overridden per call by passing a partial config as the
+last argument to most methods.
+
+```ts
 const p = new Pronouny({
-	// Will default to failing quietly into "they".
+	// Recoverable errors resolve to a fallback instead of throwing.
 	failQuietly: true,
 
-	// Will default to only querying the first subject
-	// pronoun to limit scope. Set to "true" to force
-	// recursive search.
+	// resolve() only matches ids/subject forms. Set true to match any form.
 	deepSearch: false,
 
-	// Will default to using random pronouns in arrays.
-	// Set to false to force using 0 index.
+	// Pick forms/pronouns at random. Set false to always use the first.
 	useRandom: true,
 
-	// Will default to using "they" as a fallback pronoun.
+	// The id used whenever resolution fails quietly.
 	fallbackPronoun: "they",
 });
+```
+
+Pronouny ships with `he`, `she`, `they`, `it`, `you`, `we`, and `i`
+registered by default.
+
+## Usage
+
+### Adding and removing pronouns
+
+```ts
+// Register a pronoun under a unique id. A form may be a single string
+// or an array of accepted spellings.
+const ze = p.add("ze", {
+	subject: "ze",
+	object: "hir",
+	possessive: "hirs",
+	possessiveDeterminer: "hir",
+	reflexive: "hirself",
+});
 
-// Create a new Pronoun object using Pronouny.new()
-const pronounZe: Pronoun = p.new(
-	{
-		subject: "ze",
-		object: "hir",
-		possessive: "hirs",
-		psAdjective: "hir",
-		reflexive: "hirself",
-	},
-	false
-);
+// Because ids are explicit, two pronouns can share a subject form —
+// e.g. a plural and a singular "they":
+p.add("they-singular", {
+	subject: "they",
+	object: "them",
+	possessive: "theirs",
+	possessiveDeterminer: "their",
+	reflexive: "themself",
+});
 
-// .new() will automatically add new Pronouns to its
-// validation map. however, if you want to do so manually,
-// you can do it with Pronouny.add().
-p.add(pronounZe);
+// Remove a pronoun by id.
+p.remove("it");
+```
 
-// .remove() also works;
-p.remove(p.resolve("I"));
-// this deletes the "I" pronoun from the map.
+### Resolving and identifying
 
-// Methods are chainable so you can reach the Pronoun class.
-p.add(pronounZe).set("he/they").use().subject();
-//   ^Pronouny      ^PronounSet    ^Pronoun  ^string
+```ts
+p.resolve("she").id; // "she"
 
-// Instantiate a set of pronouns using Pronouny.set().
-const vayne = {
-	username: "vaynegarden",
-	pronouns: p.set("she/ze/they"),
-};
-// from there, you can use `[PronounSet].use()` to get a random `Pronoun`.
+// Shallow resolution (default) only matches ids and subject forms, so
+// "him" falls back to "they":
+p.resolve("him").id; // "they"
+
+// Deep resolution matches any form:
+p.resolve("him", { deepSearch: true }).id; // "he"
+
+// identify() reports which form a word is, or undefined:
+p.identify("her"); // "object"
+p.identify("their"); // "possessiveDeterminer"
+p.identify("banana"); // undefined
+```
+
+### Getting a specific form
+
+Use `.as(form)` on a `Pronoun`, or on a `PronounSet` to pick one member
+first.
+
+```ts
+const they = p.resolve("they");
+they.as("subject"); // "they"
+they.as("possessiveDeterminer"); // "their"
+they.as("intensive"); // alias of "reflexive"
+
+// A PronounSet picks a member (per config) then returns the form:
+p.set("she/they").as("object"); // "her" or "them"
+```
+
+### Template parsing
+
+`parse` is a tagged-template helper. Interpolated pronoun words are
+rewritten into the correct form and capitalisation is preserved;
+everything else is left untouched.
+
+On a `Pronoun`, every substitution uses that pronoun. On a `PronounSet`,
+each substitution independently draws a pronoun from the set (per the
+`useRandom` config), so a multi-pronoun set is distributed across the
+string:
+
+```ts
+const pronouns = p.set("she/they");
+
+pronouns.parse`${"They"} lost ${"their"} keys — help ${"them"}!`;
+// e.g. "She lost their keys — help them!" — each slot is drawn from the set.
+```
+
+Set `useRandom: false` if you want every slot to use the first member of
+the set instead.
+
+## Error handling
+
+When `failQuietly` is `false`, recoverable problems throw a typed
+[`PnyError`](src/errors.ts) instead of falling back:
+
+```ts
+import Pronouny, { PnyError } from "pronouny";
+
+const strict = new Pronouny({ failQuietly: false });
+
+try {
+	strict.resolve("notapronoun");
+} catch (err) {
+	if (err instanceof PnyError) {
+		console.error(err.type); // "PronounResolutionError"
+	}
+}
+```
+
+`PnyError` extends the native `Error`, so it works with normal
+`try`/`catch` and `instanceof`.
+
+## Extending the defaults
+
+Pass your own pronoun map as the second constructor argument to replace
+the built-ins entirely:
+
+```ts
+import Pronouny, { DEFAULT_PRONOUNS } from "pronouny";
 
-// Resolve the pronouns in your app by referencing the form
-// that you need. There's `subject`, `object`, `possessive`,
-// `psAdjective`, and `reflexive`.
-console.log(
-	`${vayne.username} has updated ${vayne.pronouns.psAdjective()} status.`
+// Start from the defaults and add to them.
+const p = new Pronouny(
+	{},
+	{
+		...DEFAULT_PRONOUNS,
+		xe: {
+			subject: "xe",
+			object: "xem",
+			possessive: "xyrs",
+			possessiveDeterminer: "xyr",
+			reflexive: "xemself",
+		},
+	},
 );
-// This returns "vaynegarden updated her status", "vaynegarden
-// updated hir status", or "vaynegarden updated their status",
-// selected randomly among the three.
+```
+
+## Development
+
+```sh
+npm install
+npm test        # run the Jest suite
+npm run build   # emit ESM + CJS + type declarations to lib/
 ```
 
 ## Changelog
 
+### v1.0.0
+
+- **Rewritten as a modular, multi-file package** with a proper dual
+  ESM/CJS build, type declarations, and an `exports` map.
+- **Bug fixes:**
+    - Per-call config no longer mutates the shared instance config.
+    - Random selection and index bounds now reach the last element and
+      no longer read out of bounds.
+    - `deepSearch` now actually performs a deep search.
+    - `parse()` compares words case-insensitively, so capitalised
+      non-pronoun words are left alone.
+- **Performance:** resolution and identification are backed by
+  hash-map indexes (O(1)) instead of linear scans.
+- **Errors:** `PnyError` now extends the native `Error` and is only
+  thrown when `failQuietly` is disabled (no more unconditional
+  `console.error`).
+- Pronouns are registered under explicit ids, so multiple pronouns can
+  share the same subject form.
+- Added `it` to the default pronouns and `identify()`, `has()`,
+  `get()`, and `list()` to `Pronouny`.
+
+### v0.5.0
+
+- Added `parse()` method to `Pronoun` and `PronounSet` to allow for parsing of strings into their correct pronoun forms.
+- Added optional `resolver` property to `Pronoun`s to allow retracing to related Pronouny instance.
+- Added `identify()` method to `Pronouny` to allow for identification for type of pronouns.
+
 ### v0.4.0
 
--   Optimized `forEach()` calls to use `for` loops instead.
--   Added `fallbackPronoun` option to allow for configuration of pronoun to use in case of quiet failure states.
--   Removed redundant `set` parameter from `[PronounSet].remove()` calls.
+- Optimized `forEach()` calls to use `for` loops instead.
+- Added `fallbackPronoun` option to allow for configuration of pronoun to use in case of quiet failure states.
+- Removed redundant `set` parameter from `[PronounSet].remove()` calls.
 
 ### v0.3.1
 
--   Added documentation.
--   Reordered `failQuietly` and `useRandom` on `Pronoun`.
--   Tested and fixed examples.
+- Added documentation.
+- Reordered `failQuietly` and `useRandom` on `Pronoun`.
+- Tested and fixed examples.
 
 ### v0.3.0
 
--   Rewritten to consolidate functionality into a single default export `Pronouny`.
--   Includes "we", "you", and "I" pronouns by default.
--   Added a config object so you can decide on error handling globally.
--   All methods are now chainable for ease of use.
+- Rewritten to consolidate functionality into a single default export `Pronouny`.
+- Includes "we", "you", and "I" pronouns by default.
+- Added a config object so you can decide on error handling globally.
+- All methods are now chainable for ease of use.
 
 ### v0.2.0
 
--   Now fails silently when trying to resolve pronouns that don't exist or indexing out of bounds.
--   Implementation of `PronounSet` class changed to Set from Array to prevent duplicate pronouns.
--   added `get()` method to `PronounSet` class to retrieve a random Pronoun object.
--   Added `add()` and `remove()` on `PronounSet`
+- Now fails silently when trying to resolve pronouns that don't exist or indexing out of bounds.
+- Implementation of `PronounSet` class changed to Set from Array to prevent duplicate pronouns.
+- added `get()` method to `PronounSet` class to retrieve a random Pronoun object.
+- Added `add()` and `remove()` on `PronounSet`
 
 ### v0.1.2
 
--   Initial release.
+- Initial release.
 
 ## TODO
 
--   [x] Consolidate implementation into one general-use class.
--   [x] Add global configuration for pronoun use.
--   [ ] Use more performant data structures.
--   [ ] Cleaner error handling.
--   [ ] Unique pronoun identifiers to allow for pronouns with the same first subject pronoun to have multiple forms.
+- [x] Consolidate implementation into one general-use class.
+- [x] Add global configuration for pronoun use.
+- [x] Use more performant data structures. _(hash-map indexes for O(1) resolve/identify)_
+- [x] Cleaner error handling. _(typed `PnyError extends Error`, thrown only when not failing quietly)_
+- [x] Unique pronoun identifiers to allow for pronouns with the same first subject pronoun to have multiple forms. _(pronouns are keyed by explicit `id`)_

package/lib/cjs/Pronoun.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The {@link Pronoun} class.
+ * @module
+ */
+import type Pronouny from "./Pronouny.js";
+import { type PartialConfig, type PronounComponents, type PronounFormInput, type PronounInput } from "./types.js";
+/**
+ * Normalise a loose {@link PronounInput} into strict
+ * {@link PronounComponents}, accepting single strings or arrays and
+ * legacy alias keys. Throws a {@link PnyError} if any form is missing.
+ */
+export declare function normalizeComponents(id: string, input: PronounInput): PronounComponents;
+/**
+ * # `Pronoun`
+ * A single pronoun with all five grammatical {@link PronounForm forms}.
+ * Each form may hold several accepted spellings.
+ *
+ * Create pronouns through {@link Pronouny.add} so they are registered
+ * for resolution, or construct one directly for standalone use.
+ */
+export declare class Pronoun {
+    /** Unique identifier within a {@link Pronouny} instance. */
+    readonly id: string;
+    /** The normalised forms of this pronoun. */
+    readonly components: PronounComponents;
+    /** The Pronouny instance this pronoun belongs to, if any. */
+    resolver?: Pronouny;
+    constructor(id: string, input: PronounInput, resolver?: Pronouny);
+    private get config();
+    /**
+     * Retrieve a single surface string for the requested grammatical
+     * form.
+     *
+     * @param form   The form to retrieve. Accepts aliases such as
+     *               `possessiveAdjective` and `intensive`. Defaults to
+     *               `subject`.
+     * @param index  Retrieve the `index`-th spelling of the form. When
+     *               `-1` (default) a spelling is chosen according to the
+     *               `useRandom` config.
+     * @param config Optional per-call config overrides.
+     */
+    as(form?: PronounFormInput, index?: number, config?: PartialConfig): string;
+    /**
+     * Tagged-template helper. Interpolated pronoun words are rewritten
+     * to the matching form of *this* pronoun, preserving capitalisation.
+     * Non-pronoun values pass through unchanged.
+     *
+     * ```ts
+     * he.parse`${"They"} updated ${"their"} status.`;
+     * // "He updated his status."
+     * ```
+     */
+    parse(strings: TemplateStringsArray, ...values: unknown[]): string;
+}
+//# sourceMappingURL=Pronoun.d.ts.map

package/lib/cjs/Pronoun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pronoun.d.ts","sourceRoot":"","sources":["../../src/Pronoun.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAG1C,OAAO,EAIN,KAAK,aAAa,EAClB,KAAK,iBAAiB,EAEtB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,MAAM,YAAY,CAAC;AAGpB;;;;GAIG;AACH,wBAAgB,mBAAmB,CAClC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,YAAY,GACjB,iBAAiB,CAsCnB;AAED;;;;;;;GAOG;AACH,qBAAa,OAAO;IACnB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IAEvC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,QAAQ,CAAC;gBAER,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,QAAQ;IAMhE,OAAO,KAAK,MAAM,GAEjB;IAED;;;;;;;;;;;OAWG;IACH,EAAE,CACD,IAAI,GAAE,gBAA4B,EAClC,KAAK,SAAK,EACV,MAAM,CAAC,EAAE,aAAa,GACpB,MAAM;IA4BT;;;;;;;;;OASG;IACH,KAAK,CACJ,OAAO,EAAE,oBAAoB,EAC7B,GAAG,MAAM,EAAE,OAAO,EAAE,GAClB,MAAM;CAKT"}

package/lib/cjs/Pronoun.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * The {@link Pronoun} class.
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Pronoun = void 0;
+exports.normalizeComponents = normalizeComponents;
+const errors_js_1 = require("./errors.js");
+const template_js_1 = require("./template.js");
+const types_js_1 = require("./types.js");
+const utils_js_1 = require("./utils.js");
+/**
+ * Normalise a loose {@link PronounInput} into strict
+ * {@link PronounComponents}, accepting single strings or arrays and
+ * legacy alias keys. Throws a {@link PnyError} if any form is missing.
+ */
+function normalizeComponents(id, input) {
+    const source = input;
+    const pick = (...keys) => {
+        for (const key of keys) {
+            const value = source[key];
+            if (value !== undefined) {
+                return (0, utils_js_1.toArray)(value).map(String);
+            }
+        }
+        return undefined;
+    };
+    const components = {
+        subject: pick("subject"),
+        object: pick("object"),
+        possessive: pick("possessive"),
+        possessiveDeterminer: pick("possessiveDeterminer", "possessiveAdjective", "psAdjective"),
+        reflexive: pick("reflexive", "intensive"),
+    };
+    for (const form of types_js_1.PRONOUN_FORMS) {
+        const value = components[form];
+        if (!value || value.length === 0) {
+            throw new errors_js_1.PnyError("PronounValidationError", `Pronoun "${id}" is missing a value for the "${form}" form.`);
+        }
+    }
+    return components;
+}
+/**
+ * # `Pronoun`
+ * A single pronoun with all five grammatical {@link PronounForm forms}.
+ * Each form may hold several accepted spellings.
+ *
+ * Create pronouns through {@link Pronouny.add} so they are registered
+ * for resolution, or construct one directly for standalone use.
+ */
+class Pronoun {
+    constructor(id, input, resolver) {
+        this.id = id;
+        this.components = normalizeComponents(id, input);
+        this.resolver = resolver;
+    }
+    get config() {
+        return this.resolver?.config ?? types_js_1.DEFAULT_CONFIG;
+    }
+    /**
+     * Retrieve a single surface string for the requested grammatical
+     * form.
+     *
+     * @param form   The form to retrieve. Accepts aliases such as
+     *               `possessiveAdjective` and `intensive`. Defaults to
+     *               `subject`.
+     * @param index  Retrieve the `index`-th spelling of the form. When
+     *               `-1` (default) a spelling is chosen according to the
+     *               `useRandom` config.
+     * @param config Optional per-call config overrides.
+     */
+    as(form = "subject", index = -1, config) {
+        const cfg = (0, utils_js_1.mergeConfig)(this.config, config);
+        const canonical = (0, types_js_1.canonicalForm)(form);
+        const ctx = this.components[canonical];
+        if (!ctx || ctx.length === 0) {
+            if (cfg.failQuietly)
+                return "";
+            throw new errors_js_1.PnyError("PronounFormError", `Pronoun "${this.id}" has no "${canonical}" form.`);
+        }
+        if (index >= 0) {
+            if (index >= ctx.length) {
+                if (cfg.failQuietly)
+                    return ctx[0];
+                throw new errors_js_1.PnyError("PronounIndexingError", `Index ${index} is out of range for the "${canonical}" form of "${this.id}" (length ${ctx.length}).`);
+            }
+            return ctx[index];
+        }
+        if (!cfg.useRandom)
+            return ctx[0];
+        return ctx[(0, utils_js_1.randomIndex)(ctx.length)];
+    }
+    /**
+     * Tagged-template helper. Interpolated pronoun words are rewritten
+     * to the matching form of *this* pronoun, preserving capitalisation.
+     * Non-pronoun values pass through unchanged.
+     *
+     * ```ts
+     * he.parse`${"They"} updated ${"their"} status.`;
+     * // "He updated his status."
+     * ```
+     */
+    parse(strings, ...values) {
+        return (0, template_js_1.renderTemplate)(this.resolver, strings, values, (form) => this.as(form));
+    }
+}
+exports.Pronoun = Pronoun;
+//# sourceMappingURL=Pronoun.js.map

package/lib/cjs/Pronoun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pronoun.js","sourceRoot":"","sources":["../../src/Pronoun.ts"],"names":[],"mappings":"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"}

package/lib/cjs/PronounSet.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The {@link PronounSet} class.
+ * @module
+ */
+import { Pronoun } from "./Pronoun.js";
+import type Pronouny from "./Pronouny.js";
+import type { PartialConfig, PronounFormInput } from "./types.js";
+/** A pronoun, or a string that can be resolved to one. */
+export type PronounLike = Pronoun | string;
+/**
+ * # `PronounSet`
+ * An ordered, de-duplicated collection of {@link Pronoun}s representing
+ * how a single entity may be referred to (e.g. `she/they`).
+ *
+ * Create one with {@link Pronouny.set}. Call {@link PronounSet.use} to
+ * pick a pronoun, or {@link PronounSet.as} / {@link PronounSet.parse}
+ * to render a form directly.
+ */
+export declare class PronounSet {
+    /** The pronouns in this set, in insertion order. */
+    readonly pronouns: Set<Pronoun>;
+    /** The Pronouny instance that owns this set. */
+    readonly resolver: Pronouny;
+    constructor(resolver: Pronouny, pronouns?: Iterable<PronounLike> | PronounLike);
+    private resolveOne;
+    /**
+     * Add one or more pronouns to the set. Strings are resolved through
+     * the owning {@link Pronouny} instance. Chainable.
+     */
+    add(pronoun: Iterable<PronounLike> | PronounLike): this;
+    /**
+     * Remove one or more pronouns from the set. Strings are resolved
+     * through the owning {@link Pronouny} instance. Chainable.
+     */
+    remove(pronoun: Iterable<PronounLike> | PronounLike): this;
+    /** The number of pronouns in the set. */
+    get size(): number;
+    /** The pronouns as an array, in insertion order. */
+    list(): Pronoun[];
+    /**
+     * Pick a single {@link Pronoun} from the set.
+     *
+     * @param index  Retrieve the `index`-th pronoun. When `-1` (default)
+     *               a pronoun is chosen according to the `useRandom`
+     *               config.
+     * @param config Optional per-call config overrides.
+     */
+    use(index?: number, config?: PartialConfig): Pronoun;
+    /**
+     * Pick a pronoun from the set and return the requested grammatical
+     * form. Shorthand for `set.use(-1, config).as(form, -1, config)`.
+     */
+    as(form?: PronounFormInput, config?: PartialConfig): string;
+    /**
+     * Tagged-template helper. Each interpolated pronoun word is resolved
+     * independently, drawing a fresh pronoun from the set (per the
+     * `useRandom` config) for every substitution — so a multi-pronoun
+     * set is distributed across the string rather than fixed to one
+     * member. Interpolated pronoun words are rewritten to the matching
+     * form (preserving capitalisation); other values pass through
+     * unchanged.
+     *
+     * ```ts
+     * pronouns.parse`${"They"} updated ${"their"} status.`;
+     * // e.g. "She updated their status."
+     * ```
+     */
+    parse(strings: TemplateStringsArray, ...values: unknown[]): string;
+}
+//# sourceMappingURL=PronounSet.d.ts.map

package/lib/cjs/PronounSet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PronounSet.d.ts","sourceRoot":"","sources":["../../src/PronounSet.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAG1C,OAAO,KAAK,EAAE,aAAa,EAAe,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG/E,0DAA0D;AAC1D,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3C;;;;;;;;GAQG;AACH,qBAAa,UAAU;IACtB,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IAEhC,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;gBAG3B,QAAQ,EAAE,QAAQ,EAClB,QAAQ,GAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,WACjB;IAOlB,OAAO,CAAC,UAAU;IAMlB;;;OAGG;IACH,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,WAAW,GAAG,IAAI;IAWvD;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,WAAW,GAAG,IAAI;IAW1D,yCAAyC;IACzC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,oDAAoD;IACpD,IAAI,IAAI,OAAO,EAAE;IAIjB;;;;;;;OAOG;IACH,GAAG,CAAC,KAAK,SAAK,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO;IA6BhD;;;OAGG;IACH,EAAE,CAAC,IAAI,GAAE,gBAA4B,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,MAAM;IAItE;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM;CAQlE"}