- Inherits from:
- NSObject
- Declared in:
- BDRuleEngine/BDRuleContext.h
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.
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.
- 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:
- (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.
- (id)init
Initializes an instance of BDRuleContext with no model.
- (id)initWithModel:(BDRuleModel *)model
Initializes an instance of BDRuleContext with the given model. This is the designated initializer for this class.
- (BDRuleModel *)model
Returns the rule model this context is currently using.
- (void)setModel:(BDRuleModel *)value
Sets the context to use the given rule model.
- (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.
- (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.
- (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.
- (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.
- (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.