pattern for acronyms and numbers

Get the indefinite form of the name, nominative case.

[Required]

pattern for plurals that add apostrophe-s

pattern for apostrophe-s words

regular expression for removing annotations from a short name

class property: the main dictionary StringComparator

The dummyName is a property that displays nothing, for use when we want to use an object in a sentence without actually displaying any text for it (e.g. to provide a subject for a verb to agree with).

The VocabWords list for empty objects. These are words (usually adjectives) that can be applied to an object that can be distinguished from similar objects by its contents ("box of papers", "bucket of water"), for times when it's empty. This is a list of VocabWords objects for matching during parsing.

[Required]

pattern for nouns with -es plurals

The subjective-case pronoun for this object. We'll try to infer the pronoun from the gender and number flags: if plural, 'they'; if isHim, 'he'; if isHer 'she'; otherwise 'it'.

The possessive adjective pronoun for this object. We'll try to infer the pronoun from the gender and number flags: if plural, 'their'; if isHim, 'his'; if isHer, 'her'; otherwise 'its'.

The possessive noun pronoun for this object. We'll try to infer the pronoun from the gender and number flags: if plural, 'theirs'; if isHim, 'his'; if isHer, 'hers'; otherwise 'its'.

The objective-case pronoun for this object. We'll try to infer the pronoun from the gender and number flags: if plural, 'them'; if isHim, 'him'; if isHer 'her'; otherwise 'it'.

pattern for nouns y -> -ies plurals)

lookup table for irregular plurals - we build this at preinit time

Determine the gender of this object

By default an object is neuter if it's neither masculine nor feminine, but that can be overridden in cases where something might be referred to as either 'him' or 'it' for example.

pattern for pulling the last word out of a phrase

pattern for words ending in 'men' (chairman, fireman, etc)

The prepositional phrase for something located inside this object, e.g. 'in the box' or 'on the table

The prepositional phrase for something being moved inside this object, e.g. 'into the box' or 'onto the table

Get the objective form of the name. The regular 'name' property gives the subjective form - i.e., the form that appears as the subject of a verb. 'objName' gives the form that appears as a direct or indirect object. Unlike many languages, English doesn't further distinguish cases for the different roles of verb objects; they're all just "objective". English also doesn't inflect regular nouns at all for these two cases - the objective form of "book" or "key" or "widget" is identical to the subjective form. The only place where case makes a difference in English is pronouns: "I" and "me", "he" and "him", etc. So, this routine simply returns the subjective name string by default, which will work for any object with a regular noun as its name. Generally, this will only need to be overridden for the player character object, which usually uses a pronoun as its name ("you" for a second-person game, "I" for a first-person game).

The pronominal phrase for something leaving this object, e.g. 'out of the box'

Flag, do we want our theName to be constructed from our owner's name, e.g. "Bob's wallet" rather than "the wallet".

pattern for plural annotations

pattern for part-of-speech annotations

Get the possessive adjective-like form of the name. This is the form of the name we use as a qualifier phrase when showing an object we possess. The English rule for ordinary nouns is just to add apostrophe-s to the name: "Bob" becomes "Bob's", "Orc guard" becomes "Orc guard's". This works for nearly all nouns in English, but you can override this if the rule produces the wrong result for a particular name. But if the noun is plural and its name ends with an 's' we should just add an apostrophe - so we do this via the possEnding property.

However, it does vary for pronouns. By default, we check the name to see if it's a pronoun, and apply the correct pronoun mapping if so.

The correct ending for our possessive form. This is usually apostrophe-s for an English noun, except where the noun is plural and ends with an 's', which case we just want an apostrophe; for example "the clerks' lunch" but "the women's dinner".

Get the possessive noun-like form of the name. This is the form of the possessive we use in a genetive "of" phrase or a "being" predicate, such as "that's a book of Bob's" or "that book is Bob's". In English, this is almost always identical to the possessive adjective form for a regular noun - it's just the same apostrophe-s word as the adjective form.

However, it diverges for some of the pronouns: "my" vs "mine", "her" vs "hers", "their" vs "theirs", "our" vs "ours". We check the name to see if it's a pronoun, and apply the appropriate pronoun mapping if so.

preposition list, as a regular expression OR pattern

if we need to add 's as the plural ending - this should be either a simple straight quote ('\''), or HTML markup for a curly quote regular expression for separating the main phrase and prepositional phrase from a "noun prep noun" phrase

Regular expression pattern for matching a single preposition word. A word is a preposition if it's in our preposition list, OR it's annotated explicitly with "[prep]" at the end.

class property: pronoun lookup table (built during preinit)

pattern for detecting a proper name - each word starts with a capital letter

