This module provides support for parsing user input against parse patterns. Patterns allow you to flag certain sections of user input as special. For example, you can flag that certain parts of the input must be a description of an object, or that they must match a particular syntax, or that they may optionally match a particular syntax, etc.

The parsing functionality as a whole is broken down into two phases: parsing and binding. Parsing is responsible for making sure that user input is valid per a parse pattern and for matching user input against any match patterns. The parsing phase does not make any attempt to validate any object descriptions against any actual objects.

Binding is responsible for actually matching an object description against one more objects. It includes support for singular and pural references, as well as cardinal and ordinal numeric modifiers. Binding occurs within a context, which is a list of possible objects that the description may match. Binding succeeds if a description (with specified numeric modifiers applied) matches one or more objects within the context; it fails otherwise.

Parsing occurs through use of the parse function. Binding occurs through the bind function. If you want to do both in a single step, you can use the parseAndBind function.

Tokens in the parse pattern are interpreted as follows:

text                    required word
(text1|text2|...|textN) Require either text1 or text2 or ... or textN
<a href="#text">[text]</a>                  optional word
%o                      match object description
%s                      match string
%a                      match optional adverb

Examples of parsing :

Pattern: "look"
Valid input examples:   "look"
Invalid input examples: "look ball", "look here", "look around"
Pattern: "look (at|toward|towards) <a href="#the">[the]</a> %o"
Valid input examples: "look at ball", "look toward ball",
'                     "look towards ball", "look at the ball",
'                     "look at the balls", "look at both balls",
'                     "look at the third ball"
Invalid input examples: "look", "look at at balls",
'                       "look at all 'em balls!"
Pattern: "get <a href="#the">[the]</a> %o from <a href="#the">[the]</a> %o"
Valid input examples: "get ball from basket", "get the ball from the basket",
'                     "get fifteen balls from the second basket",
'                     "get everything from both baskets"
Invalid input examples: "get ball", "get ball basket", "ball from basket",
'                       "get ball inside basket"
Pattern: "smile %a <a href="#at">[at]</a> [the] %o"
Valid input examples: "smile happily at john", "smile at john",
'                     "smile john", "smile sorrowfully at john"
Invalid input examples: "smile", "smile at john happily"

bind ( matches,  potentialObjectsTuple=None )

bindWithin ( match,  containers )

parse ( pattern,  input )

parseAndBind (
        pattern,
        input,
        potentialObjectsTuple=None,
        )

successful ( results )