/* 

 *   Copyright (c) 2000, 2006 Michael J. Roberts.  All Rights Reserved. 

 *   

 *   TADS 3 Library - main header

 *   

 *   This file provides definitions of macros, properties, and other

 *   identifiers used throughout the library and in game source.

 *   

 *   Each source code file in the library and in a game should generally

 *   #include this header near the top of the source file.  

 */

#ifndef ADV3_H

#define ADV3_H

/* ------------------------------------------------------------------------ */

/*

 *   Include the system headers that we depend upon.  We include these here

 *   so that each game source file will pick up the same set of system

 *   headers in the same order, which is important for intrinsic function

 *   set definitions.  

 */

#include <tads.h>

#include <tok.h>

#include <t3.h>

#include <vector.h>

#include <file.h>

#include <dict.h>

/* ------------------------------------------------------------------------ */

/*

 *   Establish the default dictionary for the game's player command parser

 *   vocabulary.

 */

dictionary cmdDict;

/* ------------------------------------------------------------------------ */

/*

 *   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.  

 */

#define canInherit() \

    propInherited(targetprop, targetobj, definingobj, PropDefAny)

/* ------------------------------------------------------------------------ */

/*

 *   Generic part of speech for "miscellaneous word."  We use this to

 *   classify words in unstructured phrases; it can apply to any token.

 *   Note that dictionary entries are never made with this word type, so

 *   it's not specific to any language; this is merely for flagging words in

 *   unstructured phrases in grammar matches.  

 */

dictionary property miscWord;

/*

 *   Generic part of speech for SpecialTopic words.  We enter special topic

 *   keywords into the parser dictionary so that they're not flagged as

 *   unknown words if they're used out of context.  

 */

dictionary property specialTopicWord;

/* ------------------------------------------------------------------------ */

/*

 *   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).  

 */

#ifdef __DEBUG

#define PARSER_DEBUG

#endif

/*

 *   Define some convenience macros for parser debug operations.  When

 *   PARSER_DEBUG isn't defined, these macros expand out to nothing.  

 */

#ifdef PARSER_DEBUG

#define dbgShowGrammarList(lst) showGrammarList(lst)

#define dbgShowGrammarWithCaption(headline, match) \

    showGrammarWithCaption(headline, match)

#else /* PARSER_DEBUG */

#define dbgShowGrammarList(lst)

#define dbgShowGrammarWithCaption(headline, match)

#endif /* PARSER_DEBUG */

/* ------------------------------------------------------------------------ */

/*

 *   Parser global variables giving information on the command currently

 *   being performed.  These are valid through doAction processing.  These

 *   should never be changed except by the parser.

 */

/* the actor performing the current command */

#define gActor (libGlobal.curActor)

/*

 *   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.  

 */

#define gDobj (gAction.getDobj())

#define gIobj (gAction.getIobj())

/* 

 *   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.  

 */

#define gTopic (gAction.getTopic())

#define gTopicText (gTopic.getTopicText.toLower())

/* get the current literal phrase text, when the command has one */

#define gLiteral (gAction.getLiteral())

/*

 *   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.  

 */

#define gTentativeDobj (gAction.getTentativeDobj())

#define gTentativeIobj (gAction.getTentativeIobj())

/* 

 *   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) 

 */

#define gIssuingActor (libGlobal.curIssuingActor)

/* the Action object of the command being executed */

#define gAction (libGlobal.curAction)

/*

 *   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.  

 */