pattern for proper nouns: starts with a capital, and at least one lower-case letter within

The reflexive name as a pronoun, e.g. himself, herself, itself

lookup table of special-case a/an words (we build this automatically during classInit from CustomVocab objects)

pre-compile some regular expressions for aName

The demonstrative pronoun for this object, nominative case. For a singular gendered object, or a first- or second-person object, we'll use the regular pronoun (I, you, he, her). For any other singular object, we'll use 'that', and for plural, 'those'.

The demonstrative pronoun, objective case. For a singular gendered object, or a first- or second-person object, we'll use the regular pronoun (me, you, him, her). For any other singular object, we'll use 'that', and for plural, 'those'.

Get the definite form of the name, nominative case.

[Required]

Definite name, objective case.

regular expression for trimming leading and trailing spaces

class property: the truncation length to use for the main dictionary StringComparator.

Add a word to the dictionary and to our vocabulary list for the given match flags.

Add additional vocab words to those already in use for this object. If we specify the name part this will replace the existing name for the object.

Apply an indefinite article ("a box", "an orange", "some lint") to the given name string 'str' for this object. We'll try to figure out which indefinite article to use based on what kind of noun phrase we use for our name (singular, plural, or a "mass noun" like "lint"), and our spelling.

By default, we'll use the article "a" if the name starts with a consonant, or "an" if it starts with a vowel.

If the name starts with a "y", we'll look at the second letter; if it's a consonant, we'll use "an", otherwise "a" (hence "an yttrium block" but "a yellow brick").

If the object is marked as a mass noun or having plural usage, we will use "some" as the article ("some water", "some shrubs"). If the string has a possessive qualifier, we'll make that "some of" instead ("some of Bob's water").

Some objects will want to override the default behavior, because the lexical rules about when to use "a" and "an" are not without exception. For example, silent-"h" words ("honor") are written with "an", and "h" words with a pronounced but weakly stressed initial "h" are sometimes used with "an" ("an historian"). Also, some 'y' words might not follow the generic 'y' rule.

'U' words are especially likely not to follow any lexical rule - any 'u' word that sounds like it starts with 'y' should use 'a' rather than 'an', but there's no good way to figure that out just looking at the spelling (consider "unassuming", " unimportant word", or "a unanimous decision" and "an unassuming man"). We simply always use 'an' for a word starting with 'u', but this will have to be overridden when the 'u' sounds like 'y'.

Get the indefinite name for a version of our name that has a possessive qualifier. The caller is responsible for ensuring that the possessive is already in a suitable format for adding an indefinite article - usually something like "book of Bob's", so that we can turn this into "a book of Bob's".

In English, there's a special case where the regular indefinite name format differs from the possessive format, which is why we need this separate method in the English module. Specifically, if the basic name is a plural or mass noun, we have to use "some of" in the possessive case, rather than the usual "some": "some water" in the normal case, but "some of Bob's water" in the possessive case.

Class initialization. The library calls this at preinit time, before calling construct() on any instances, to set up any pre-built tables in the class. There's no required implementation here - this is purely for the language module's convenience to do any initial set-up work.

For the English version, we take the opportunity to set up the main parser Dictionary object, and initialize the plural table. The plural table is a lookup table we build from the plural list, for quicker access during execution.

[Required]

Apply a contents qualifier to the name for my container. 'obj' is the object (my container), and 'str' is the name under construction. We'll add the appropriate prepositional phrase: "the bucket OF WATER".

Generate the "distinguished name" for this object, given a list of Distinguisher objects that we're using to tell it apart from others in a list.

'article' indicates which kind of article to use: Definite ("the"), Indefinite ("a", "an", "some"), or nil (no article). 'distinguishers' is a list of Distinguisher object that are being used to identify this object uniquely. Our job is to elaborate the object's name with all of the qualifying phrases implied by the distinguishers.

[Required]

Pronoun-or-name mapper. If our name is a pronoun, return the given pronoun name property. Otherwise return the given name string.

Inherit vocab from our superclasses according to the following scheme:
1. A + sign in the name section will be replaced with the name from our superclass.
2 Unless the adjective and nouns section start with a -, any adjectives and nouns from our superclasses vocab will be added to the respective section.
3 If our pronouns section is empty or contains a +, inherit pronouns from our superclass, otherwise leave it unchanged.

initVocab() - Parse the 'vocab' string. This is called during preinit and on dynamically constructing a new Mentionable, to initialize up the object's vocabulary for use by the parser.

