BDRuleContext

Inherits from:
NSObject
Declared in:
BDRuleEngine/BDRuleContext.h

Class at a Glance

A BDRuleContext is the primary interface of an application to the rule system. It respresents a context within which the rule system can operate. To use the rule system, a context is populated with values and then interrogated. Both are done via the standard key-value coding mechanism.


Class Description

A BDRuleContext is the primary interface of an application to the rule system. It respresents a context within which the rule system can operate. To use the rule system, a context is populated with values and then interrogated. Both are done via the standard key-value coding mechanism.

When a context is asked for the value of a key for which it doesn't have a stored value, it will use its associated rule model to find the value of the key. If no value is found, it will return nil.

One common operation in applications is to iterate over a collection of values, storing each one in turn under a specific key within the context and then looking up a second specific key. The convenience method -valuesForKeyPath:takingSuccessiveValues:forKeyPath: is provided to automate this. For instance, to determine how to color stock values based on whether they have risen or fallen, you can use the following expression:

- (NSArray *)colorsForStocks:(NSArray *)stocks
{
    [myRuleContext valuesForKeyPath:@"color"
             takingSuccessiveValues:stocks
                         forKeyPath:@"stock"];
}

Assuming myRuleContext is attached to a rule model with appropriate rules, this will return an array of colors to use in your application's interface for each stock in stocks.

For convenience, users may wish to subclass BDRuleContext and provide additional accessors representing commonly-accessed keys. Subclasses should avoid overriding -valueForKey:, -takeValueForKey:, -inferredValueForKey:, and -valuesForKeyPath:takingSuccessiveValues:forKeyPath:. Instead, subclasses should use -storedValueForKey: and -takeStoredValueForKey: within their accessors; this ensures that values for the convenience accessors get added to the stored values dictionary instead of using the rule system.

Note: No caching of evaluated rules is currently performed. This could cause large or complex rulesets to be slow.


Method Types

Initialization
-init
-initWithModel:
Accessors
-setKeyPath:
-keyPath
Key-Value Coding
-valueForKey:
-takeValue:forKey:
-storedValueForKey:
-takeStoredValue:forKey:
Inferring Values
-inferredValueForKey:
Retrieving Multiple Successive Values
valuesForKeyPath:takingSuccessiveValues:forKeyPath:

Instance Methods

inferredValueForKey:

- (void)inferredValueForKey:(NSString *)key

Consults the rule system for the value corresponding to key. The context's rule model is consulted for a set of candidate rules for key. Each resulting rule's left-hand side qualifier is evaluated against the context in turn. The first rule whose left-hand side qualifier evaluates to YES is fired, and the value of its right-hand side assignment returned.

-init

- (id)init

Initializes an instance of BDRuleContext with no model.

-initWithModel:

- (id)initWithModel:(BDRuleModel *)model

Initializes an instance of BDRuleContext with the given model. This is the designated initializer for this class.

model

- (BDRuleModel *)model

Returns the rule model this context is currently using.

setModel:

- (void)setModel:(BDRuleModel *)value

Sets the context to use the given rule model.

storedValueForKey:

- (void)storedValueForKey:(NSString *)key

Returns the stored value for the given key in the context. If there is a stored value for this key (that is, a value that was set using -takeValue:forKey:) the stored value is returned. If there is no stored value, nil is returned.

In subclasses, this is what accessor methods should use.

takeStoredValue:ForKey:

- (void)takeStoredValue:(id)value forKey:(NSString *)key

Sets the stored value for the given key in the context. This just modifies the stored value within the context; the rule system is not consulted.

If value is nil, it removes any stored value for key from the context.

In subclasses, this is what accessor methods should use.

takeValue:ForKey:

- (void)takeValue:(id)value forKey:(NSString *)key

Sets the value for the given key in the context. This just modifies the stored value within the context; the rule system is not consulted.

valueForKey:

- (void)valueForKey:(NSString *)key

Returns the value for the given key in the context. If there is a stored value for this key (that is, a value that was set using -takeValue:forKey:) the stored value is returned. If there is no stored value, the rule system is consulted via -inferredValueForKey:. If the rule system also does not resolve the key, nil is returned.

valuesForKeyPath:takingSuccessiveValues:forKeyPath:

- (void)valuesForKeyPath:(NSString *)keyPath takingSuccessiveValues:(NSArray *)values forKeyPath:(NSString *)valueKeyPath

This convenience method prevents you from having to enumerate over an array of values to use the rule system to determine information about each one. It is equivalent to iterating over values, sending the context -takeValue:forKey: with each element of values in turn for valueKeyPath, and then sending the context -valueForKey: to look up the value at keyPath.


Copyright © 2002, 2003 bDistributed.com, Inc. All rights reserved worldwide.