#define gActionIs(action) \

    (gAction != nil && gAction.actionOfKind(action##Action))

/* is the current global action ANY of the specified actions? */

#define gActionIn(action...) \

    (gAction != nil \

     && (action#foreach/gAction.actionOfKind(action##Action)/||/))

/* the verification results object - this is valid during verification */

#define gVerifyResults (libGlobal.curVerifyResults)

/* the command transcript object - this is valid during command execution */

#define gTranscript (mainOutputStream.curTranscript)

/*

 *   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.  

 */

#define gMessageParams(var...) \

    (gAction.setMessageParams(var#foreach/#@var, 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.  

 */

#define gSynthMessageParam(var) (gAction.synthMessageParam(var))

/* ------------------------------------------------------------------------ */

/*

 *   Miscellaneous macros

 */

/* get the current player character Actor object */

#define gPlayerChar (libGlobal.playerChar)

/* 

 *   the exit lister object - if the exits module isn't included in the

 *   game, this will be nil 

 */

#define gExitLister (libGlobal.exitListerObj)

/*

 *   the hint manager object - if the hints module isn't included in the

 *   game, this will be nil 

 */

#define gHintManager (libGlobal.hintManagerObj)

/* ------------------------------------------------------------------------ */

/*

 *   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.)  

 */

#define gLibMessages (libGlobal.libMessageObj)

/* ------------------------------------------------------------------------ */

/*

 *   readMainCommandTokens() phase identifiers.  We define a separate code

 *   for each kind of call to readMainCommandTokens() so that we can do any

 *   special token processing that depends on the type of command we're

 *   reading.

 *   

 *   The library doesn't use the phase information itself for anything.

 *   These phase codes are purely for the author's use in writing

 *   pre-parsing functions and for differentiating prompts for the different

 *   types of input, as needed.

 *   

 *   Games that read additional response types of their own are free to add

 *   their own enums to identify the additional phases.  Since the library

 *   doesn't need the phase information for anything internally, it won't

 *   confuse the library at all to add new game-specific phase codes.  

 */

/* reading a normal command line */

enum rmcCommand;

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

enum rmcOops;

/* reading a response to a prompt for a missing object phrase */

enum rmcAskObject;

/* reading a response to a prompt for a missing literal phrase */

enum rmcAskLiteral;

/* reading a response to an interactive disambiguation prompt */

enum rmcDisambig;

/* ------------------------------------------------------------------------ */

/*

 *   Property set definitions 

 */

#define objFor(which, action) propertyset '*' ## #@which ## #@action

#define dobjFor(action) objFor(Dobj, action)

#define iobjFor(action) objFor(Iobj, 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.  

 */

#define asObjFor(obj, Action) \

    { \

        preCond { return preCond##obj##Action; } \

        verify() { verify##obj##Action; } \

        remap() { return remap##obj##Action; } \

        check() { check##obj##Action; } \

        action() { action##obj##Action; } \

    }

#define asDobjFor(action) asObjFor(Dobj, action)

#define asIobjFor(action) asObjFor(Iobj, 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.  

 */

#define asObjWithoutActionFor(obj, Action) \

    { \

        preCond { return preCond##obj##Action; } \

        verify() { verify##obj##Action; } \

        remap() { return remap##obj##Action(); } \

        check() { check##obj##Action; } \

        action() {  } \

    }

#define asDobjWithoutActionFor(action) asObjWithoutActionFor(Dobj, action)

#define asIobjWithoutActionFor(action) asObjWithoutActionFor(Iobj, action)

/*

 *   "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) 

 */

#define remapTo(action, objs...) { remap = [action##Action, ##objs] }

/*

 *   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 

 */

#define maybeRemapTo(cond, action, objs...) \

    { remap = ((cond) ? [action##Action, ##objs] : inherited()) }

/*

 *   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.  

 */

#define mapPushTravelHandlers(pushAction, travelAction) \

    dobjFor(pushAction) asDobjFor(PushTravel) \

    mapPushTravelIobj(pushAction, travelAction)

#define mapPushTravelIobj(pushAction, travelAction) \

    iobjFor(pushAction) \

    { \

        verify() \

            { gAction.verifyPushTravelIobj(self, travelAction##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.  

 */

#define actorStateObjFor(obj, Action) \

    { \

        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; } \

    }

#define actorStateDobjFor(action) actorStateObjFor(Dobj, action)

#define actorStateIobjFor(action) actorStateObjFor(Iobj, action)

/* ------------------------------------------------------------------------ */

/*

 *   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.

 */

enum ActorObject, DirectObject, IndirectObject;

/*

 *   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. 

 */

enum OtherObject;

/* ------------------------------------------------------------------------ */

/*

 *   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.  

 */

enum PronounIt, PronounThem, PronounHim, PronounHer, PronounYou, PronounMe;

/* ------------------------------------------------------------------------ */

/* 

 *   set the location property 

 */

+ property location;

/* ------------------------------------------------------------------------ */

/*

 *   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.  

 */

#define asExit(dir) = static ((dir).createUnlistedProxy())

/* ------------------------------------------------------------------------ */

/*

 *   "Person" indices.  We define these as numbers rather than enums so that

 *   we can easily use these as list indices.  

 */

#define FirstPerson   1

#define SecondPerson  2

#define ThirdPerson   3

/* ------------------------------------------------------------------------ */

/*

 *   Transparency levels 

 */

/* the sense is passed without loss of detail */

enum transparent;

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

enum distant;

/*

 *   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. 

 */

enum attenuated;

/* 

 *   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.  

 */

enum obscured;

/* the sense is not passed at all */

enum opaque;

/* ------------------------------------------------------------------------ */

/*

 *   Size classes.  An object is large, medium, or small with respect to

 *   each sense; the size is used to determine how well the object can be

 *   sensed at a distance or when obscured.

 *   

 *   What "size" means depends on the sense.  For sight, the size

 *   indicates the visual size of the object.  For hearing, the size

 *   indicates the loudness of the object.  

 */

/* 

 *   Large - the object is large enough that its details can be sensed

 *   from a distance or through an obscuring medium.

 */

enum large;

/* 

 *   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.  

 */

enum medium;

/*

 *   Small - the object cannot be sensed at a distance at all.  This is

 *   appropriate for detailed parts of medium-class objects.  

 */

enum small;

/* ------------------------------------------------------------------------ */

/*

 *   Path traversal operations. 

 */

/* traverse from the starting point of the path */

enum PathFrom;

/* traverse into the contents */

enum PathIn;

/* traverse out to the container */

enum PathOut;

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

enum PathPeer;

/* 

 *   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 

 */

enum PathThrough;

/* traverse to the ending point of the path */

enum PathTo;

/* ------------------------------------------------------------------------ */

/*

 *   Listing Options 

 */

/* 

 *   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) 

 */

#define ListTall      0x0001

/*

 *   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.  

 */

#define ListRecurse   0x0002

/* 

 *   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) 

 */

#define ListLong      0x0004

/* 

 *   This is a recursive listing of the contents of an item.  This is set by

 *   showList() in calls it makes to recursive listing levels.

 */

#define ListContents  0x0008

/*

 *   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) 

 */

#define ListCustomFlag 0x0100

#define ListerCustomFlag(n) static ((inherited.nextCustomFlag) << ((n) - 1))

/* ------------------------------------------------------------------------ */

/*

 *   Spelled-out number options, for spellInt() and related functions.

 *   

 *   Note that the interfaces to the number-spelling functions can vary by

 *   language, and that variation can include these flags.  Some language

 *   modules might ignore some of these generic flags or define additional

 *   language-specific flags.  

 */

/* 

 *   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.  

 */

#define SpellIntTeenHundreds    0x0001

/*

 *   use 'and' before the tens - 125 is 'one hundred and twenty-five'

 *   rather than 'one hundred twenty-five' 

 */

#define SpellIntAndTens         0x0002

/*

 *   put a comma after each power group - 123456 is 'one hundred

 *   twenty-three thousand, four hundred fifty-six' 

 */

#define SpellIntCommas          0x0004

/* ------------------------------------------------------------------------ */

/*

 *   Decimal number format options.  These are used with the number

 *   formatting functions to control the formatting of numbers displayed in

 *   decimal digit format.  

 */

/*

 *   Use a group separator character between digit groups, using the

 *   default setting in languageGlobals.

 */

#define DigitFormatGroupSep     0x0001

/* 

 *   Explicitly use a comma/period to separate digit groups, overriding

 *   the current languageGlobals setting.

 */

#define DigitFormatGroupComma   0x0002

#define DigitFormatGroupPeriod  0x0004

/* ------------------------------------------------------------------------ */

/*

 *   ResolveInfo flags 

 */

/* the noun phrase ends with an adjective */

#define EndsWithAdj      0x0001

/* 

 *   one of the words in the noun phrase was truncated from its full

 *   dictionary spelling 

 */

#define VocabTruncated   0x0002

/*

 *   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.)  

 */

#define PluralTruncated  0x0004

/*

 *   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'.  

 */

#define MatchedAll       0x0008

/*

 *   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).  

 */

#define AlwaysAnnounce   0x0010

/*

 *   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.  

 */

#define ClearDisambig    0x0020

/*

 *   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