The vocab string is designed to make it as quick and easy as possible to define an object's name and vocabulary. To the extent possible, we derive the vocabulary from the name, so for many objects the whole definition will just look like the object name. However, we also make it possible to define as much extra vocabulary beyond the name as needed, and to control the way the words making up the name are handled in terms of their parts of speech.

The 'vocab' string has this overall syntax:

vocab = 'article short name; adjectives; nouns; pronouns'

You don't have to include all of the parts; you can simply stop when you're done, so it's valid, for example, to just write the 'short name' part. It's also fine to include an empty part: if you have extra nouns to list, but no adjectives, you can say 'short name;;nouns'.

The 'article' is optional. This can be one of 'a', 'an', 'some', or '()'. If it's 'a' or 'an', and this differs from what we'd automatically generate based on the first word of the short name, we automatically enter the first word into the list of special cases for a/an words. If it's 'some', we automatically set massNoun=true for the object. If it's '-', we set qualified=true ('()' means that the name doesn't take an article at all).

Note that if you want to use 'a', 'an', 'some', or '()' as the first word of the actual short name, you simply need to add the desired article in front of it: 'an a tile from a scrabble set'.

The short name gives name that we display whenever the parser needs to show the object in a list, an announcement, etc.

If the short name consists entirely of capitalized words (that is, if every word starts with a capital letter), and the 'proper' property isn't explicitly set for this object, we'll set 'proper' to true to indicate that this is a proper name.

We also try to infer the object's vocabulary words from the short name. We first break off any prepositional phrases, if we see the prepositions 'to', 'of', 'from', 'with', or 'for'. We then assume that the FIRST phrase is of the form 'adj adj adj... noun' - that is, zero or more adjectives followed by a noun; and that the SECOND and subsequent phrases are entirely adjectives. You can override the part-of-speech inference by putting the actual part of speech immediately after a word (with no spaces) in square brackets: 'John[n] Smith' overrides the assumption that 'John' is an adjective. Use [n] to make a word a noun, [adj] to make it an adjective, [prep] to make it a preposition, and [pl] to make it a plural. You can also add [weak] to make it a weak token (one on which the object won't be matched alone), or equivalently, enclose the word in parentheses. These annotations are stripped out of the name when it's displayed.

We consider ALL of the words in the short name's second and subsequent phrases (the prepositional phrases) to be adjectives, except for the preposition words themselves, which we consider to be prepositions. This is because these phrases all effectively qualify the main phrase, so we don't consider them as "important" to the object's name. This helps the parser be smarter about disambiguation, without bothering the user with clarifying questions all the time. When the player types "garage", we'll match the "key to the garage" object as well as the "garage" object, but if both objects are present, we'll know to choose the garage over the key because the noun usage is a better match to what the user typed.

We automatically ignore articles (a, an, the, and some) as vocabulary words when they immediately follow prepositions in the short name. For example, in 'key to the garage', we omit 'the' as a vocabulary word for the object because it immediately follows 'to'. We also omit 'to', since we don't enter the prepositions as vocabulary. We do the complementary work on parsing, by ignoring these words when we see them in the command input in the proper positions. These words are really structural parts of the grammar rather than parts of the object names, so the parser can do a better job of recognizing noun phrases by considering the grammatical functions of these words.

For many (if not most) objects, the short name won't be enough to state all of the vocabulary words you want to recognize for the object in command input. Trying to cram every possible vocabulary word into the short name would usually make for an unwieldy display name. Fortunately, it's easy to add input vocabulary words that aren't displayed in the name. Just add a semicolon, then the adjectives, then another semicolon, then the nouns.

Note that there's no section for adding extra prepositions, but you can still add them. Put the prepositions in the adjective list, and explicitly annotate each one as a preposition by adding "[prep]" at the end, as in "to[prep]".

