@sharpee/parser-en-us 0.9.60-beta

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Cornelson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @sharpee/parser-en-us
+
+English (US) parser for the Sharpee Interactive Fiction Platform.
+
+## Installation
+
+```bash
+pnpm add @sharpee/parser-en-us
+```
+
+## Usage
+
+```typescript
+import { EnglishParser } from '@sharpee/parser-en-us';
+import { ParserFactory } from '@sharpee/stdlib';
+import { EnglishLanguageProvider } from '@sharpee/lang-en-us';
+
+// Register the parser
+ParserFactory.registerParser('en-US', EnglishParser);
+
+// Create language provider
+const language = new EnglishLanguageProvider();
+
+// Create parser instance
+const parser = ParserFactory.createParser('en-US', language);
+
+// Parse commands
+const result = parser.parse('take the red ball');
+if (result.success) {
+  console.log(result.value.action); // 'if.action.taking'
+  console.log(result.value.structure.directObject?.text); // 'the red ball'
+}
+```
+
+## Features
+
+### Compound Verbs
+- "look at" → examining
+- "pick up" → taking  
+- "put down" → dropping
+- "turn on/off" → switching on/off
+
+### Rich Information Preservation
+- Articles preserved: "the", "a", "an"
+- Modifiers tracked: "red", "small", "wooden"
+- Position information for all tokens
+- Original text reconstructible
+
+### Grammar Patterns
+- `VERB_ONLY`: "look", "wait"
+- `VERB_NOUN`: "take ball", "examine mirror"
+- `VERB_PREP_NOUN`: "look at painting"
+- `VERB_NOUN_PREP_NOUN`: "put ball in box"
+- `DIRECTION_ONLY`: "north", "n"
+
+### Abbreviations
+- Verb abbreviations: "x" → "examine", "l" → "look"
+- Direction abbreviations: "n" → "north", "se" → "southeast"
+
+## Parsed Command Structure
+
+```typescript
+interface ParsedCommand {
+  rawInput: string;
+  tokens: Token[];
+  structure: {
+    verb: VerbPhrase;
+    directObject?: NounPhrase;
+    preposition?: PrepPhrase;
+    indirectObject?: NounPhrase;
+  };
+  pattern: string;
+  confidence: number;
+  action: string;
+}
+```
+
+### Example Output
+
+Input: "put the small key in the wooden box"
+
+```json
+{
+  "action": "if.action.putting",
+  "structure": {
+    "verb": {
+      "text": "put",
+      "head": "put"
+    },
+    "directObject": {
+      "text": "the small key",
+      "head": "key",
+      "articles": ["the"],
+      "modifiers": ["small"],
+      "candidates": ["key"]
+    },
+    "preposition": {
+      "text": "in"
+    },
+    "indirectObject": {
+      "text": "the wooden box",
+      "head": "box",
+      "articles": ["the"],
+      "modifiers": ["wooden"],
+      "candidates": ["box"]
+    }
+  },
+  "pattern": "VERB_NOUN_PREP_NOUN",
+  "confidence": 0.7
+}
+```
+
+## English-Specific Features
+
+- **SVO Word Order**: Subject-Verb-Object parsing
+- **Articles**: "the", "a", "an" handling
+- **Determiners**: "all", "every", "some"
+- **Compound Prepositions**: Multi-word verb phrases
+- **Flexible Adjective Placement**: "red ball" or "ball that is red"
+
+## License
+
+MIT

package/dist/direction-mappings.d.ts

