pronouny 0.3.1 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # Pronouny
 
-**Pronouny** is a typed library intended to make programmatically resolving English pronouns easier. \
+**Pronouny** is a typed library intended to make programmatically resolving English pronouns easier.
 
 ## Installation
 
@@ -26,6 +26,9 @@ const p = new Pronouny({
 	// Will default to using random pronouns in arrays.
 	// Set to false to force using 0 index.
 	useRandom: true,
+
+	// Will default to using "they" as a fallback pronoun.
+	fallbackPronoun: "they",
 });
 
 // Create a new Pronoun object using Pronouny.new()
@@ -49,7 +52,7 @@ p.add(pronounZe);
 p.remove(p.resolve("I"));
 // this deletes the "I" pronoun from the map.
 
-// Methods are chainable and you can reach the Pronoun class.
+// Methods are chainable so you can reach the Pronoun class.
 p.add(pronounZe).set("he/they").use().subject();
 //   ^Pronouny      ^PronounSet    ^Pronoun  ^string
 
@@ -58,7 +61,7 @@ const vayne = {
 	username: "vaynegarden",
 	pronouns: p.set("she/ze/they"),
 };
-// from there, you can use `[PronounSet].use()` to get a random pronoun.
+// from there, you can use `[PronounSet].use()` to get a random `Pronoun`.
 
 // Resolve the pronouns in your app by referencing the form
 // that you need. There's `subject`, `object`, `possessive`,