Next, there's the matter of plurals. For each noun, we'll try to automatically infer a plural according to the spelling pattern. We also have a table of common irregular plurals that we'll apply. For irregular words that aren't in the table, you can override the spelling-based plural by putting the real plural in braces immediately after the noun, with no spaces. Start with a hyphen to specify a suffix; otherwise just write the entire plural word. For example, you could write 'man{men}' or 'child{-ren}' (although these particular irregular plurals are already in our special-case list, so the custom plurals aren't actually needed in these cases). You can use plural annotations in the short name as well as the extra noun list; they'll be removed from the short name when it's displayed. We don't try to generate a plural for a proper noun (a noun that starts with a capital letter), but you can provide explicit plurals.

For words longer than the truncation length in the string comparator, you can set the word to match exactly by adding '=' as the last character. This also requires exact character matching, rather than allowing accented character approximations (e.g., matching 'a' in the input to 'a-umlaut' in the dictionary).

We automatically assume that plurals should be matched without truncation. This is because English plurals are usually formed with suffixes; if the user wants to enter a plural, they'll have to type the whole word anyway, because that's the only way you make it all the way to the suffix. You can override this assumption for a given plural by adding '~' at the end of the plural. This explicitly allows truncated and character approximation matches.

Finally, the 'pronouns' section gives a list of the pronouns that this word can match. You can include 'it', 'him', 'her', and 'them' in this section. We'll automatically set the isIt, isHim, isHer, and plural properties to true when we see the corresponding pronouns.

[Required]

Initialize vocabulary for one word from the 'vocab' list. 'w' is the word text, with optional part-of-speech and plural-form annotations ([n], [adj], [prep], [pl], (-s)). It can also have a special flag character as its final character: '=' for an exact match (no truncation and no character approximations), or '~' for fuzzy matches (truncation and approximation allowed).

'matchFlags' is a combination of MatchXxx values. This should minimally provide the part of speech as one of MatchAdj, MatchNoun, or MatchPlural. You can also include MatchNoTrunc to specify that user input can only match this word without any truncation, and MatchNoApprox to specify that input can only match without character approximations (e.g., 'a' matching 'a-umlaut').

Apply a locational qualifier to the name for an object contained within me. 'obj' is the object (something among my contents), and 'str' is the name under construction. We'll add the appropriate prepositional phrase: "the box UNDER THE TABLE".

Match a pronoun. This returns true if this object is a valid antecedent for this pronoun grammatically: that is, it matches the pronoun in gender, number, and any other attributes the pronoun carries.

English pronouns have gender and number. (Some other languages have other attributes, such as animation - whether or not they refer to living creatures.)

This routine doesn't tell us if the object is a *current* antecedent for the pronoun. The current antecedent is a function of the command history. This routine only tells us whether this object is a match in terms of grammatical attributes for the pronoun.

Note that this routine can and should ignore first-person and second-person pronouns. Those pronouns are relative to the speaker, so the parser handles them directly.

[Required]

Get the plural form of the given name. If the string ends in vowel-plus-'y' or anything other than 'y', we'll add an 's'; otherwise we'll replace the 'y' with 'ies'. We also handle abbreviations and individual letters specially.

This can only deal with simple adjective-noun forms. For more complicated forms, particularly for compound words, it must be overridden (e.g., "Attorney General" -> "Attorneys General", "man-of-war" -> "men-of-war"). We recognize a fairly extensive set of special cases (child -> children, man -> men), as listed in the irregularPlural lists in any CustomVocab objects. Add new items to the irregular plural list by creating one or more CustomVocab objects with their own irregularPlural lists.

Get the plural of the given word. If there's an irregular plural entry for the word, we return that; otherwise we infer the plural from the spelling. 'apost' is the string to use for an apostrophe ('’').

Generate a possessive name for an object that we own, given a string under construction for the object's name. 'obj' is the object we're possessing ('self' is the owner), and 'str' is the name string under construction, without any possessive or article qualifiers yet.

Note that we must add to 'str', not the base name of the object. We might be using a variation on the name (such as the disambiguation name), or we might have already adorned the name with other qualifiers.

'article' specifies the usage: Definite, Indefinite, or nil for no article. We DON'T actually add the article here; rather, this tells us the form that the name will take when the caller is done with it, so we should use a suitable form of the possessive phrasing to the extent it varies by article. In English, it does vary. In the Definite case, the possessive effectively replaces the article: "the book" becomes "Bob's book". In the Indefinite case, the possessive has to be rephrased prepositionally so that the article can still be included: "a book" becomes "a book of Bob's". Mass nouns are a further special case: "some water" becomes "some of Bob's water".

The default behavior is as follows. In Definite mode, we return "<name>'s <string>". In Indefinite mode, we return "<string> of <name>" (for a final result like "a book of Bob's").

Get the pronoun to use for this object. This returns the Pronoun object suitable for representing this object in a generated message.

[Required]

Remove a word from this object's vocabulary. If the matchFlags parameter is supplied it should be one of MatchNoun, MatchAdj, MatchPrep or MatchPlural, in which case only VocabWords matching the corresponding part of speech (as well as word) will be removed.

reinitialize the vocab of this object from scratch, using the string voc in place of the original vocab property.

Get the definite form of the name, given the name string under construction. The English default is "the <name>", unless the object is already qualified, in which case it's just the base name. If, however, we're ownerNamed and we have a nominalOwner, return our owner's possessive adjective followed by our name (e.g. "Bob's wallet").

The name with a definite article (or just the proper or qualified name) followed by the appropriate form of the verb 'to be'. This can be useful for producing sentences of which this object is the subject.