@@ -0,0 +1,24 @@
+/**
+ * English-specific direction mappings for the parser
+ * Maps English words and abbreviations to language-agnostic Direction constants
+ */
+import { DirectionType } from '@sharpee/world-model';
+/**
+ * Map English direction words to Direction constants
+ */
+export declare const DirectionWords: Record<string, DirectionType>;
+/**
+ * Map English abbreviations to Direction constants
+ */
+export declare const DirectionAbbreviations: Record<string, DirectionType>;
+/**
+ * Parse an English direction string to a Direction constant
+ * Returns null if the string is not a recognized direction
+ */
+export declare function parseDirection(input: string): DirectionType | null;
+/**
+ * Get the English word for a Direction constant
+ * Used for display/output
+ */
+export declare function getDirectionWord(direction: DirectionType): string;
+//# sourceMappingURL=direction-mappings.d.ts.map

package/dist/direction-mappings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"direction-mappings.d.ts","sourceRoot":"","sources":["../src/direction-mappings.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAa,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAEhE;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAexD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAWhE,CAAC;AAEF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAgBlE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,aAAa,GAAG,MAAM,CAajE"}

package/dist/direction-mappings.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * English-specific direction mappings for the parser
+ * Maps English words and abbreviations to language-agnostic Direction constants
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DirectionAbbreviations = exports.DirectionWords = void 0;
+exports.parseDirection = parseDirection;
+exports.getDirectionWord = getDirectionWord;
+const world_model_1 = require("@sharpee/world-model");
+/**
+ * Map English direction words to Direction constants
+ */
+exports.DirectionWords = {
+    'north': world_model_1.Direction.NORTH,
+    'south': world_model_1.Direction.SOUTH,
+    'east': world_model_1.Direction.EAST,
+    'west': world_model_1.Direction.WEST,
+    'northeast': world_model_1.Direction.NORTHEAST,
+    'northwest': world_model_1.Direction.NORTHWEST,
+    'southeast': world_model_1.Direction.SOUTHEAST,
+    'southwest': world_model_1.Direction.SOUTHWEST,
+    'up': world_model_1.Direction.UP,
+    'down': world_model_1.Direction.DOWN,
+    'in': world_model_1.Direction.IN,
+    'inside': world_model_1.Direction.IN,
+    'out': world_model_1.Direction.OUT,
+    'outside': world_model_1.Direction.OUT
+};
+/**
+ * Map English abbreviations to Direction constants
+ */
+exports.DirectionAbbreviations = {
+    'n': world_model_1.Direction.NORTH,
+    's': world_model_1.Direction.SOUTH,
+    'e': world_model_1.Direction.EAST,
+    'w': world_model_1.Direction.WEST,
+    'ne': world_model_1.Direction.NORTHEAST,
+    'nw': world_model_1.Direction.NORTHWEST,
+    'se': world_model_1.Direction.SOUTHEAST,
+    'sw': world_model_1.Direction.SOUTHWEST,
+    'u': world_model_1.Direction.UP,
+    'd': world_model_1.Direction.DOWN
+};
+/**
+ * Parse an English direction string to a Direction constant
+ * Returns null if the string is not a recognized direction
+ */
+function parseDirection(input) {
+    if (!input)
+        return null;
+    const normalized = input.toLowerCase().trim();
+    // Check abbreviations first (more specific)
+    if (exports.DirectionAbbreviations[normalized]) {
+        return exports.DirectionAbbreviations[normalized];
+    }
+    // Then check full words
+    if (exports.DirectionWords[normalized]) {
+        return exports.DirectionWords[normalized];
+    }
+    return null;
+}
+/**
+ * Get the English word for a Direction constant
+ * Used for display/output
+ */
+function getDirectionWord(direction) {
+    // Find the first matching English word for this direction
+    for (const [word, dir] of Object.entries(exports.DirectionWords)) {
+        if (dir === direction) {
+            // Prefer the primary forms (not 'inside'/'outside')
+            if (direction === world_model_1.Direction.IN && word === 'inside')
+                continue;
+            if (direction === world_model_1.Direction.OUT && word === 'outside')
+                continue;
+            return word;
+        }
+    }
+    // Fallback to lowercase version of constant
+    return direction.toLowerCase();
+}
+//# sourceMappingURL=direction-mappings.js.map

