Parser Instance API

Methods available on a parser instance returned by createParser().

parse()

Parses a command string and returns a result.

Signature:

parse(input: string, options?: ParseOptions): ParseResult

Parameters:

Returns: ParseResult — A discriminated union indicating the parse outcome.

Example:

const result = parser.parse('get the lamp', {
  scope: {
    room: currentRoom,
    inventory: playerInventory
  }
})

if (result.type === 'command') {
  console.log(result.command.verb)  // "GET"
}

Throws:

• ValidationError — When input exceeds maximum length (1,000,000 characters)

addVerb()

Adds a custom verb definition to this parser instance.

Signature:

addVerb(definition: VerbDefinition): void

Parameters:

Returns: void

Example:

parser.addVerb({
  canonical: 'CAST',
  synonyms: ['cast', 'invoke'],
  pattern: 'subject'
})

const result = parser.parse('cast fireball')
// { type: 'command', command: { verb: 'CAST', ... } }

Notes:

• Added verbs only affect this parser instance
• Does not modify the default vocabulary
• Synonyms must be lowercase

addDirection()

Adds a custom direction definition to this parser instance.

Signature:

addDirection(definition: DirectionDefinition): void

Parameters:

Returns: void

Example:

parser.addDirection({
  canonical: 'PORTAL',
  aliases: ['portal', 'p']
})

const result = parser.parse('portal')
// { type: 'command', command: { verb: 'GO', direction: 'PORTAL' } }

Notes:

• Added directions only affect this parser instance
• Directions can be used alone or with GO
• Aliases must be lowercase

clearPronoun()

Clears the pronoun reference ("it") tracked by this parser.

Signature:

clearPronoun(): void

Returns: void

Example:

parser.parse('get lamp')      // Sets "it" = lamp
parser.parse('examine it')    // Works, examines lamp

parser.clearPronoun()

parser.parse('examine it')    // parse_error: no referent

Notes:

• Pronoun also clears automatically when scope.room changes
• Use this for manual control, e.g., after time passes or scene change

Types

ParseOptions

Options for a single parse operation.

interface ParseOptions {
  scope?: ResolverScope
}

ResolverScope

Scope information passed to the resolver function.

interface ResolverScope {
  room?: unknown
  inventory?: unknown
  [key: string]: unknown
}

Example:

parser.parse('get lamp', {
  scope: {
    room: { id: 'room-1', items: [...] },
    inventory: [...],
    npcPresent: true,
    lightLevel: 'dim'
  }
})

Parser

The parser interface returned by createParser().

interface Parser {
  parse(input: string, options?: ParseOptions): ParseResult
  addVerb(definition: VerbDefinition): void
  addDirection(definition: DirectionDefinition): void
  clearPronoun(): void
}