throw new AbortImplicitSignal()
a concise macro to throw an AbortImplicitSignal

{ \
preCond { return curState.preCond##obj##Action; } \
verify() { curState.verify##obj##Action; } \
remap() { return curState.remap##obj##Action; } \
check() { curState.check##obj##Action; } \
action() { curState.action##obj##Action; } \
}
For an Actor, delegate an action handler to the ActorState object for processing. You can use this any time you want to write the handlers for a particular action in the ActorState rather than in the Actor itself. This would be desirable if the actor's response for a particular action varies considerably according to the actor's state. For example, if you want an actor's response to being attacked to be handled in the actor's current ActorState object, you could put this code in the Actor object:

dobjFor(AttackWith) actorStateDobjFor(AttackWith)

Once you've done this, you'd just write a normal dobjFor(AttackWith) handler in each of the ActorState objects associated with the actor.

0x0001 /* plain text hyperlink (no underline/color) */
aHref() flags

0x0010
Always announce the object before executing the command on it. This flag can be set for objects that match phrases whose meaning isn't necessarily known to the player, such as "all" (which selects objects based on the simulation state, which might not exactly match what the player had in mind) or "any book" (which might select arbitrarily from several possibilities, so the player can't know which we'll choose).

0x0100
We've announced this as a defaulted object. We use this to ensure that we only make this type of announcement once, even if the opportunity to make the announcement comes up more than once; this can happen when we're asking for missing objects interactively in a multi-object command, since we might want to announce a default before prompting as well as before execution.

= static ((dir).createUnlistedProxy())
Alternative exit definition. This can be used to define a secondary direction that links to the same destination, via the same connector, as another direction. It's frequently desirable to link multiple directions to the same exit; for example, a door leading north might also lead out, or a stairway to the north could lead up as well.

Use this as follows in a room's property list:

out asExit(north)

(Note that there's no '=' sign.)

It's not necessary to use this macro to declare an alternative exit, since the alternatives can all point directly to the same connector as the original. The only thing this macro does is to make the alternative exit unlisted - it won't be shown in the list of exits in the status line, and it won't be shown in "you can't go that way" messages.

Note that there's one common case where you should be careful with asExit(): if you have a room that has an exit in some compass direction, you might be tempted to make OUT the primary "direction" for the exit, and treat the equivalent compass as a synonym, with a line such as "south asExit(out)". You should avoid doing this - do it the other way instead, with the compass direction as the primary direction and OUT as the synonym: "out asExit(south)". The reason this is important is that if there's a nested room inside the location (such as a chair), OUT while in the nested room will mean to get out of the nested room. If you make the compass direction primary and make OUT the synonym, the compass direction will be listed as an available exit both in the location and in any nested rooms within it.

(newAction##Action.retryWithMissingDobj(gAction, ResolveAsker))
Ask for a direct object and retry the command using the single-object phrasing. This can be used in the action() routine for a no-object command to ask for the missing direct object.

In many cases, there is simply no grammar rule for a zero-object form of a verb; in such cases, this macro is not needed, since the missing object is handled via the grammar. However, for some actions, it is desirable to allow the zero-object phrasing some of the time, but require the direct-object phrasing other times. This macro exists for these cases, because it allows the intransitive version of the action to decide, on a case-by-case basis, whether to process the no-object form of the command or to prompt for a direct object.

newAction is the root name (without the Action suffix) of the transitive action to execute. For example, if we're processing a plain "in" command, we could use askForDobj(Enter) to ask for a direct object for the transitive "enter" phrasing.

(newAction##Action.retryWithMissingIobj(gAction, ResolveAsker))
Ask for an indirect object and retry the command using the two-object phrasing. This can be used in the action() routine of a single-object command to ask for the missing indirect object.

In many cases, there is simply no grammar rule for a single-object form of a verb; in such cases, this macro is not needed, since the missing object is handled via the grammar. However, for some actions, it is desirable to allow the single-object phrasing some of the time, but require the two-object phrasing other times. This macro exists for these cases, because it allows the action() routine to decide, on a case-by-case basis, whether to process the single-object form of the command or to prompt for an indirect object.

newAction is the root name (without the Action suffix) of the two-object form of the action. For example, if we're processing a single-object "unlock" command, we would use askForIobj(UnlockWith) to ask for an indirect object for the "unlock with" two-object phrasing.

(newAction##Action.retryWithMissingLiteral(gAction))
Ask for a literal phrase and retry the command using the two-object phrasing. This is analogous to askForDobj() and askForIobj(), but for literal phrases; we effectively convert a TAction into a LiteralTAction.

(newAction##Action.retryWithMissingTopic(gAction))
Ask for a topic phrase and retry the command using the two-object phrasing.

{ \
preCond { return preCond##obj##Action; } \
verify() { verify##obj##Action; } \
remap() { return remap##obj##Action; } \
check() { check##obj##Action; } \
action() { action##obj##Action; } \
}
Treat an object definition as equivalent to another object definition. These can be used immediately after a dobjFor() or iobjFor() to treat the first action as though it were the second. So, if the player types "search box", and we want to treat the direct object the same as for "look in box", we could make this definition for the box:

dobjFor(Search) asDobjFor(LookIn)

Note that no semicolon is needed after this definition, and that this definition is completely in lieu of a regular property set for the object action.

In general, a mapping should NOT change the role of an object: dobjFor(X) should not usually be mapped using asIobjFor(Y), and iobjFor(X) shouldn't be mapped using asDobjFor(Y). The problem with changing the role is that the handler routines often assume that the object is actually in the role for which the handler was written; a verify handler might refer to '{dobj}' in generating a message, for example, so reversing the roles would give the wrong object in the role.

Role reversals should always be avoided, but can be used if necessary under conditions where all of the code involved in the TARGET of the mapping can be carefully controlled to ensure that it doesn't make assumptions about object roles, but only references 'self'. Reversing roles in a mapping should never be attempted in general-purpose library code, because code based on the library could override the target of the role-reversing mapping, and the override could fail to observe the restrictions on object role references.

Note that role reversals can almost always be handled with other mechanisms that handle reversals cleanly. Always consider remapTo() first when confronted with a situation that seems to call for a role-reversing asObjFor() mapping, as remapTo() specifically allows for object role changes.

{ \
preCond { return preCond##obj##Action; } \
verify() { verify##obj##Action; } \
remap() { return remap##obj##Action(); } \
check() { check##obj##Action; } \
action() { } \
}
Define mappings of everything except the action. This can be used in cases where we want to pick up the verification, preconditions, and check routines from another handler, but not the action. This is often useful for two-object verbs where the action processing is entirely provided by one or the other object, so applying it to both would be redundant.

DefineAction(name, cls) \
verDobjProp = &verifyDobj##name \
remapDobjProp = &remapDobj##name \
preCondDobjProp = &preCondDobj##name \
checkDobjProp = &checkDobj##name \
actionDobjProp = &actionDobj##name \
whichMessageTopic = which
Define a concrete TopicTAction, given the root name for the action. 'which' gives the role the topic serves, for message generation purposes - this should be one of the object role enums (DirectObject, IndirectObject, etc) indicating which role the topic plays in the action's grammar.

propInherited(targetprop, targetobj, definingobj, PropDefAny)
canInherit - determine if there's anything to inherit from the current method. Returns true if there's a method to inherit, nil if 'inherited' in the current context would not invoke any code.

0x0020
The noun phrase describing this object was ambiguous, and the object was selected by automatic disambiguation in a context where it was clear which object was indicated. This is used in cases where the objects not selected were all illogical for the action context.

(gTranscript.addReport(new CosmeticSpacingCommandReport(msg, ##params)))
Add an cosmetic internal spacing report. This type of report is used to show spacing (usually a paragraph break) within command output.

The important thing about this report is that it doesn't trigger suppression of any default reports. This is useful when internal separation is added on speculation that there might be some reports to separate, but without certainty that there will actually be any reports shown; for example, when preparing to show a list of special descriptions, we might add some spacing just in case some special descriptions will be shown, saving the trouble of checking to see if anything actually needs to be shown.

(gVerifyResults.addResult(new DangerousVerifyResult('')))
command is logical but dangerous

showGrammarList(lst)
Define some convenience macros for parser debug operations. When PARSER_DEBUG isn't defined, these macros expand out to nothing.

(gTranscript.addReport(new DefaultDescCommandReport(msg, ##params)))
Set a default descriptive report for the current command. This report will be shown unless any other report is shown for the same command. This differs from defaultReport in that we don't suppress a default description for an implied command: we only suppress a default description when there are other reports for the same command.

The purpose of the default descriptive report is to generate reports that say things along the lines that there's nothing special to describe. For example:

>x desk
You see nothing special about it.

>look in alcove
There's nothing in the alcove.

When there's nothing else to report, these default descriptions are suitable as the full response to the command. However, they become undesirable when we have other "status" information or related special descriptions to display; consider:

>x desk
You see nothing special about it.
Someone has jabbed a dagger into the top of the desk.

>look in alcove
There's nothing in the alcove.
A vase is displayed in the alcove.

>x bag
You see nothing special about it. It's open, and it contains
a red book, an iron key, and a brass key.

In the first two examples above, we have special descriptions for objects contained in the objects being described. The special descriptions essentially contradict the default descriptions' claims that there's nothing special to mention, and also render the default descriptions unnecessary, in that it would be enough to show just the special descriptions. The third example above is similar, but the extra information is status information for the object being described rather than a special description of a contained item; as with the other examples, the generic default description is both contradictory and unnecessary.

Default description reports should ONLY be used for messages that have the character of the examples above: generic descriptions that indicate explicitly that there's nothing special to report. Messages that offer any sort of descriptive detail should NOT be generated as default description reports, because it is suitable and desirable to retain an actual descriptive message even when other status information or related special descriptions are also shown.

0x0080
The noun phrase was missing from the command and this object was supplied as an implicit default.

(gTranscript.addReport(new DefaultCommandReport(msg, ##params)))
Set a default report for the current command. This report will be shown unless a non-default report is issued, or if the default report is to be suppressed (for example, because the command is being performed implicitly as part of another command).

Default reports should be used only for simple acknowledgments of the command's successful completion - things like "Taken" or "Dropped" or "Done."

Default responses are suppressed for implicit commands because they are redundant. When a command is performed implicitly, it is conventional to mention the command being performed with a parenthetical: "(First taking the book)". In such cases, a simple acknowledgment that the command was successfully performed would add nothing of use but would merely make the output more verbose, so we omit it.

class name##Action: ##baseClass \
baseActionClass = name##Action
Define an action with the given base class. This adds the *Action suffix to the given root name, and defines a class with the given base class. We also define the baseActionClass property to refer to myself; this is the canonical class representing the action for all subclasses. This information is useful because a language module might define several grammar rule subclasses for the given class; this lets us relate any instances of those various subclasses back to this same canonical class for the action if necessary.

DefineAction(name, ConvIAction)
define a conversational IAction, such as Hello, Goodbye, Yes, No

BaseDefineTopicTAction(name, which, ConvTopicTAction)
Define a concrete ConvTopicTAction. This is just like defining a TopicTAction, but defines the action using the ConvTopicTAction subclass.

DefineAction(name, IAction)
Define a concrete IAction, given the root name for the action. We'll automatically generate a class with name XxxAction.

DefineAction(name, LiteralAction)
Define a concrete LiteralAction, given the root name for the action.

DefineAction(name, LiteralTAction) \
verDobjProp = &verifyDobj##name \
remapDobjProp = &remapDobj##name \
preCondDobjProp = &preCondDobj##name \
checkDobjProp = &checkDobj##name \
actionDobjProp = &actionDobj##name \
whichMessageLiteral = which
Define a concrete LiteralTAction, given the root name for the action. 'which' gives the role the literal phrase serves, for message generation purposes - this should be one of the object role enums (DirectObject, IndirectObject, etc) indicating which role the topic plays in the action's grammar.

DefineAction(name, SystemAction)
Define a "system" action. System actions are meta-game commands, such as SAVE and QUIT, that generally operate the user interface and are not part of the game world.

DefineTActionSub(name, TAction)
Define a concrete TAction, given the root name for the action. We'll automatically generate a class with name XxxAction, a verProp with name verXxx, a checkProp with name checkXxx, and an actionProp with name actionDobjXxx.

DefineAction(name, cls) \
verDobjProp = &verifyDobj##name \
remapDobjProp = &remapDobj##name \
preCondDobjProp = &preCondDobj##name \
checkDobjProp = &checkDobj##name \
actionDobjProp = &actionDobj##name \

Define a concrete TAction with a specific base class.

DefineTIActionSub(name, TIAction)
Define a concrete TIAction, given the root name for the action. We'll automatically generate a class with name XxxAction, a verDobjProp with name verDobjXxx, a verIobjProp with name verIobjxxx, a checkDobjProp with name checkDobjXxx, a checkIobjProp with name checkIobjXxx, an actionDobjProp with name actionDobjXxx, and an actionIobjProp with name actionIobjXxx.

DefineAction(name, cls) \
verDobjProp = &verifyDobj##name \
verIobjProp = &verifyIobj##name \
remapDobjProp = &remapDobj##name \
remapIobjProp = &remapIobj##name \
preCondDobjProp = &preCondDobj##name \
preCondIobjProp = &preCondIobj##name \
checkDobjProp = &checkDobj##name \
checkIobjProp = &checkIobj##name \
actionDobjProp = &actionDobj##name \
actionIobjProp = &actionIobj##name
Define a concrete TIAction with a specific base class.

DefineAction(name, TopicAction)
Define a concrete TopicAction, given the root name for the action.

0x0002
Explicitly use a comma/period to separate digit groups, overriding the current languageGlobals setting.

0x0001
Use a group separator character between digit groups, using the default setting in languageGlobals.

(gDobj == self ? msg : nil)
Thing message property overrides sometimes need to be selective about the role of the object. These macros let you specify that a Thing message override is only in effect when the Thing is the direct or indirect object. When the object isn't in the specified role, the message override will be ignored.

For example, suppose you want to override an object's response to PUT IN, but *only* when it's the indirect object of PUT IN - *not* when the object is itself being put somewhere. To do this, you could give the object a property like this:

notAContainerMsg = iobjMsg('The vase\'s opening is too small. ')

This specifies that when the object is involved in a PUT IN command that fails with the 'notAContainerMsg' message, the given message should be used - but *only* when the object is the indirect object.

0x0001
the noun phrase ends with an adjective

throw new ExitSignal()
a concise macro to throw an ExitSignal

throw new ExitActionSignal()
a concise macro to throw an ExitActionSignal

(gTranscript.addReport(new ExtraCommandReport(msg, ##params)))
Add an "extra" report. This is an incidental message that doesn't affect the display of a default report.

1
"Person" indices. We define these as numbers rather than enums so that we can easily use these as list indices.

(libGlobal.curAction)
the Action object of the command being executed

(gAction != nil \
&& (action#foreach/gAction.actionOfKind(action##Action)/||/))
is the current global action ANY of the specified actions?

(gAction != nil && gAction.actionOfKind(action##Action))
Determine if the current global action is the specified action. Only the action prefix is needed - so use "Take" rather than "TakeAction" here.

This tests to see if the current global action is an instance of the given action class - we test that it's an instance rather than the action class itself because the parser creates an instance of the action when it matches the action's syntax.

(libGlobal.curActor)
the actor performing the current command

(gAction.getDobj())
For convenience, define some macros that return the current direct and indirect objects from the current action. The library only uses direct and indirect objects, so games that define additional command objects will have to add their own similar macros for those.

(libGlobal.exitListerObj)
the exit lister object - if the exits module isn't included in the game, this will be nil

(libGlobal.hintManagerObj)
the hint manager object - if the hints module isn't included in the game, this will be nil

(libGlobal.curIssuingActor)
the actor who *issued* the current command (this is usually the player character, because most commands are initiated by the player on the command line, but it is also possible for one actor to send a command to another programmatically)

(libGlobal.libMessageObj)
The current library messages object. This is the source object for messages that don't logically relate to the actor carrying out the comamand. It's mostly used for meta-command replies, and for text fragments that are used to construct descriptions.

This message object isn't generally used for parser messages or action replies - most of those come from the objects given by the current actor's getParserMessageObj() or getActionMessageObj(), respectively.

By default, this is set to libMessages. The library never changes this itself, but a game can change this if it wants to switch to a new set of messages during a game. (If you don't need to change messages during a game, but simply want to customize some of the default messages, you don't need to set this variable - you can simply use 'modify libMessages' instead. This variable is designed for cases where you want to *dynamically* change the standard messages during the game.)

(gAction.getLiteral())
get the current literal phrase text, when the command has one

(gAction.setMessageParams(var#foreach/#@var, var/,/))
Some message processors add their own special parameters to messages, because they want to use expansion parameters (in the "{the dobj/him}" format) outside of the set of objects directly involved in the command.

The Action method setMessageParam() lets you define such a parameter, but for convenience, we define this macro for setting one or more parameters whose names exactly match their local variable names. In other words, if you call this macro like this:

gMessageParams(obj, cont)

then you'll get one parameter with the text name 'obj' whose expansion will be the value of the local variable obj, and another with text name 'cont' whose expansion is the value of the local variable cont.

(libGlobal.playerChar)
get the current player character Actor object

(conversationManager.setRevealed(key))
reveal a topic key, as though through <.reveal>

(conversationManager.revealedNameTab[key] != nil)
has a topic key been revealed through <.reveal>?

(gPlayerChar.setKnowsAbout(obj))
mark a Topic/Thing as known/seen by the player character

(gAction.synthMessageParam(var))
Synthesize a global message parameter name for the given object and return the synthesized name. This is useful in cases where there might be repeated instances of global message parameters in the same action, so it's not safe to use a fixed name string for the object. We'll create a unique global message parameter name, associate the object with the name, and return the name string.

(gAction.getTentativeDobj())
The tentative pre-resolution lists for the direct and indirect objects. When we're resolving an object of a multi-object command, these pre-resolution lists are available for the later-resolved objects.

Note that these values are list of ResolveInfo objects. The obj_ property of a list entry gives the entry's game-world object.

These lists do not provide the final resolution lists for the objects; rather, they provide a tentative set of possibilities based on the information that's available without knowing the results of resolving the earlier-resolved objects yet.

These are not meaningful when resolving single-object actions.

(gAction.getTopic())
Get the current ResolvedTopic, and the literal text of the topic phrase as the user typed it (but converted to lower case). These are applicable when the current action has a topic phrase.

(mainOutputStream.curTranscript)
the command transcript object - this is valid during command execution

(libGlobal.curVerifyResults)
the verification results object - this is valid during verification

(gVerifyResults.addResult(new IllogicalVerifyResult(msg, ##params)))
command is always illogical

(gVerifyResults.addResult( \
new IllogicalAlreadyVerifyResult(msg, ##params)))
illogical because things are already as the command would make them

(gVerifyResults.addResult(new IllogicalNowVerifyResult(msg, ##params)))
command is currently (but not always) illogical, for the given reason

(gVerifyResults.addResult(new IllogicalSelfVerifyResult(msg, ##params)))
illogical since we're trying to use something on itself (eg, PUT X IN X)

(gVerifyResults.addResult(new InaccessibleVerifyResult(msg, ##params)))
command is being performed on an inaccessible object

0x0008
This is a recursive listing of the contents of an item. This is set by showList() in calls it makes to recursive listing levels.

0x0100
Custom option bits. Flag bits with this value and higher are reserved for use by individual lister subclasses.

To ensure compatibility with any future changes that involve adding more base lister flags, subclasses are encouraged to use the following mechanism. DO NOT use #define to define your own custom subclass flags. Instead, define a property of your lister subclass for each flag you need as follows:

myCustomFlag1 = ListerCustomFlag(1) // use 1 for the first flag
myCustomFlag2 = ListerCustomFlag(2) // etc
nextCustomFlag = ListerCustomFlag(3)

You DO NOT have to use the name 'myCustomFlag1' - use whatever name you like that describes the nature of the flag. However, the last item MUST be called 'nextCustomFlag' - this ensures that any subclasses of your class will allocate their own flags with new values that don't conflict with any of yours.

Then, when a client of your Lister subclass needs to pass one of your flag to the Lister, it should simply evaluate your 'myCustomFlagN' property of your lister. If you'd like, you can even #define a ListXxx macro that retrieves the value, for the convenience of your callers:

#define ListMyclassMyCustomFlag1 (Myclass.myCustomFlag1)

0x0004
use "long list" notation - separates items that contain sublists with special punctuation, to set off the individual items in the longer listing from the items in the sublists (for example, separates items with semicolons rather than commas)

0x0002
Recursively list the contents of each item we list.

For a 'tall' list, this indicates that we'll show the listed contents of each item that we list, and the listed contents of those items, and so on, indenting each level to indicate the containment relationship.

For a 'wide' list, this indicates that we'll show the listed contents of each item in-line in the listing, as a parenthetic note.

For both types of listings, when this flag is set and the indent level is zero (indicating a top-level listing), after the main list, we'll show a separate list for the contents of each item in our list that isn't itself listable but has listed contents, or has contents with listed contents, and so on to any level. For example, if we're showing a room description, and the room contains a desk that isn't listed because it's a fixed part of the room, we'll show a separate list of the desk's listed contents.

0x0001
use "tall" notation, which lists objects in a single column, one item per line (the default is "wide" notation, which creates a sentence with the object listing)

(gVerifyResults.addResult(new LogicalVerifyResult(100, '', 100)))
Command is logical. There's generally no need to add a logical result explicitly, since a command is logical unless disapproved, but we include this for completeness.

We use 100 as the default likelihood, to leave plenty of room for specific likelihood rankings both above and below the default level.

(gVerifyResults.addResult(new LogicalVerifyResult(rank, key, 100)))
Command is logical, and is ranked as indicated among logical results. The 'rank' value is the likelihood rank; the higher the rank, the more logical the command is. The rank is only used to establish an ordering of the logical results; if a command also has illogical results, all of the illogical results rank as less logical than the logical result with the lowest likelihood.

The 'key' value is an arbitrary string value associated with the ranking. When two result lists both have a logical result object, and both logical result objects have the same likelihood level, we'll check the keys; if the keys match, we'll treat the two results as equivalent and thus not distinguishing for disambiguation. This is useful because it creates a crude multivariate space for ranking items for disambiguation.

For example, suppose we have a "put in" command, and we have two possibilities for the target container. Neither is being held by the actor, so they both have a result with a logical rank of 70 with a key value of 'not held'. In addition, both are openable, and one is open and the other is closed; the closed one has an additional result with a logical rank of 80 and a key of 'not open'. Which do we choose? If we looked only at the logical rankings, both would be equivalent, since both have 70's as their most disapproving results. However, we see that the two 70's were applied for the same reason - because they share a common key - so we know this information isn't helpful for disambiguation and can be ignored. So, we find that the closed one has an 80, and the other has no other results (hence is by default logical with rank 100), thus we take the '80' as the better one.

Throughout the library, we use the following conventions:

150 = especially good fit: a good candidate for the action that is especially likely to be used with the command. For example, a book is especially suitable for a "read" command.

140 = similar to 150, but slightly less ideal a fit. We use this for objects that are excellent fits, but for which we know certain other objects might be better fits.

100 = default: a perfectly good candidate for the action, with nothing that would make it illogical, but nothing that makes it especially likely, either

80 = slightly less than perfect: a good candidate, but with some temporary and correctable attribute that may make it less likely than others. This is used for attributes that can be corrected: a container needs to be opened for the action to succeed, but isn't currently open, or an article of clothing cannot be worn for the action to proceeds, but is currently being worn.

60/70 = slightly less than perfect, but with some attributes that can't be readily corrected and which make the candidate potentially less likely. These are used to make guesses about which might object might be intended when several are logical but some might be more readily used than others; for example, if putting an object into a container, a container being held might rank higher than one not being held, so the one not being held might be ranked a "70" likelihood.

50 = logical but not especially likely: an acceptable candidate for the action, but probably not the best choice for the action. This is used when an object can be used for the action, but would not be expected to do anything special with the action.

(gVerifyResults.addResult(new LogicalVerifyResult(rank, key, ord)))
Logical ranking with specific list ordering. This is the same as a regular logicalRank, but uses the given list ordering rather than the default list ordering (100).

0x0008
show the portable items

0x0004
show the non-portable items (the specialDesc's)

0x0002
show the room's long desription (the roomDesc)

0x0001
show the room name as part of the description

1
The indices for the key values used to navigate menus, which are held in the keyList array of MenuItems.

(gTranscript.addReport(new MainCommandReport(msg, ##params)))
Set a main report for the current command. This report will be shown as the main report from the command, overriding any default report for the command.

dobjFor(pushAction) asDobjFor(PushTravel) \
mapPushTravelIobj(pushAction, travelAction)
For two-object push-travel actions, such as "push sled into cave", define a special mapping for both the direct and indirect objects:

- Map the direct object (the object being pushed) to a simple PushTravel action. So, for "push sled into cave," map the direct object handling to PushTravel for the sled. This makes the handling of the command equivalent to "push sled north" and the like.

- Map the indirect object (the travel connector) to use the PushTravel action's verify remapper. This is handled specially by the PushTravel action object to handle the verification as though it were verifying the corresponding ordinary (non-push) travel action on the indirect object. Beyond verification, we do nothing, since the direct object of a pushable object will handle the whole action using a nested travel action.

This effectively decomposes the two-object action into two coupled single-object actions: a regular PushTravel action on the object being pushed, and a regular whatever-kind-of-travel on the connector being traversed. This handling has the appeal that it means that we don't need a separate PUSH version of every kind of allowed travel on a connector, and we don't need a special handler version for each kind of travel on a pushable object; instead, we just use the basic PushTravel and kind-of-travel handlers to form the combined form. Note that this still allows separate treatment of the combined form wherever desired, just by overriding these default handlers for the two-object action.

0x0008
The object came from an 'all' phrase. Normally, the only time this makes any difference is when deciding whether or not to mention which object we're acting upon; an 'all' object should normally be mentioned explicitly, as though the command had involved multiple objects, because otherwise it might not be clear to the user what object had actually matched 'all'.

{ remap = ((cond) ? [action##Action, ##objs] : inherited()) }
Conditionally remap an action. If 'cond' (a conditional expression) evaluated to true, we'll remap the action as directed; otherwise, we'll inherit the default handling

_nestedAction(nil, gActor, action##Action, ##objs)
Run a nested action.

_nestedAction(nil, actor, action##Action, ##objs)
Run a nested action targeted to a given actor.

_newAction(CommandTranscript, nil, gActor, action##Action, ##objs)
Run a new action. This is a brand new action run as a separate turn, not as a nested action. This doesn't replace any current action, but is simply a separate action.

This is normally used only for internal actions that are run between other actions. This should not normally be used while another action is being processed - use nestedAction for that instead. This should also not normally be used to replace the current action with another - use replaceAction for that.

Returns a CommandTranscript object, which provides information on the results of the action.

_newAction(CommandTranscript, nil, actor, action##Action, ##objs)
run a new action with a specific actor

(gVerifyResults.addResult(new NonObviousVerifyResult('')))
command is logical but non-obvious: the object should never be taken as a default

sentinel##which##action = __objref(action##Action, warn)
in debug mode, flag objFor definitions for non-existent actions

openableDescContentsLister
For compatibility with versions before 3.1.1, define openableContentsLister as a synonym for openableDescContentsLister. The former was renamed to the latter in 3.1.1 because the original name was inconsistent with the corresponding listers for other classes. In principle, openableContentsLister is meant to be the 'contentsLister' (for displaying the openable's contents in room descriptions, etc) for an Openable, while openableDescContentsLister is its 'descContentsLister' (for displaying the openable's contents in its own EXAMINE description). Fortunately we don't have a need for a special contentsLister for Openable, so we can avoid breaking existing code by mapping the old name to the new name.

If we're compiling for debugging, automatically include the parser debug code, which allows certain information on the parsing process (such as grammar match trees) to be displayed each time a command is typed.

Note that you can turn on parser debugging independently of full compiler debug information simply by explicitly defining PARSER_DEBUG (with the t3make -D option, for example).

0x0004
One or more plurals was truncated from its full dictionary spelling. (We specially distinguish plurals that are truncated, because in English a plural is usually formed by adding "s" or "es" to the end of the singular form of a noun, meaning that a given singular form is usually a leading substring of its plural. When a singular noun is longer than the truncation limit, which is conventionally six characters, the singular will always match as a truncated version of the plural, so every time someone types in a singular it'll be treated as ambiguous between the singular and plural form. So, in the English parser, we have a preference to ignore a truncated plural any time the word could also be interpreted as an untruncated singular, hence we note when we have a truncated plural.)

{ remap = [action##Action, ##objs] }
"Remap" an action. This effectively rewrites the action in the given form. Each of the object slots can be filled either with a specific object, or with a noun phrase role name (DirectObject, IndirectObject); in the latter case, the object or objects from the named noun phrase role in the *current* action (i.e., before the rewrite) will be used.

If the new action has two or more objects (for example, if it's a TIAction), then EXACTLY ONE of the slots must be filled with a specific object, and all of the other slots must be filled with role names. The specific object is the one that corresponds to the original object that's doing the remapping in the first place - this can simply be 'self' if the new action will operate on the same object, or it can be a different object. The important thing is that the 'verify' method for the defining object will be forwarded to the corresponding 'verify' method on the corresponding object for the new action.

This macro must be used as the ENTIRE definition block for a dobjFor() or iobjFor(). For example, to remap a "put in" command directed to a desk so that the command is instead applied to a drawer in the desk, we could define the following on the desk object:

iobjFor(PutIn) remapTo(PutIn, DirectObject, deskDrawer)

_replaceAction(gActor, action##Action, ##objs)
Replace the current action with a new action. The new action will be performed, and the original action will be terminated with 'exit'.

'action' is the root name of the action, without the 'Action' suffix (we'll add the suffix automatically). 'objs' is a varying-length list of the resolved objects - direct object, indirect object, etc.

_replaceAction(actor, action##Action, ##objs)
Replace the current action with a new action directed to a different actor (but from the same issuing actor).

(gTranscript.addReport(new AfterCommandReport(msg, ##params)))
Set an "after" report for the current command. This report will be shown after any main report, but will override any default report for the command.

(gTranscript.addReport(new BeforeCommandReport(msg, ##params)))
Set a "before" report for the current command. This report will be shown before any main report, but will override any default report for the command.

(gTranscript.addReport(new FailCommandReport(msg, ##params)))
Report failure. This overrides any default report, and marks the command as having failed.

A failure report should NOT indicate any state change - this is important because failure reports are suppressed under some conditions (for example, when an NPC is performing an implied command, and the implied command fails, we don't show the failure report). If a failure is accompanied by a state change, then a mainReport() should be made in addition to the failure report - the main report should indicate the state change.

(gTranscript.addReport(new QuestionCommandReport(msg, ##params)))
Report a question. This shows a report that's really an interactive prompt for more information, such as a prompt for a missing object.

0x0002
use 'and' before the tens - 125 is 'one hundred and twenty-five' rather than 'one hundred twenty-five'

0x0004
put a comma after each power group - 123456 is 'one hundred twenty-three thousand, four hundred fifty-six'

0x0001
Use tens of hundreds rather than thousands if possible - 1950 is 'nineteen hundred fifty' rather than 'one thousand nine hundred fifty'. This only works if the number (not including the millions and billions) is in the range 1,100 to 9,999, because we don't want to say something like 'one hundred twenty hundred' for 12,000.

_tryImplicitAction(gIssuingActor, gActor, &announceImplicitAction, \
action##Action, ##objs)
Try performing a command implicitly. The action is the root name of the action, without the 'Action' suffix - we'll automatically add the suffix. 'objs' is a varying-length list of the resolved objects in the new action - the direct object, indirect object, and any others needed for the action.

_tryImplicitAction(gIssuingActor, gActor, msgProp, \
action##Action, ##objs)
Try performing a command implicitly, with a special descriptive message. 'msgProp' gives the libMessages method to invoke the announce the action, if the action is performed. If 'msgProp' is nil, no message is displayed at all.

'action' is the root name of the action, without the 'Action' suffix (we'll automatically add the suffix). 'objs' is a varying-length list of the resolved objects - direct object, indirect object, and any others needed.

0x0040
The noun phase describing this object was ambiguous, and the object was selected by automatic disambiguation in a context where it was not perfectly clear which object was indicated. This is used for cases where the objects selected were more logical than the objects not selected, but some of the unselected objects were still logical.

This flag doesn't mean that we chose arbitrarily, but rather that we chose the best object or objects from a field that included additional objects that, though not quite as good, were still valid. We flag this case because the user *could* have meant to use one of the other valid objects, even though we consider it most likely that the user meant to use the one(s) we selected; so, we want to flag this so we can call the user's attention to our choice, to make it more likely that the user will immediately notice if we made the wrong choice.

Note that we can't have both ClearDisambig and UnclearDisambig at the same time, but we *can* have neither of these. If neither flag is set for an object, it simply means that the object wasn't ambiguous to start with. When the user explicitly picks an object interactively, the selected object is effectively unambiguous, so it won't have either flag set; even though it started off ambiguous, the user did all of the work of selecting the appropriate object, leaving things unambiguous in the end.

0x0002
one of the words in the noun phrase was truncated from its full dictionary spelling

Object role identifiers. These are used to identify the role of a noun phrase in a command.

The library provides base classes for actions of zero, one, and two noun phrases in their grammars: "look", "take book", "put book on shelf". We thus define role identifiers for direct and indirect objects. Note that even though we stop there, this doesn't preclude games or library extensions from adding actions that take more than two noun phrases ("put coin in slot with tongs"); any such extensions must simply define their own additional role identifiers for the third or fourth (etc) noun phrase.

Announce clear and unclear disambiguation results, both using parenthetical announcement ("(the red door)"). When this setting is selected, the parser makes these announcements every time it applies the logicalness rules or likelihood rankings to disambiguate a noun phrase. There's no announcement when no disambiguation is needed (because the noun phrase matches only one in-scope object).

Announce unclear disambiguation results only. When this setting is selected, the parser makes a parenthetical announcement (e.g., "(the red door)") when it selects an object based on likelihood rankings from among more than one logical match. The parser makes no announcement when exactly one logical object is in scope, even if other objects match the noun phrase by name.

The sense is passed, but with attenuation of energy level. No other obscuration of detail occurs; this is something like tinted glass that doesn't distort the transmitted sense but reduces the amount of energy.

Special result code for Actor.canEndConversation() - this indicates that the other actor said something to force the conversation to keep going.

Describe clear disambiguation results, rather than announcing them. The parser makes the parenthetical announcement, as usual, for unclear disambiguation picks, but not for clear picks (a clear pick is one where there's only one logical object, even though the noun phrase matches more than one object). For clear picks, however, the parser uses a verbose version of the action reply in lieu of one of the terse default messages. For example, rather than saying just "Taken", the parser would reply "You take the red book." The longer messages mention the object by name, to make it clear exactly which one was chosen.

the sense is passed, but with a loss of detail associated with distance

End-of-conversation reason codes

footnote status levels

Inventory modes. "Wide" mode displays the inventory in paragraph form; "tall" mode displays as a list, with one item per line, indenting items to reflect containment.

Large - the object is large enough that its details can be sensed from a distance or through an obscuring medium.

Medium - the object can be sensed at a distance or when obscured, but not in any detail. Most objects fall into this category. Note that things that are parts of large objects should normally be medium.

The sense is passed, but with a loss of detail due to an obscuring layer of material. The energy level is also attenuated. This is something like dirty or wavy glass that distorts an image transmitted through it but doesn't completely block out light.

the sense is not passed at all

A special role for the "other" object of a two-object command. This can be used in certain contexts (such as remapTo) where a particular object role is implied by the context, and where the action involved has exactly two objects; OtherObject in such contexts means DirectObject when the implied role is IndirectObject, and vice versa.

traverse from the starting point of the path

traverse into the contents

traverse out to the container

traverse from an object to a peer at the same containment level

traverse through an object with no common container on either side of the traversal - this is used when we are traversing an object, such as a SenseConnector, that connects unrelated locations

traverse to the ending point of the path

Pronoun types. These are used to identify pronoun antecedents when resolving noun phrases involving pronouns.

We define a basic set of pronouns here that are common to most languages. Language-specific modules are free to add their own pronoun types as needed.

Our basic set is:

'it' - the neuter singular
'him' - the masculine singular
'her' - the feminine singular
'them' - the ungendered plural
'you' - second person singular
'me' - first person singular

Note that the first-person and second-person pronouns are assigned meanings that can vary by context. When a command is issued by the player character to the player character (i.e., the command comes from the player and no target actor is specified), these refer to the player character when the PC is in the appropriate referral person - if the game calls the PC "you", then the player calls the PC "me", and vice versa. When a command is targeted to or issued by an actor other than the PC, then "you" refers to the command's target and "me" refers to the command's issuer.

reading a response to a prompt for a missing literal phrase

reading a response to a prompt for a missing object phrase

reading a normal command line

reading a response to an interactive disambiguation prompt

reading an unknown word response, to check for an "oops" command

Small - the object cannot be sensed at a distance at all. This is appropriate for detailed parts of medium-class objects.

the sense is passed without loss of detail

+points? "desc";
An achievement defines its descriptive text. It can also optionally define the number of points it awards.

"topicResponse" | [eventList];
alternative topics just specify the response string or strings

'name';
a conversation node need a name

"topicResponse" | [eventList];
default topics just specify the response text

[eventList];
An event list takes a list of strings, objects, and/or functions.

"desc";
A template for footnotes - all we usually need to define in a footnote is its descriptive text, so this makes it easy to define one.

->closeWhenAchieved? 'title' 'heading'? [menuContents];
templates for hint system objects

'title' 'heading'?;
some templates for defining menu items

"topicResponse" | [eventList];
miscellanous topics just specify the response text or list

[locationList];
Template for multi-location objects. To put a MultiLoc object in several initial locations, simply use a template giving the list of locations.

[firstEvents] [eventList];
A shuffled event list with two lists - the first list is the sequential initial list, fired in the exact order specified; and the second is the random list, with the events that occur in shuffled order after we exhaust the initial list.

[valueList];
low-level shuffled list

'name' [keywordList] | 'matchPat' "topicResponse" | [eventList] ?;
A SpecialTopic takes a keyword list or a regular expression instead of the regular match criteria. It also takes a suggestion name string and the normal response text. There's no need for a score in a special topic, since these are unique.

'name' [keywordList] | 'matchPat' [firstEvents] [eventList];
a ShuffledEventList version of the above

'tagName' 'openText'? 'closeText'?;
Templates for style tags

->masterObject inherited;
a synchronized event list takes its state from another list

"desc";
Define a template for the Tip class.

+matchScore? @matchObj | [matchObj] | 'matchPattern' "topicResponse" | [eventList] ?;
A TopicEntry can be defined with an optional score, followed by the match criteria (which can be either a single matching object, a list of matching objects, or a regular expression pattern string), followed by the optional response text (which can be given either as a double-quoted string or as a list of single-quoted strings to use as an EventList).

+matchScore? @matchObj | [matchObj] | 'matchPattern' [firstEvents] [eventList];
a ShuffledEventList version of the above

+matchScore? @matchObj | [matchObj] 'matchPattern' "topicResponse" | [eventList] ?;
we can also include *both* the match object/list *and* pattern

+matchScore? @matchObj | [matchObj] 'matchPattern' [firstEvents] [eventList];
a ShuffledEventList version of the above

+matchScoreAdjustment;
a TopicGroup can specify its score adjustment