package/dist/direction-mappings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"direction-mappings.js","sourceRoot":"","sources":["../src/direction-mappings.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AA4CH,wCAgBC;AAMD,4CAaC;AA7ED,sDAAgE;AAEhE;;GAEG;AACU,QAAA,cAAc,GAAkC;IAC3D,OAAO,EAAE,uBAAS,CAAC,KAAK;IACxB,OAAO,EAAE,uBAAS,CAAC,KAAK;IACxB,MAAM,EAAE,uBAAS,CAAC,IAAI;IACtB,MAAM,EAAE,uBAAS,CAAC,IAAI;IACtB,WAAW,EAAE,uBAAS,CAAC,SAAS;IAChC,WAAW,EAAE,uBAAS,CAAC,SAAS;IAChC,WAAW,EAAE,uBAAS,CAAC,SAAS;IAChC,WAAW,EAAE,uBAAS,CAAC,SAAS;IAChC,IAAI,EAAE,uBAAS,CAAC,EAAE;IAClB,MAAM,EAAE,uBAAS,CAAC,IAAI;IACtB,IAAI,EAAE,uBAAS,CAAC,EAAE;IAClB,QAAQ,EAAE,uBAAS,CAAC,EAAE;IACtB,KAAK,EAAE,uBAAS,CAAC,GAAG;IACpB,SAAS,EAAE,uBAAS,CAAC,GAAG;CACzB,CAAC;AAEF;;GAEG;AACU,QAAA,sBAAsB,GAAkC;IACnE,GAAG,EAAE,uBAAS,CAAC,KAAK;IACpB,GAAG,EAAE,uBAAS,CAAC,KAAK;IACpB,GAAG,EAAE,uBAAS,CAAC,IAAI;IACnB,GAAG,EAAE,uBAAS,CAAC,IAAI;IACnB,IAAI,EAAE,uBAAS,CAAC,SAAS;IACzB,IAAI,EAAE,uBAAS,CAAC,SAAS;IACzB,IAAI,EAAE,uBAAS,CAAC,SAAS;IACzB,IAAI,EAAE,uBAAS,CAAC,SAAS;IACzB,GAAG,EAAE,uBAAS,CAAC,EAAE;IACjB,GAAG,EAAE,uBAAS,CAAC,IAAI;CACpB,CAAC;AAEF;;;GAGG;AACH,SAAgB,cAAc,CAAC,KAAa;IAC1C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAExB,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;IAE9C,4CAA4C;IAC5C,IAAI,8BAAsB,CAAC,UAAU,CAAC,EAAE,CAAC;QACvC,OAAO,8BAAsB,CAAC,UAAU,CAAC,CAAC;IAC5C,CAAC;IAED,wBAAwB;IACxB,IAAI,sBAAc,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,OAAO,sBAAc,CAAC,UAAU,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,SAAwB;IACvD,0DAA0D;IAC1D,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,sBAAc,CAAC,EAAE,CAAC;QACzD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,oDAAoD;YACpD,IAAI,SAAS,KAAK,uBAAS,CAAC,EAAE,IAAI,IAAI,KAAK,QAAQ;gBAAE,SAAS;YAC9D,IAAI,SAAS,KAAK,uBAAS,CAAC,GAAG,IAAI,IAAI,KAAK,SAAS;gBAAE,SAAS;YAChE,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,4CAA4C;IAC5C,OAAO,SAAS,CAAC,WAAW,EAAE,CAAC;AACjC,CAAC"}

