rules.t

documentation
#charset "us-ascii"
#include "advlite.h"

/* 
 *   RULES EXTENSION by Eric Eve July 2014
 *
 *   The rules.t extension allows Inform7-style rules and rulebooks to be
 *   defined in a TADS 3 game.
 */




/* 
 *   A RuleBook is a container for one or more rules. Calling the follow()
 *   method of a RuleBook causes each of its contained rules to be executed in
 *   turn until one returns a non-null value. That value is then returned to the
 *   caller of the RuleBook. [DEFINED IN RULES EXTENSION]
 */     
class RuleBook: PreinitObject    
    
    /* A list of rules contained in this rulebook */
    contents = []
    
    /* 
     *   The actor to use for comparison with the who property for rules in this
     *   RuleBook. The default is gPlayerChar, but for some RuleBooks gActor may
     *   be more appropriate.
     */
    actor = gPlayerChar
    
    /* Add a rule to the contents of this rulebook [RULES EXTENSION] */
    addToContents(ru)
    {
        contents += ru;
    }
    
    /* Remove a rule from the contents of this rulebook [RULES EXTENSION] */
    removeFromContents(ru)
    {
        contents -= ru;
    }
    
    
    /* 
     *   Follow this Rule. This is the method game code will normally call to
     *   make use of this RuleBook. Each of our rules will be tested to see if
     *   it matches its conditions; we then run through those of our rules that
     *   match their rules in order of precedence until one returns a non-null
     *   value, which we then in turn return to our caller. If no rule returns a
     *   non-null value we return our own default value, which is normally nil.
     *
     *   This method can be called with as many arguments as the game code finds
     *   useful, or with none at all. Our arguments will then be passed on to
     *   each Rule that is called. The first argument will also be stored in our
     *   matchObj property, which our Rules can compare with their own matchObj
     *   condition to see if they match. This allows game code to, for example,
     *   run a RuleBook related to some object that isn't one of the objects
     *   directly involved in the current action. [RULES EXTENSION]
     */
    follow([args])
    {
        /* 
         *   If we have any arguments at all, store the first one in our
         *   matchObj property for comparison with our Rules' matchObj
         *   conditions.
         */
        if(args.length > 0)
            matchObj = args[1];
        
        /* Carry out any custom initialization required. */
        initBook(args...);
        
        /* 
         *   Make sure that all the Rules in our contents list know that we're
         *   the RuleBook that's currently calling them. This is necessary in
         *   case the same Rule is associated with more than one RuleBook.
         */
        contents.forEach({ r: r.setRulebook(self) });
        
        /* Extract the subset of Rules that match their conditions. */
        local validRules = contents.subset({r: r.matchConditions});
        
        /* Sort the matching rules in descending order of precedence. */
        validRules = validRules.sort(SortDesc, {a, b: a.compareTo(b)} );
        
        /* 
         *   Go through each of the matching rules in turn, calling its follow
         *   method. If any rule returns a non-null value, stop running through
         *   the rules and return that value to our caller.
         */
        foreach(local ru in validRules)
        {
            IfDebug(rules, 
                    "[Executing rule: <<valToSym(ru)>> in rulebook
                    <<valToSym(self)>>]\n" );
            local res = ru.follow(args...);
            
            if(res != contValue)
                return res;
        }
        
        /* 
         *   If no rule returned a non-null value, return our own defaultVal to
         *   our caller.
         */
        return defaultVal;
    }
    
    
    /* 
     *   contValue (continue value) is the value that a Rule in this RuleBook
     *   needs to return to avoid the RuleBook stopping at that Rule (rather
     *   than going on to consider more Rules). By default this is null, which
     *   means by default a Rule that does not explicitly return a value (and so
     *   effectivelt returns nil) will stop the RuleBook. If you want the
     *   default behaviour for this RuleBook to be not for Rules to stop the
     *   book, then override this to nil. [RULES EXTENSION]
     */
    contValue = null
    
    /*  
     *   The default value to return to our caller. By default this is the same
     *   as our contValue , to make it easy to test whether we any rule returned
     *   a non-null value. By default a rule that does something will return
     *   nil, so if no rule does anything we want to return a different value.
     *   By making the defaultValue the same as the contValue, we ensure that we
     *   can tell our caller that no rule was executed (if that is indeed the
     *   case). [RULES EXTENSION]
     */
    defaultVal = contValue
    
    /*   
     *   The value our associated rules use by default to stop this RuleBook
     *   considering any further rules (when a Rule uses the stop macro). By
     *   default we use a value of true. [RULES EXTENSION]
     */    
    stopValue = true
    
    /* 
     *   Game code can use this method to initialize the values of custom
     *   RuleBook properties at the start of the processing of following a
     *   RuleBook. [RULES EXTENSION]
     */
    initBook([args]) { }
    
    /*   
     *   The object (or any other value) to be matched by our Rule's matchObj
     *   conditions if they have any. This property is set by our follow()
     *   method (from its first argument) and so should not normally be directly
     *   changed from game code. [RULES EXTENSION]
     */
    matchObj = nil
    