@@ -69,10 +72,30 @@ console.log(
 // This returns "vaynegarden updated her status", "vaynegarden
 // updated hir status", or "vaynegarden updated their status",
 // selected randomly among the three.
+
+// Alternatively, you can use the `parse()` template string method
+// to parse a string with pronouns and write in reasonably natural syntax.
+// This functionality will be updated more in the future.
+console.log(
+	vayne.pronouns.parse`${vayne.username} has updated ${"her"} status.`
+);
+// Returns the same as above.
 ```
 
 ## Changelog
 
+### 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.
+
 ### v0.3.1
 
 -   Added documentation.

package/lib/cjs/index.d.ts

@@ -6,11 +6,13 @@
  * and `rfx`.
  */
 declare class Pronoun {
+    [key: string]: any;
     sbj: Array<string>;
     obj: Array<string>;
     psv: Array<string>;
     psj: Array<string>;
     rfx: Array<string>;
+    resolver?: Pronouny;
     /** @constructor */
     constructor(pronouns: {
         subject: Array<string> | string;
@@ -18,7 +20,7 @@ declare class Pronoun {
         possessive: Array<string> | string;
         psAdjective: Array<string> | string;
         reflexive: Array<string> | string;
-    });
+    }, resolver?: Pronouny);
     /**# Subject Getter
      * Get a subject pronoun. By default, uses one at
      * random and fails silently by using the last
@@ -115,6 +117,11 @@ declare class Pronoun {
      * Default is `true`.
      */
     reflexive(index?: number, useRandom?: boolean, failQuietly?: boolean): string;
+    /**# `.parse()` a Template String
+     * A method to parse tagged template strings and provide
+     * the correct pronouns, as per a particular PronounSet.
+     */
+    parse(strings: TemplateStringsArray, ...args: Array<string>): string;
 }
 /**# `PronounSet` class
  * A private class to construct the methods on
@@ -140,7 +147,7 @@ declare class PronounSet {
      * @param failQuietly
      * Override default behavior to fail into 'they'.
      */
-    add(pronoun: string | Pronoun | Array<string> | Array<Pronoun>, failQuietly?: boolean | undefined): this;
+    add(pronoun: string | Pronoun | Array<string> | Array<Pronoun>, failQuietly?: boolean): this;
     /**# `.remove()` from PronounSet
      * Remove pronoun/s from a given Pronoun or strings
      * (resolved using the {@linkcode Pronouny} instance
@@ -153,7 +160,7 @@ declare class PronounSet {
      * @param failQuietly
      * Override default behavior to fail into no removal.
      */
-    remove(set: PronounSet, pronoun: string | Pronoun | Array<string> | Array<Pronoun>, failQuietly?: boolean | undefined): this;
+    remove(pronoun: string | Pronoun | Array<string> | Array<Pronoun>, failQuietly?: boolean): this;
     /**# `.use()` a PronounSet
      * A method to retrieve one Pronoun at random. Use with
      * {@link Pronoun|`Pronoun` methods} to get a specific
@@ -162,7 +169,7 @@ declare class PronounSet {
      * {@link PronounSet.possessive|`.possessive()`}, or
      * {@link PronounSet.reflexive|`.reflexive()`}. This is mostly
      * here if you'd like to explicitly get a `Pronoun` instance
-     * from a `PronounSet`.
+     * from a `PronounSet`. Also useful for narrowing {@link PronounSet.parse|`.parse()`}.
      *
      * @param index
      * Retrieve `index`th pronoun from insertion.
@@ -174,17 +181,24 @@ declare class PronounSet {
      * Override default behavior to use random as per
      * Pronouny config.
      */
-    use(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): Pronoun;
+    use(index?: number, failQuietly?: boolean, useRandom?: boolean): Pronoun;
     /**Retrieves a random subject pronoun. */
-    subject(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): string;
+    subject(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
     /**Retrieves a random object pronoun. */
-    object(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): string;
+    object(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
     /**Retrieves a random possessive pronoun. */
-    possessive(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): string;
+    possessive(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
     /**Retrieves a random possessive adjective pronoun. */
-    psAdjective(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): string;
+    psAdjective(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
     /**Retrieves a random reflexive pronoun. */
-    reflexive(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): string;
+    reflexive(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
+    /**# Template Parsing
+     * A method to select only one pronoun from the set
+     * and reuse it for the entire string. This is useful
+     * for when you want to use the same pronoun for a
+     * sentence.
+     */
+    parse(strings: TemplateStringsArray, ...args: Array<string>): string;
 }
 /**# Config
  * `failQuietly`: Controls various quiet failure states.
@@ -197,19 +211,33 @@ declare class PronounSet {
  * used. If false, it will default to 0. If failing
  * quietly and indexing out of bounds, it will use the
  * last item.
+ *
+ * `fallbackPronoun`: Controls what is considered the
+ * default pronoun for when one is not assigned or for
+ * quiet failure states. By default, this is `they`. **It
+ * is not recommended to change this.**
  */
 type PronounyConfig = {
     /**Controls various quiet failure states. */
-    failQuietly?: boolean;
+    failQuietly: boolean;
     /**Controls how deeply Pronouny will search for
      * queries. By default, `string` parameters will
      * only resolve using the first subject pronoun. */
-    deepSearch?: boolean;
+    deepSearch: boolean;
     /**Controls whether random selection will be used.
      * If false, it will default to 0. If failing
      * quietly and indexing out of bounds, it will
      * use the last item. */
-    useRandom?: boolean;
+    useRandom: boolean;
+    /**Controls what is considered the default pronoun
+     * for when one is not assigned or for quiet failure
+     * states. By default, this is `they`. **It is not
+     * recommended to change this.**
+     *
+     * If you remove `they` from the Pronouny instance,
+     * you are responsible for setting this to a valid
+     * pronoun string and ensuring it will resolve. */
+    fallbackPronoun: string;
 };
 /**# Pronouny
  * A typed library intended to make English pronoun
@@ -236,15 +264,40 @@ type PronounyConfig = {
  * `Pronoun` object.
  */
 export default class Pronouny {
+    [keyof: string]: any;
     config: PronounyConfig;
     resolveMap: Map<string, Pronoun>;
+    default: {
+        he: Pronoun;
+        she: Pronoun;
+        they: Pronoun;
+        you: Pronoun;
+        i: Pronoun;
+        we: Pronoun;
+        config: {
+            failQuietly: boolean;
+            deepSearch: boolean;
+            useRandom: boolean;
+            fallbackPronoun: string;
+        };
+    };
     constructor(config?: PronounyConfig);
     /**# `.resolve()` a Pronoun
      * Returns a pronoun from a given string. Uses
      * Pronouny's config to determine the depth of search.
      * By default, only checks the first subject pronoun.
      */
-    resolve(pronoun: string, deepSearch?: boolean | undefined): Pronoun;
+    resolve(pronoun: string, deepSearch?: boolean): Pronoun;
+    /**# `.identify()` a Pronoun
+     * Returns a string describing the type of pronoun
+     * passed in. Returns `subject`, `object`,
+     * `possessive`, `possessive adjective`, or
+     * `reflexive`. You can use this to access other
+     * pronouns by retrieving via string indexing.
+     * **This method is case-sensitive and does not
+     * have a quiet failure state.**
+     */
+    identify(pronoun: string): string;
     /**# `.add()` an Unlisted Pronoun
      * If you made a `.new()` Pronoun but disabled
      * `autoAppend`, you can later append it back by

package/lib/cjs/index.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 function randomToLimit(limit) {
     return Math.floor(Math.random() * limit);
 }
+function isUpperCase(str) {
+    return str === str.toUpperCase() && str !== str.toLowerCase();
+}
 /**# `Pronoun` class
  * A private class to construct the methods for pronoun
  * access. Use {@link Pronouny} to create and
@@ -12,7 +15,7 @@ function randomToLimit(limit) {
  */
 class Pronoun {
     /** @constructor */
-    constructor(pronouns) {
+    constructor(pronouns, resolver) {
         this.sbj =
             typeof pronouns.subject === "string"
                 ? [pronouns.subject]
@@ -33,6 +36,9 @@ class Pronoun {
             typeof pronouns.reflexive === "string"
                 ? [pronouns.reflexive]
                 : pronouns.reflexive;
+        if (resolver) {
+            this.resolver = resolver;
+        }
         return this;
     }
     /**# Subject Getter
@@ -201,6 +207,25 @@ class Pronoun {
                 throw new Error(`could not retrieve index ${index} from "${this.sbj[0]}" reflexive pronoun`);
         }
     }
+    /**# `.parse()` a Template String
+     * A method to parse tagged template strings and provide
+     * the correct pronouns, as per a particular PronounSet.
+     */
+    parse(strings, ...args) {
+        let result = strings[0];
+        for (let i = 0; i < args.length; i++) {
+            const upperCaseFlag = isUpperCase(args[i][0]);
+            let argSub = this.resolver?.identify(args[i].toLowerCase()) !== ""
+                ? this.use()[this.resolver?.identify(args[i].toLowerCase()) ||
+                    new Pronouny().identify(args[i].toLowerCase())]()
+                : args[i];
+            if (upperCaseFlag) {
+                argSub = argSub[0].toUpperCase() + argSub.slice(1);
+            }
+            result += argSub + strings[i + 1];
+        }
+        return result;
+    }
 }
 /**# `PronounSet` class
  * A private class to construct the methods on
@@ -216,27 +241,27 @@ class PronounSet {
         this.resolver = resolver;
         switch (true) {
             case Array.isArray(pronouns):
-                pronouns.forEach((x) => {
+                for (const x of pronouns) {
                     if (x instanceof Pronoun) {
                         this.pronouns.add(x);
                     }
                     else {
                         this.pronouns.add(resolver.resolve(x));
                     }
-                });
+                }
                 break;
             case typeof pronouns === "string":
                 this.pronouns.add(resolver.resolve(pronouns));
                 break;
             default:
-                pronouns.forEach((x) => {
+                for (const x of pronouns) {
                     if (x instanceof Pronoun) {
                         this.pronouns.add(x);
                     }
                     else {
                         this.pronouns.add(resolver.resolve(x));
                     }
-                });
+                }
                 break;
         }
         return this;
@@ -262,12 +287,12 @@ class PronounSet {
                 this.pronouns.add(this.resolver.resolve(pronoun));
                 break;
             case pronoun instanceof Array:
-                pronoun.forEach((p) => {
+                for (const p of pronoun) {
                     this.add(p, failQuietly);
-                });
+                }
                 break;
             case failQuietly:
-                this.pronouns.add(this.resolver.resolve("they"));
+                this.pronouns.add(this.resolver.resolve(this.resolver.config.fallbackPronoun));
                 break;
             case !failQuietly:
             default:
@@ -287,18 +312,18 @@ class PronounSet {
      * @param failQuietly
      * Override default behavior to fail into no removal.
      */
-    remove(set, pronoun, failQuietly = this.resolver.config.failQuietly) {
+    remove(pronoun, failQuietly = this.resolver.config.failQuietly) {
         switch (true) {
             case pronoun instanceof Pronoun:
-                set.pronouns.delete(pronoun);
+                this.pronouns.delete(pronoun);
                 break;
             case typeof pronoun === "string":
-                set.pronouns.delete(this.resolver.resolve(pronoun));
+                this.pronouns.delete(this.resolver.resolve(pronoun));
                 break;
             case pronoun instanceof Array:
-                pronoun.forEach((p) => {
-                    this.remove(set, p);
-                });
+                for (const p of pronoun) {
+                    this.remove(p);
+                }
                 break;
             case failQuietly:
                 break;
@@ -316,7 +341,7 @@ class PronounSet {
      * {@link PronounSet.possessive|`.possessive()`}, or
      * {@link PronounSet.reflexive|`.reflexive()`}. This is mostly
      * here if you'd like to explicitly get a `Pronoun` instance
-     * from a `PronounSet`.
+     * from a `PronounSet`. Also useful for narrowing {@link PronounSet.parse|`.parse()`}.
      *
      * @param index
      * Retrieve `index`th pronoun from insertion.
@@ -346,7 +371,7 @@ class PronounSet {
             case indexable[index] !== undefined:
                 return indexable[index];
             case failQuietly:
-                return this.resolver.resolve("they");
+                return this.resolver.resolve(this.resolver.config.fallbackPronoun);
             default:
                 throw new Error(`Index ${index} out of range`);
         }
@@ -371,54 +396,27 @@ class PronounSet {
     reflexive(index = -1, failQuietly = this.resolver.config.failQuietly, useRandom = this.resolver.config.useRandom) {
         return this.use(index, failQuietly, useRandom).reflexive(-1, failQuietly, useRandom);
     }
+    /**# Template Parsing
+     * A method to select only one pronoun from the set
+     * and reuse it for the entire string. This is useful
+     * for when you want to use the same pronoun for a
+     * sentence.
+     */
+    parse(strings, ...args) {
+        let result = strings[0];
+        for (let i = 0; i < args.length; i++) {
+            const upperCaseFlag = isUpperCase(args[i][0]);
+            let argSub = this.resolver.identify(args[i].toLowerCase()) !== ""
+                ? this.use()[this.resolver.identify(args[i].toLowerCase())]()
+                : args[i];
+            if (upperCaseFlag) {
+                argSub = argSub[0].toUpperCase() + argSub.slice(1);
+            }
+            result += argSub + strings[i + 1];
+        }
+        return result;
+    }
 }
-const pronounHe = new Pronoun({
-    subject: ["he"],
-    object: ["him"],
-    possessive: ["his"],
-    psAdjective: ["his"],
-    reflexive: ["himself"],
-});
-const pronounShe = new Pronoun({
-    subject: ["she"],
-    object: ["her"],
-    possessive: ["hers"],
-    psAdjective: ["her"],
-    reflexive: ["herself"],
-});
-const pronounThey = new Pronoun({
-    subject: ["they"],
-    object: ["them"],
-    possessive: ["theirs"],
-    psAdjective: ["their"],
-    reflexive: ["theirself", "theirselves", "themselves", "themself"],
-});
-const pronounYou = new Pronoun({
-    subject: ["you"],
-    object: ["you"],
-    possessive: ["yours"],
-    psAdjective: ["your"],
-    reflexive: ["yourself"],
-});
-const pronounI = new Pronoun({
-    subject: ["I"],
-    object: ["me"],
-    possessive: ["mine"],
-    psAdjective: ["my"],
-    reflexive: ["myself"],
-});
-const pronounWe = new Pronoun({
-    subject: ["we"],
-    object: ["us"],
-    possessive: ["our"],
-    psAdjective: ["ours"],
-    reflexive: ["ourselves"],
-});
-const PronounyDefaultConfig = {
-    failQuietly: true,
-    deepSearch: false,
-    useRandom: true,
-};
 /**# Pronouny
  * A typed library intended to make English pronoun
  * resolution easy. Instantiate in your project using
@@ -444,15 +442,76 @@ const PronounyDefaultConfig = {
  * `Pronoun` object.
  */
 class Pronouny {
-    constructor(config = PronounyDefaultConfig) {
-        this.config = Object.assign(PronounyDefaultConfig, config);
+    constructor(config = {
+        failQuietly: true,
+        deepSearch: false,
+        useRandom: true,
+        fallbackPronoun: "they",
+    }) {
+        this.default = {
+            he: new Pronoun({
+                subject: ["he"],
+                object: ["him"],
+                possessive: ["his"],
+                psAdjective: ["his"],
+                reflexive: ["himself"],
+            }, this),
+            she: new Pronoun({
+                subject: ["she"],
+                object: ["her"],
+                possessive: ["hers"],
+                psAdjective: ["her"],
+                reflexive: ["herself"],
+            }, this),
+            they: new Pronoun({
+                subject: ["they"],
+                object: ["them"],
+                possessive: ["theirs"],
+                psAdjective: ["their"],
+                reflexive: [
+                    "theirself",
+                    "theirselves",
+                    "themselves",
+                    "themself",
+                ],
+            }, this),
+            you: new Pronoun({
+                subject: ["you"],
+                object: ["you"],
+                possessive: ["yours"],
+                psAdjective: ["your"],
+                reflexive: ["yourself"],
+            }, this),
+            i: new Pronoun({
+                subject: ["I"],
+                object: ["me"],
+                possessive: ["mine"],
+                psAdjective: ["my"],
+                reflexive: ["myself"],
+            }, this),
+            we: new Pronoun({
+                subject: ["we"],
+                object: ["us"],
+                possessive: ["ours"],
+                psAdjective: ["our"],
+                reflexive: ["ourselves"],
+            }, this),
+            config: {
+                failQuietly: true,
+                deepSearch: false,
+                useRandom: true,
+                fallbackPronoun: "they",
+            },
+        };
+        const defaults = this.default;
+        this.config = Object.assign(defaults.config, config);
         this.resolveMap = new Map([
-            [pronounThey.sbj[0], pronounThey],
-            [pronounYou.sbj[0], pronounYou],
-            [pronounWe.sbj[0], pronounWe],
-            [pronounI.sbj[0], pronounI],
-            [pronounHe.sbj[0], pronounHe],
-            [pronounShe.sbj[0], pronounShe],
+            [defaults.they.sbj[0], defaults.they],
+            [defaults.you.sbj[0], defaults.you],
+            [defaults.we.sbj[0], defaults.we],
+            [defaults.i.sbj[0], defaults.i],
+            [defaults.he.sbj[0], defaults.he],
+            [defaults.she.sbj[0], defaults.she],
         ]);
         return this;
     }
@@ -468,28 +527,66 @@ class Pronouny {
                 return resolvedPronoun;
             case deepSearch:
                 let searchResult;
-                this.resolveMap.forEach((mapPronoun) => {
-                    Object.values(mapPronoun).forEach((type) => {
+                for (const [_, value] of this.resolveMap) {
+                    for (const type of Object.values(value)) {
                         if (type.includes(pronoun)) {
-                            searchResult = mapPronoun;
+                            searchResult = value;
                         }
-                    });
-                });
+                    }
+                }
                 if (searchResult) {
                     return searchResult;
                 }
             case this.config.failQuietly:
-                return this.resolveMap.get("they");
+                return this.resolveMap.get(this.config.fallbackPronoun);
             default:
                 throw new Error(`Pronoun "${pronoun}" not found`);
         }
     }
+    /**# `.identify()` a Pronoun
+     * Returns a string describing the type of pronoun
+     * passed in. Returns `subject`, `object`,
+     * `possessive`, `possessive adjective`, or
+     * `reflexive`. You can use this to access other
+     * pronouns by retrieving via string indexing.
+     * **This method is case-sensitive and does not
+     * have a quiet failure state.**
+     */
+    identify(pronoun) {
+        let pronounType = "";
+        for (const [_, value] of this.resolveMap) {
+            for (let i = 0, types = Object.values(value); i < types.length; i++) {
+                let type = types[i];
+                if (Object.keys(value)[i] === "resolver") {
+                    continue;
+                }
+                if (type.includes(pronoun)) {
+                    pronounType = Object.keys(value)[i];
+                }
+            }
+        }
+        switch (pronounType) {
+            case "sbj":
+                return "subject";
+            case "obj":
+                return "object";
+            case "psv":
+                return "possessive";
+            case "psj":
+                return "psAdjective";
+            case "rfx":
+                return "reflexive";
+            default:
+                return "";
+        }
+    }
     /**# `.add()` an Unlisted Pronoun
      * If you made a `.new()` Pronoun but disabled
      * `autoAppend`, you can later append it back by
      * using this method. Returns `Pronouny`.
      */
     add(pronoun) {
+        pronoun.resolver = this;
         this.resolveMap.set(pronoun.sbj[0], pronoun);
         return this;
     }
@@ -498,6 +595,10 @@ class Pronouny {
      * Pronouny instance. Returns `Pronouny`.
      */
     remove(pronoun) {
+        if (pronoun === this.resolveMap.get(this.config.fallbackPronoun)) {
+            throw new Error(`Cannot remove fallback pronoun. Assign a new one before removal.`);
+        }
+        pronoun.resolver = undefined;
         this.resolveMap.delete(pronoun.sbj[0]);
         return this;
     }

package/lib/esm/index.d.ts

@@ -6,11 +6,13 @@
  * and `rfx`.
  */
 declare class Pronoun {
+    [key: string]: any;
     sbj: Array<string>;
     obj: Array<string>;
     psv: Array<string>;
     psj: Array<string>;
     rfx: Array<string>;
+    resolver?: Pronouny;
     /** @constructor */
     constructor(pronouns: {
         subject: Array<string> | string;
@@ -18,7 +20,7 @@ declare class Pronoun {
         possessive: Array<string> | string;
         psAdjective: Array<string> | string;
         reflexive: Array<string> | string;
-    });
+    }, resolver?: Pronouny);
     /**# Subject Getter
      * Get a subject pronoun. By default, uses one at
      * random and fails silently by using the last
@@ -115,6 +117,11 @@ declare class Pronoun {
      * Default is `true`.
      */
     reflexive(index?: number, useRandom?: boolean, failQuietly?: boolean): string;
+    /**# `.parse()` a Template String
+     * A method to parse tagged template strings and provide
+     * the correct pronouns, as per a particular PronounSet.
+     */
+    parse(strings: TemplateStringsArray, ...args: Array<string>): string;
 }
 /**# `PronounSet` class
  * A private class to construct the methods on
@@ -140,7 +147,7 @@ declare class PronounSet {
      * @param failQuietly
      * Override default behavior to fail into 'they'.
      */
-    add(pronoun: string | Pronoun | Array<string> | Array<Pronoun>, failQuietly?: boolean | undefined): this;
+    add(pronoun: string | Pronoun | Array<string> | Array<Pronoun>, failQuietly?: boolean): this;
     /**# `.remove()` from PronounSet
      * Remove pronoun/s from a given Pronoun or strings
      * (resolved using the {@linkcode Pronouny} instance
@@ -153,7 +160,7 @@ declare class PronounSet {
      * @param failQuietly
      * Override default behavior to fail into no removal.
      */
-    remove(set: PronounSet, pronoun: string | Pronoun | Array<string> | Array<Pronoun>, failQuietly?: boolean | undefined): this;
+    remove(pronoun: string | Pronoun | Array<string> | Array<Pronoun>, failQuietly?: boolean): this;
     /**# `.use()` a PronounSet
      * A method to retrieve one Pronoun at random. Use with
      * {@link Pronoun|`Pronoun` methods} to get a specific
@@ -162,7 +169,7 @@ declare class PronounSet {
      * {@link PronounSet.possessive|`.possessive()`}, or
      * {@link PronounSet.reflexive|`.reflexive()`}. This is mostly
      * here if you'd like to explicitly get a `Pronoun` instance
-     * from a `PronounSet`.
+     * from a `PronounSet`. Also useful for narrowing {@link PronounSet.parse|`.parse()`}.
      *
      * @param index
      * Retrieve `index`th pronoun from insertion.
@@ -174,17 +181,24 @@ declare class PronounSet {
      * Override default behavior to use random as per
      * Pronouny config.
      */
-    use(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): Pronoun;
+    use(index?: number, failQuietly?: boolean, useRandom?: boolean): Pronoun;
     /**Retrieves a random subject pronoun. */
-    subject(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): string;
+    subject(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
     /**Retrieves a random object pronoun. */
-    object(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): string;
+    object(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
     /**Retrieves a random possessive pronoun. */
-    possessive(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): string;
+    possessive(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
     /**Retrieves a random possessive adjective pronoun. */
-    psAdjective(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): string;
+    psAdjective(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
     /**Retrieves a random reflexive pronoun. */
-    reflexive(index?: number, failQuietly?: boolean | undefined, useRandom?: boolean | undefined): string;
+    reflexive(index?: number, failQuietly?: boolean, useRandom?: boolean): string;
+    /**# Template Parsing
+     * A method to select only one pronoun from the set
+     * and reuse it for the entire string. This is useful
+     * for when you want to use the same pronoun for a
+     * sentence.
+     */
+    parse(strings: TemplateStringsArray, ...args: Array<string>): string;
 }
 /**# Config
  * `failQuietly`: Controls various quiet failure states.
@@ -197,19 +211,33 @@ declare class PronounSet {
  * used. If false, it will default to 0. If failing
  * quietly and indexing out of bounds, it will use the
  * last item.
+ *
+ * `fallbackPronoun`: Controls what is considered the
+ * default pronoun for when one is not assigned or for
+ * quiet failure states. By default, this is `they`. **It
+ * is not recommended to change this.**
  */
 type PronounyConfig = {
     /**Controls various quiet failure states. */
-    failQuietly?: boolean;
+    failQuietly: boolean;
     /**Controls how deeply Pronouny will search for
      * queries. By default, `string` parameters will
      * only resolve using the first subject pronoun. */
-    deepSearch?: boolean;
+    deepSearch: boolean;
     /**Controls whether random selection will be used.
      * If false, it will default to 0. If failing
      * quietly and indexing out of bounds, it will
      * use the last item. */
-    useRandom?: boolean;
+    useRandom: boolean;
+    /**Controls what is considered the default pronoun
+     * for when one is not assigned or for quiet failure
+     * states. By default, this is `they`. **It is not
+     * recommended to change this.**
+     *
+     * If you remove `they` from the Pronouny instance,
+     * you are responsible for setting this to a valid
+     * pronoun string and ensuring it will resolve. */
+    fallbackPronoun: string;
 };
 /**# Pronouny
  * A typed library intended to make English pronoun
@@ -236,15 +264,40 @@ type PronounyConfig = {
  * `Pronoun` object.
  */
 export default class Pronouny {
+    [keyof: string]: any;
     config: PronounyConfig;
     resolveMap: Map<string, Pronoun>;
+    default: {
+        he: Pronoun;
+        she: Pronoun;
+        they: Pronoun;
+        you: Pronoun;
+        i: Pronoun;
+        we: Pronoun;
+        config: {
+            failQuietly: boolean;
+            deepSearch: boolean;
+            useRandom: boolean;
+            fallbackPronoun: string;
+        };
+    };
     constructor(config?: PronounyConfig);
     /**# `.resolve()` a Pronoun
      * Returns a pronoun from a given string. Uses
      * Pronouny's config to determine the depth of search.
      * By default, only checks the first subject pronoun.
      */
-    resolve(pronoun: string, deepSearch?: boolean | undefined): Pronoun;
+    resolve(pronoun: string, deepSearch?: boolean): Pronoun;
+    /**# `.identify()` a Pronoun
+     * Returns a string describing the type of pronoun
+     * passed in. Returns `subject`, `object`,
+     * `possessive`, `possessive adjective`, or
+     * `reflexive`. You can use this to access other
+     * pronouns by retrieving via string indexing.
+     * **This method is case-sensitive and does not
+     * have a quiet failure state.**
+     */
+    identify(pronoun: string): string;
     /**# `.add()` an Unlisted Pronoun
      * If you made a `.new()` Pronoun but disabled
      * `autoAppend`, you can later append it back by

package/lib/esm/index.js

@@ -1,6 +1,9 @@
 function randomToLimit(limit) {
     return Math.floor(Math.random() * limit);
 }
+function isUpperCase(str) {
+    return str === str.toUpperCase() && str !== str.toLowerCase();
+}
 /**# `Pronoun` class
  * A private class to construct the methods for pronoun
  * access. Use {@link Pronouny} to create and
@@ -10,7 +13,7 @@ function randomToLimit(limit) {
  */
 class Pronoun {
     /** @constructor */
-    constructor(pronouns) {
+    constructor(pronouns, resolver) {
         this.sbj =
             typeof pronouns.subject === "string"
                 ? [pronouns.subject]
@@ -31,6 +34,9 @@ class Pronoun {
             typeof pronouns.reflexive === "string"
                 ? [pronouns.reflexive]
                 : pronouns.reflexive;
+        if (resolver) {
+            this.resolver = resolver;
+        }
         return this;
     }
     /**# Subject Getter
@@ -199,6 +205,25 @@ class Pronoun {
                 throw new Error(`could not retrieve index ${index} from "${this.sbj[0]}" reflexive pronoun`);
         }
     }
+    /**# `.parse()` a Template String
+     * A method to parse tagged template strings and provide
+     * the correct pronouns, as per a particular PronounSet.
+     */
+    parse(strings, ...args) {
+        let result = strings[0];
+        for (let i = 0; i < args.length; i++) {
+            const upperCaseFlag = isUpperCase(args[i][0]);
+            let argSub = this.resolver?.identify(args[i].toLowerCase()) !== ""
+                ? this.use()[this.resolver?.identify(args[i].toLowerCase()) ||
+                    new Pronouny().identify(args[i].toLowerCase())]()
+                : args[i];
+            if (upperCaseFlag) {
+                argSub = argSub[0].toUpperCase() + argSub.slice(1);
+            }
+            result += argSub + strings[i + 1];
+        }
+        return result;
+    }
 }
 /**# `PronounSet` class
  * A private class to construct the methods on
@@ -214,27 +239,27 @@ class PronounSet {
         this.resolver = resolver;
         switch (true) {
             case Array.isArray(pronouns):
-                pronouns.forEach((x) => {
+                for (const x of pronouns) {
                     if (x instanceof Pronoun) {
                         this.pronouns.add(x);
                     }
                     else {
                         this.pronouns.add(resolver.resolve(x));
                     }
-                });
+                }
                 break;
             case typeof pronouns === "string":
                 this.pronouns.add(resolver.resolve(pronouns));
                 break;
             default:
-                pronouns.forEach((x) => {
+                for (const x of pronouns) {
                     if (x instanceof Pronoun) {
                         this.pronouns.add(x);
                     }
                     else {
                         this.pronouns.add(resolver.resolve(x));
                     }
-                });
+                }
                 break;
         }
         return this;
@@ -260,12 +285,12 @@ class PronounSet {
                 this.pronouns.add(this.resolver.resolve(pronoun));
                 break;
             case pronoun instanceof Array:
-                pronoun.forEach((p) => {
+                for (const p of pronoun) {
                     this.add(p, failQuietly);
-                });
+                }
                 break;
             case failQuietly:
-                this.pronouns.add(this.resolver.resolve("they"));
+                this.pronouns.add(this.resolver.resolve(this.resolver.config.fallbackPronoun));
                 break;
             case !failQuietly:
             default:
@@ -285,18 +310,18 @@ class PronounSet {
      * @param failQuietly
      * Override default behavior to fail into no removal.
      */
-    remove(set, pronoun, failQuietly = this.resolver.config.failQuietly) {
+    remove(pronoun, failQuietly = this.resolver.config.failQuietly) {
         switch (true) {
             case pronoun instanceof Pronoun:
-                set.pronouns.delete(pronoun);
+                this.pronouns.delete(pronoun);
                 break;
             case typeof pronoun === "string":
-                set.pronouns.delete(this.resolver.resolve(pronoun));
+                this.pronouns.delete(this.resolver.resolve(pronoun));
                 break;
             case pronoun instanceof Array:
-                pronoun.forEach((p) => {
-                    this.remove(set, p);
-                });
+                for (const p of pronoun) {
+                    this.remove(p);
+                }
                 break;
             case failQuietly:
                 break;
@@ -314,7 +339,7 @@ class PronounSet {
      * {@link PronounSet.possessive|`.possessive()`}, or
      * {@link PronounSet.reflexive|`.reflexive()`}. This is mostly
      * here if you'd like to explicitly get a `Pronoun` instance
-     * from a `PronounSet`.
+     * from a `PronounSet`. Also useful for narrowing {@link PronounSet.parse|`.parse()`}.
      *
      * @param index
      * Retrieve `index`th pronoun from insertion.
@@ -344,7 +369,7 @@ class PronounSet {
             case indexable[index] !== undefined:
                 return indexable[index];
             case failQuietly:
-                return this.resolver.resolve("they");
+                return this.resolver.resolve(this.resolver.config.fallbackPronoun);
             default:
                 throw new Error(`Index ${index} out of range`);
         }
@@ -369,54 +394,27 @@ class PronounSet {
     reflexive(index = -1, failQuietly = this.resolver.config.failQuietly, useRandom = this.resolver.config.useRandom) {
         return this.use(index, failQuietly, useRandom).reflexive(-1, failQuietly, useRandom);
     }
+    /**# Template Parsing
+     * A method to select only one pronoun from the set
+     * and reuse it for the entire string. This is useful
+     * for when you want to use the same pronoun for a
+     * sentence.
+     */
+    parse(strings, ...args) {
+        let result = strings[0];
+        for (let i = 0; i < args.length; i++) {
+            const upperCaseFlag = isUpperCase(args[i][0]);
+            let argSub = this.resolver.identify(args[i].toLowerCase()) !== ""
+                ? this.use()[this.resolver.identify(args[i].toLowerCase())]()
+                : args[i];
+            if (upperCaseFlag) {
+                argSub = argSub[0].toUpperCase() + argSub.slice(1);
+            }
+            result += argSub + strings[i + 1];
+        }
+        return result;
+    }
 }
-const pronounHe = new Pronoun({
-    subject: ["he"],
-    object: ["him"],
-    possessive: ["his"],
-    psAdjective: ["his"],
-    reflexive: ["himself"],
-});
-const pronounShe = new Pronoun({
-    subject: ["she"],
-    object: ["her"],
-    possessive: ["hers"],
-    psAdjective: ["her"],
-    reflexive: ["herself"],
-});
-const pronounThey = new Pronoun({
-    subject: ["they"],
-    object: ["them"],
-    possessive: ["theirs"],
-    psAdjective: ["their"],
-    reflexive: ["theirself", "theirselves", "themselves", "themself"],
-});
-const pronounYou = new Pronoun({
-    subject: ["you"],
-    object: ["you"],
-    possessive: ["yours"],
-    psAdjective: ["your"],
-    reflexive: ["yourself"],
-});
-const pronounI = new Pronoun({
-    subject: ["I"],
-    object: ["me"],
-    possessive: ["mine"],
-    psAdjective: ["my"],
-    reflexive: ["myself"],
-});
-const pronounWe = new Pronoun({
-    subject: ["we"],
-    object: ["us"],
-    possessive: ["our"],
-    psAdjective: ["ours"],
-    reflexive: ["ourselves"],
-});
-const PronounyDefaultConfig = {
-    failQuietly: true,
-    deepSearch: false,
-    useRandom: true,
-};
 /**# Pronouny
  * A typed library intended to make English pronoun
  * resolution easy. Instantiate in your project using
@@ -442,15 +440,76 @@ const PronounyDefaultConfig = {
  * `Pronoun` object.
  */
 export default class Pronouny {
-    constructor(config = PronounyDefaultConfig) {
-        this.config = Object.assign(PronounyDefaultConfig, config);
+    constructor(config = {
+        failQuietly: true,
+        deepSearch: false,
+        useRandom: true,
+        fallbackPronoun: "they",
+    }) {
+        this.default = {
+            he: new Pronoun({
+                subject: ["he"],
+                object: ["him"],
+                possessive: ["his"],
+                psAdjective: ["his"],
+                reflexive: ["himself"],
+            }, this),
+            she: new Pronoun({
+                subject: ["she"],
+                object: ["her"],
+                possessive: ["hers"],
+                psAdjective: ["her"],
+                reflexive: ["herself"],
+            }, this),
+            they: new Pronoun({
+                subject: ["they"],
+                object: ["them"],
+                possessive: ["theirs"],
+                psAdjective: ["their"],
+                reflexive: [
+                    "theirself",
+                    "theirselves",
+                    "themselves",
+                    "themself",
+                ],
+            }, this),
+            you: new Pronoun({
+                subject: ["you"],
+                object: ["you"],
+                possessive: ["yours"],
+                psAdjective: ["your"],
+                reflexive: ["yourself"],
+            }, this),
+            i: new Pronoun({
+                subject: ["I"],
+                object: ["me"],
+                possessive: ["mine"],
+                psAdjective: ["my"],
+                reflexive: ["myself"],
+            }, this),
+            we: new Pronoun({
+                subject: ["we"],
+                object: ["us"],
+                possessive: ["ours"],
+                psAdjective: ["our"],
+                reflexive: ["ourselves"],
+            }, this),
+            config: {
+                failQuietly: true,
+                deepSearch: false,
+                useRandom: true,
+                fallbackPronoun: "they",
+            },
+        };
+        const defaults = this.default;
+        this.config = Object.assign(defaults.config, config);
         this.resolveMap = new Map([
-            [pronounThey.sbj[0], pronounThey],
-            [pronounYou.sbj[0], pronounYou],
-            [pronounWe.sbj[0], pronounWe],
-            [pronounI.sbj[0], pronounI],
-            [pronounHe.sbj[0], pronounHe],
-            [pronounShe.sbj[0], pronounShe],
+            [defaults.they.sbj[0], defaults.they],
+            [defaults.you.sbj[0], defaults.you],
+            [defaults.we.sbj[0], defaults.we],
+            [defaults.i.sbj[0], defaults.i],
+            [defaults.he.sbj[0], defaults.he],
+            [defaults.she.sbj[0], defaults.she],
         ]);
         return this;
     }
@@ -466,28 +525,66 @@ export default class Pronouny {
                 return resolvedPronoun;
             case deepSearch:
                 let searchResult;
-                this.resolveMap.forEach((mapPronoun) => {
-                    Object.values(mapPronoun).forEach((type) => {
+                for (const [_, value] of this.resolveMap) {
+                    for (const type of Object.values(value)) {
                         if (type.includes(pronoun)) {
-                            searchResult = mapPronoun;
+                            searchResult = value;
                         }
-                    });
-                });
+                    }
+                }
                 if (searchResult) {
                     return searchResult;
                 }
             case this.config.failQuietly:
-                return this.resolveMap.get("they");
+                return this.resolveMap.get(this.config.fallbackPronoun);
             default:
                 throw new Error(`Pronoun "${pronoun}" not found`);
         }
     }
+    /**# `.identify()` a Pronoun
+     * Returns a string describing the type of pronoun
+     * passed in. Returns `subject`, `object`,
+     * `possessive`, `possessive adjective`, or
+     * `reflexive`. You can use this to access other
+     * pronouns by retrieving via string indexing.
+     * **This method is case-sensitive and does not
+     * have a quiet failure state.**
+     */
+    identify(pronoun) {
+        let pronounType = "";
+        for (const [_, value] of this.resolveMap) {
+            for (let i = 0, types = Object.values(value); i < types.length; i++) {
+                let type = types[i];
+                if (Object.keys(value)[i] === "resolver") {
+                    continue;
+                }
+                if (type.includes(pronoun)) {
+                    pronounType = Object.keys(value)[i];
+                }
+            }
+        }
+        switch (pronounType) {
+            case "sbj":
+                return "subject";
+            case "obj":
+                return "object";
+            case "psv":
+                return "possessive";
+            case "psj":
+                return "psAdjective";
+            case "rfx":
+                return "reflexive";
+            default:
+                return "";
+        }
+    }
     /**# `.add()` an Unlisted Pronoun
      * If you made a `.new()` Pronoun but disabled
      * `autoAppend`, you can later append it back by
      * using this method. Returns `Pronouny`.
      */
     add(pronoun) {
+        pronoun.resolver = this;
         this.resolveMap.set(pronoun.sbj[0], pronoun);
         return this;
     }
@@ -496,6 +593,10 @@ export default class Pronouny {
      * Pronouny instance. Returns `Pronouny`.
      */
     remove(pronoun) {
+        if (pronoun === this.resolveMap.get(this.config.fallbackPronoun)) {
+            throw new Error(`Cannot remove fallback pronoun. Assign a new one before removal.`);
+        }
+        pronoun.resolver = undefined;
         this.resolveMap.delete(pronoun.sbj[0]);
         return this;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pronouny",
-	"version": "0.3.1",
+	"version": "0.5.0",
 	"description": "a small, typed utility library to determine the correct pronoun from a string and several utility functions.",
 	"main": "./lib/cjs/index.js",
 	"module": "./lib/esm/index.js",