package/dist/english-grammar-engine.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @file English Grammar Engine
+ * @description English-specific implementation of grammar matching
+ */
+import { GrammarEngine, GrammarContext, PatternMatch, GrammarMatchOptions, SlotMatch } from '@sharpee/if-domain';
+import { Token } from '@sharpee/if-domain';
+import { SlotConsumerRegistry } from './slot-consumers';
+import type { PartialMatchFailure } from './parse-failure';
+/**
+ * Result of attempting to match a rule - either success or failure with info
+ */
+export type MatchAttemptResult = {
+    success: true;
+    match: PatternMatch;
+} | {
+    success: false;
+    failure: PartialMatchFailure;
+};
+/**
+ * Extended match options with failure tracking
+ */
+export interface ExtendedMatchOptions extends GrammarMatchOptions {
+    /** If true, collect partial match failures for error reporting */
+    trackFailures?: boolean;
+}
+/**
+ * Result of findMatches with optional failure information
+ */
+export interface MatchResult {
+    matches: PatternMatch[];
+    failures?: PartialMatchFailure[];
+}
+/**
+ * English-specific grammar matching engine
+ */
+export declare class EnglishGrammarEngine extends GrammarEngine {
+    private slotConsumerRegistry;
+    /** Last set of partial match failures (for error reporting) */
+    private lastFailures;
+    constructor(slotConsumerRegistry?: SlotConsumerRegistry);
+    /**
+     * Get the last set of partial match failures (for error reporting)
+     */
+    getLastFailures(): PartialMatchFailure[];
+    /**
+     * Find matching grammar rules for tokens
+     */
+    findMatches(tokens: Token[], context: GrammarContext, options?: GrammarMatchOptions): PatternMatch[];
+    /**
+     * Try to match a single rule against tokens
+     */
+    private tryMatchRule;
+    /**
+     * Try to match a single rule against tokens, returning failure info if no match
+     */
+    private tryMatchRuleWithFailure;
+    /**
+     * Build semantic properties from rule and matched tokens
+     */
+    private buildSemantics;
+    /**
+     * Consume tokens for a slot
+     */
+    private consumeSlot;
+    /**
+     * Extract typed value from a NUMBER slot match
+     */
+    static extractNumberValue(match: SlotMatch): number | null;
+    /**
+     * Extract typed value from an ORDINAL slot match
+     */
+    static extractOrdinalValue(match: SlotMatch): number | null;
+    /**
+     * Extract canonical direction from a DIRECTION slot match
+     */
+    static extractDirectionValue(match: SlotMatch): string | null;
+    /**
+     * Extract time components from a TIME slot match
+     */
+    static extractTimeValue(match: SlotMatch): {
+        hours: number;
+        minutes: number;
+    } | null;
+}
+//# sourceMappingURL=english-grammar-engine.d.ts.map

package/dist/english-grammar-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"english-grammar-engine.d.ts","sourceRoot":"","sources":["../src/english-grammar-engine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,aAAa,EACb,cAAc,EACd,YAAY,EACZ,mBAAmB,EAInB,SAAS,EACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAG3C,OAAO,EAAE,oBAAoB,EAA8C,MAAM,kBAAkB,CAAC;AACpG,OAAO,KAAK,EAAE,mBAAmB,EAAe,MAAM,iBAAiB,CAAC;AAExE;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GACtC;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAC/D,kEAAkE;IAClE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;CAClC;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,aAAa;IACrD,OAAO,CAAC,oBAAoB,CAAuB;IAEnD,+DAA+D;IAC/D,OAAO,CAAC,YAAY,CAA6B;gBAErC,oBAAoB,CAAC,EAAE,oBAAoB;IAMvD;;OAEG;IACH,eAAe,IAAI,mBAAmB,EAAE;IAIxC;;OAEG;IACH,WAAW,CACT,MAAM,EAAE,KAAK,EAAE,EACf,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,mBAAwB,GAChC,YAAY,EAAE;IAyCjB;;OAEG;IACH,OAAO,CAAC,YAAY;IAuKpB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAgN/B;;OAEG;IACH,OAAO,CAAC,cAAc;IAwDtB;;OAEG;IACH,OAAO,CAAC,WAAW;IA6DnB;;OAEG;IACH,MAAM,CAAC,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI;IAkB1D;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI;IAmB3D;;OAEG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI;IAO7D;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAarF"}