;

/* Preinitializer for Rules. [DEFINED IN RULES EXTENSION]*/
rulePreinit:PreinitObject
    execute()
    {
        /* Initialize all the Rules in the game. */
        for(local ru = firstObj(Rule); ru != nil; ru = nextObj(ru, Rule))
        {
            ru.initializeRule();
        }       
    }
;


/* 
 *   A Rule is an object that defines a set of conditions that need to be met
 *   for it to be executed when its RuleBook is run and a method that's executed
 *   when its conditions are met. A Rule can be associated with one or more
 *   RuleBooks; it starts out in the RuleBook with which it is associated via
 *   its + property (i.e. its location). [DEFINED IN RULES EXTENSION]
 */
class Rule: object
    /* 
     *   Our location is the RuleBook with which we start out being associated.
     *   Normally this will be defined by locating a Rule inside its RukeBook
     *   using the + notation. [RULES EXTENSION]
     */
    location = nil
    
    /*   
     *   The rulebook that's currently considering us. Normally this will be our
     *   location, but it could be a different RuleBook if we belong to one.
     *   Note that this property is automatically set by the library and so it
     *   should never need to be altered by game code. [RULES EXTENSION]
     */
    rulebook = location
      
    /*   
     *   Set our current rulebook to r. Note that this method is normally called
     *   by the Rulebook that's running us, and shouldn't normally be used by
     *   game code. [RULES EXTENSION]
     */
    setRulebook(r) { rulebook = r; }
    
    /*   A list of all the rulebooks this rule is currently associated with. [RULES EXTENSION] */
    rulebooks = []    
    
    /*   
     *   Initialize this Rule by adding it to the contents list of its location
     *   and calculating its specificity (i.e. how specific its conditions are)
	 *   [RULES EXTENSION]
     */
    initializeRule()
    {
        if(location)
        {
            location.addToContents(self);               
            rulebooks += location;
        }
        
        specificity = calcSpecficity();
    }
    
    /* 
     *   Do whatever this Rule needs to do when its conditions are met. This
     *   method will need to be defined on each individual Rule in game code.
	 *   [RULES EXTENSION]
     */         
    follow([args])
    {
    }
    
    /* 
     *   The priority of this Rule. This can be used to alter the order in which
     *   this Rule is considered in its RuleBook. If two Rules have different
     *   priorities they will be run in priority order, highest priority first.
     *   The default value is 100. [RULES EXTENSION]
     */ 
    priority = 100
    
    /*   
     *   Where two Rules have the same priority, the one with the more specific
     *   conditions is taken first. The specificity property holds a measure of
     *   the Rule's specificity which is calculated by the calcSpecificity()
     *   method at PreInit. [RULES EXTENSION]
     */
    specificity = nil
    
    /* 
     *   Return true if this Rule should always execute after other (despite all
     *   other ranking criteria). By default we return true if and only if other
     *   is in our execAfter list. [RULES EXTENSION]
     */   
    runAfter(other)
    {
        return valToList(execAfter).indexOf(other) != nil;        
    }
    
    /* 
     *   A list of Rules this Rule should specifically run after; this overrides
     *   all other ranking. [RULES EXTENSION]
     */
    execAfter = []
    
    /* 
     *   Return true if this Rule should always execute before other (despite all
     *   other ranking criteria). By default we return true if and only if other
     *   is in our execBefore list. [RULES EXTENSION]
     */
    runBefore(other)
    {
        return valToList(execBefore).indexOf(other) != nil;
    }
    
    /*  
     *   A list of Rules this Rule should specifically run before; this
     *   overrides all other ranking except for runAfter/execAfter.     
     *   [RULES EXTENSION]
     */
    execBefore = []
    
    /*  
     *   A Rule is normally active (that is it will normally be considered when
     *   a RuleBook is being followed) but it can be temporarily disabled by
     *   setting its isActive property to nil. [RULES EXTENSION]
     */
    isActive = true

    /* Make this Rule active [RULES EXTENSION] */
    activate() { isActive = true; }
    
    /* Make this Rule inactive [RULES EXTENSION] */
    deactivate() { isActive = nil; }
    
    /*
     *   Calculate the specificity of this Rule. The principles are (a) Rules
     *   that specify more conditions are more specific than Rule that specify
     *   fewer condition; (b) conditions involving specific objects are more
     *   specific that those relating to classes and (c) Rooms are more specific
     *   than Regions in a where condition. [RULES EXTENSION]
     */
    calcSpecficity()
    {       
        local p = 0;
       
        /* a 'when' has priority over no 'when' */
        if(propDefined(&when))
            p += 10;
        
        /* 
         *   a 'where' has priority over no 'where', and a where property that
         *   specifies a Room is more specific than one that specifies a Region.
         */
        if(propDefined(&where))
            p += valToList(where).indexWhich({r: r.ofKind(Room)}) ? 10 : 5;
        
        /* a 'during' has priority over no 'during' */
        if(propDefined(&during))
            p += 10;
        
        /* a 'who' has priority over no 'who' */
        if(propDefined(&who))
            p += 10;
        
        /* an 'action' has prioity over no 'action' */
        if(propDefined(&action))
        {
            p += 5;
        }
        
        /* 
         *   A Rule that refers to command objects (direct, indirect and
         *   accessory) is more specific than one that does not, and particular
         *   objects are more specific than classes.
         */
        for(local prop in [&dobj, &iobj, &aobj])
        {
            if(propDefined(prop))
            {
                p += valToList(self.(prop)).indexWhich( {x: !x.isClass()} ) !=
                nil ? 2 : 1;
            }                
        }
        
        /* 
         *   If matchObj is defined, then what we do with it depends on the type
         *   of value(s) it contains.
         */
        if(propDefined(&matchObj))
        {
            switch(propType(&matchObj))
            {
                /* If matchObj is nil, then ignore it. */
            case TypeNil:
                break;
                
                /* 
                 *   If it's an object, increase our specificity by 10, unless
                 *   it's a class, in which case only increase it by 5 (a class
                 *   is less specific than an object).
                 */
            case TypeObject:
                p += (matchObj.isClass ? 5 : 10);
                break;
                /* 
                 *   If it's a list, check what kind of values the list
                 *   contains.
                 */
            case TypeList:
                /*  
                 *   If the first item in the list is an object, assume the
                 *   whole list contains objects, then increase our specificity
                 *   by 10 if any of those objects is not a class, and by 5
                 *   otherwise (classes are less specific than objects).
                 */
                if(matchObj.length > 0 && dataType(matchObj[1]) == TypeObject)
                {
                    if(matchObj.indexWhich({o: !o.isClass}))
                        p += 10;
                    else
                        p += 5;
                }
                /* 
                 *   Otherwise, if it's some other kind of value, simply
                 *   increase our specificity by 10.
                 */
                else
                    p += 10;
                
                break;
                /* 
                 *   For any other kind of value, simply increase our
                 *   specificity by 10.
                 */
            default:
                p += 10;
                break;
                
            }
        }
        
        /* Check if our present property is defined. */
        if(propDefined(&present))
        {
            if(dataType(&present) == TypeObject && present.isClass)
                p += 5;
            else
                p += 10;
        }
           
        
        
        /* Return the result of the calculation. */
        return p;       
    }
    
    
    /*
     *   Get the processing priority sorting order relative to another
     *   Rule. [RULES EXTENSION]
     */
    compareTo(other)
    {
        /*  
         *   If we specifically want this Rule to run after other, rank us after
         *   other
         */
        if(runAfter(other))           
            return -1;        
        
        /*   
         *   If we specifically want this Rule to run before other, rank us
         *   before other.
         */
        if(runBefore(other))
            return 1;        
        
        /* 
         *   If the two Rules have different priorities, rank them in order of
         *   priority.
         */
        if(priority != other.priority)   
            return priority > other.priority ? 1 : -1;
        
        /*  
         *   Otherwise, if they have different speficifities, rank them in order
         *   of specificity.
         */
        if(specificity >= other.specificity)
            return specificity > other.specificity ? 1 : -1;
        
        /* 
         *   Failing all else, go by the relative location of the source
         *   code definitions: the definition that appears later in the
         *   source code takes precedence.  If the two are defined in
         *   different modules, the one in the later module takes
         *   precedence.  
         */
        if (sourceTextGroup != other.sourceTextGroup)
            return sourceTextGroup.sourceTextGroupOrder
            - other.sourceTextGroup.sourceTextGroupOrder;

        /* they're in the same module, so the later one takes precedence */
        return sourceTextOrder - other.sourceTextOrder;
        
    }
    
    /* Check whether a Rule matches its where, when, who and during conditions. [RULES EXTENSION] */    
    matchConditions()    
    {
        /* If this Rule is currently inactive it can't match any conditions. */
        if(!isActive)
            return nil;
        
        /* first check the where condition, if there is one. */
        if(propDefined(&where))
        {
            local whereLst = valToList(where);
                                    
            /* 
             *   if we can't match any item in the where list to the player
             *   char's current location, we don't meet the where condition, so
             *   return nil
             */
            if(whereLst.indexWhich( {loc: gActor.isIn(loc)}) == nil)
                return nil;
        }
        
        /* 
         *   Interpret 'when' as simply a routine that returns true or nil
         *   aocording to some condition defined by the author; so we simply
         *   test whether when returns nil if the property is defined.
         */        
        if(propDefined(&when) && when() == nil)
            return nil;       
        
         /* check the who condition, if there is one. */
        if(propDefined(&who))
        {
            local whoLst = valToList(who);
                        
            
            /* 
             *   If we can't match any item in the who list to the current
             *   actor, we don't meet the who condition, so return nil
             */
            if(whoLst.indexOf(gActor) == nil)
                return nil;
        }
        
        
        /* 
         *   if we're using the scene manager and a during condition is
         *   specified, test whether the scene is currently happening.
         */        
        if(defined(sceneManager) && propDefined(&during))
        {
            local duringList = valToList(during);
            
            if(duringList.indexWhich({s: s.isHappening}) == nil)
                return nil;
        }
        
        /* 
         *   If we've specified an action to match, test whether gAction (the
         *   current action) matches it.
         */
        if(propDefined(&action) 
           && valToList(action).indexWhich({a: gAction.ofKind(a)}) == nil)
            return nil;
        
        
        /*  
         *   If we've specified a dobj, iobj and/or aobj to match, test whether
         *   they match the direct object, indirect object and/or accessory
         *   object of the current action (provided there is one, which there
         *   may not be at startup).
         */
        if(gAction)
        {
            for(local objs in [[&dobj, gDobj], [&iobj, gIobj], [&aobj, gAobj]])
            {
                local prop = objs[1];
                local obj = objs[2];
                
                if(propDefined(prop) 
                   && valToList(self.(prop)).indexWhich({o: obj.ofKind(o)}) == nil)
                    return nil;          
                
            }
        }
        
        /* 
         *   If we have a matchObj defined, test whether it matches our current
         *   rulebook's matchjObj.
         */
        if(propDefined(&matchObj))
        {
            local mList = valToList(matchObj);
            local mo = rulebook.matchObj;
            
            if(mList.length > 0)
            {
                /* 
                 *   If we want to match an object (or class), test whether the
                 *   rulebook's match obj is of the appropriate kind. Since an
                 *   object is always of its own kind, this tests either whether
                 *   the rulebook's matchObj appears in our matchObj list or
                 *   whether it belongs to one of the classes in our matchObh
                 *   list.
                 */
                if(dataType(mList[1]) == TypeObject)
                {
                    if(mList.indexWhich({o: mo.ofKind(o) } ) == nil)
                        return nil;
                }
                /* 
                 *   Otherwise, if we're not testing for an object, simply test
                 *   whether the value of our rulebook's matchObj is equal to
                 *   anyhting in our matchObj property.
                 */
                else if(mList.indexOf(mo) == nil)
                    return nil;               
                    
            }
        }       
        
        /* 
         *   If present is defined, check whether at least one of the items in
         *   the list is in the same room, or can be sensed.
         */
        if(propDefined(&present))
        {
            local pList = valToList(present);
            
            /* 
             *   First test for the special case that the present property
             *   specifies a single class. In which case whether anything in the
             *   location of actor matches that class.
             */            
            if(pList.length == 1 && dataType(pList[1]) == TypeObject &&
               pList[1].isClass())                
            {
                if(actor.getOutermostRoom.allContents.indexWhich(
                    {o: o.ofKind(present) }) == nil)
                    return nil;
            }
            
            /* 
             *   Check whether the first item in list is a property pointer. If
             *   it is we want to use it as a property of the Q object to test
             *   for a sense connection.
             */
            else if(pList.length > 0 && dataType(pList[1]) == TypeProp)
            {
                /* The first item in the list is a property pointer. */
                local prop = pList[1];
                
                /*  
                 *   Reduce the list to its remaining elements, which should all
                 *   be objects.
                 */
                pList = pList.sublist(2);
                
                /*  
                 *   If no item in pList has a sense path from the actor via the
                 *   prop property, we don't match.
                 */
                if(pList.indexWhich({o: Q.(prop)(actor, o) }) == nil)
                   return nil;
            }
            /* 
             *   Otherwise, simply test for the presence of one of the objects
             *   in the actor's room.
             */
            else
            {
                local loc = actor.getOutermostRoom();
                
                if(pList.indexWhich({o: o.isIn(loc)}) == nil)                    
                    return nil;
            }           
        }
        
        
        /* 
         *   If we haven't failed any of the conditions, we're okay to match, so
         *   return true.
         */
        return true;
    }
    
    /* Add this rule to another rulebook [RULES EXTENSION] */
    addTo(rb)
    {
        if(rb && rb.ofKind(RuleBook))
        {
            rb.addToContents(self);
            rulebooks += rb;
        }
    }
    
    /* Remove this rule from a rulebook [RULES EXTENSION] */    
    removeFrom(rb)
    {
        if(rb && rb.ofKind(RuleBook))
        {
            rb.removeFromContents(self);
            rulebooks -= rb;
            
            if(location == rb)
                location = nil;
        }
    }
    
    /* 
     *   Move this rule to another rulebook, removing it from all its current
     *   rulebooks. If rb is nil, simply remove this Rule from its current
     *   rulebooks. [RULES EXTENSION]
     */     
    moveInto(rb)
    {        
        
        /* 
         *   If rb is actually a RuleBook, add us to its contents and make rb
         *   our current location.
         */
        if(rb && rb.ofKind(RuleBook))
        {
            rb.addToContents(self);
            
            location = rb;
        }
        
        /* 
         *   Remove us from the contents of all our previous rulebook
         */
        rulebooks.forEach({r: r.removeFromContents(self)});
        
        /* Add our new RuleBooks to our list of rulebooks */
        if(rb)
            rulebooks += rb;
        
        /* Make rb our currently active rulebook */
        rulebook = rb;
        
    }
    
    /*  
     *   The value this rule should return when the stop macro is used at the
     *   end of its follow method. By default we use our rulebook's stopValue.
	 *   [RULES EXTENSION]
     */
    stopValue = (rulebook.stopValue)
    
    /* 
     *   The actor to use to compare with the who property of this Rule. This
     *   will normally be gPlayerChar, but the value of this property is taken
     *   from our RuleBook's actor property. [RULES EXTENSION]
     */
    actor = (rulebook == nil ? gPlayerChar : rulebook.actor)
    
    
    /* ------------------------------------------------------------------- */ 
     /* 
      *   One or more of the following properties, if defined, determine what
      *   conditions this Rule needs to match in order to be executed.
      */
      
    /* 
     *   A Room or Region, or a list of Rooms and/or Regions in which our actor
     *   (usually either gActor or gPlayerChar - the latter by default - must be
     *   for this Rule to match. [RULES EXTENSION]
     */
    // where = []
    
    /*  
     *   A condition that must hold (or a method returning a Boolean value to
     *   determine whether or not appropriate conditions hold) for this Rule to
     *   match. This is only needed if none of the other properties in this
     *   section provide a way of speficifying the required conditions.
     */
    // when() {}
    
    /* 
     *   An actor, or a list of actors, one of whom must be performing the
     *   current action for this Rule to match. [RULES EXTENSION]
     */
    // who = []
    
    /*  
     *   A Scene, or a list of Scenes, one of which much be currently happening
     *   for this Rule to match. [RULES EXTENSION]
     */
    // during = []
    
    /* 
     *   An action, or a list of Actions, one of which (e.g. Take or Jump) must
     *   be the current action in order for this Rule to match. [RULES EXTENSION]
     */
    // action = []
    
    /* 
     *   An object (or class), or a list of objects (and or classes) one of
     *   which of each the direct, indirect and accessory objects of the current
     *   action must match in order for this Rule to match. (The accessory
     *   object is only relevant if the TIAAction extension is in use).
	 *   [RULES EXTENSION]
     */
    // dobj = []
    // iobj = []
    // aobj = []
    
    /* 
     *   An object, class, or other value, or a list of objects and/or classes
     *   or of other values, one of which must match the matchObj property of
     *   our rulebook (which is set by the first parameter of a call to that
     *   RuleBooks's follow() method) for this Rule to match. [RULES EXTENSION]
     */ 
    // matchObj = []
    
    
    /*  
     *   An object in the presence of which the actor must be for this rule to
     *   match. Presence normally means in the same room, but if this property
     *   is defined as a list and the first item in the list is a property
     *   pointer (&canSee, &canHear, &canReach, &canSmell), this property will
     *   be used to test for tne appropriate sense connection between the actor
     *   and at least one of the other items in the list instead. [RULES EXTENSION]
     */
    // present = []
;

#ifdef __DEBUG
/* [RULES EXTENSION] include 'rules' in the list of debugging options. */
modify DebugCtl
   /* list of all debugging options */
    all = inherited + 'rules'
;
#endif
Adv3Lite Library Reference Manual
Generated on 03/07/2024 from adv3Lite version 2.1