BDQualifier

Inherits from:
NSObject
Conforms to:
NSCopying
Declared in:
BDControl/BDQualifier.h

Class at a Glance

A BDQualifier is a predicate that can be evaluated against an object to determine whether an object matches a set of criteria. BDQualifier is a factory class commonly used to instantiate its various subclasses.


Class Description

A BDQualifier is a predicate that can be evaluated against an object to determine whether an object matches a set of criteria. Qualifiers can be created by instantiating the various concrete subclasses directly, or by passing a format string to +[BDQualifier qualifierWithFormat:].

To check whether an object matches the criteria specified in a qualifier, send that qualifier -evaluateWithObject:.

Comparison Operator Selectors

Some types of qualifiers support comparing two values. Any selector that returns a BOOL can be used for such qualifiers, but BDQualifier defines several built-in comparison selectors. These are defined by constants.

BDQualifierOperatorContains only applies to NSArrays (or other objects that respond to contains:). BDQualifierOperatorLike and BDQualifierOperatorCaseInsensitiveLike only apply to NSStrings (or other objects that respond to like: and caseInsensitiveLike:, respectively).

"Like" and "case-insensitive like" operators enable the use of the shell-style wildcards "?" and "*". For instance, to match all strings starting with "b", use the string "b*" with a "like" comparison. Or to match all strings the first letter "a" and the last letter "d", use the string "a?d" with a "like" comparison.

Qualifier Format Strings

Qualifier format strings are an extremely flexible way to create hierarchies of instances of BDQualifier's concrete subclasses. While direct instantiation provides greater flexibility, qualifier format strings provide superior ease of use for common cases.

Here are the forms for basic qualifier format strings:

parenthesized(qualifier)
Andqualifier and qualifier
Orqualifier or qualifier
Notnot qualifier
key comparisonkey1 selector key2
key valuekey selector number
key valuekey selector 'string'
key valuekey selector (class) 'string'
key valuekey selector $variable
key valuekey selector null
key valuekey selector nil
Boolean (YES)*true*
Boolean (NO)*false*

As can be expected, qualifiers may be arbitrarily nested.

Selectors in qualifier format strings are as described in the section "Comparison Operator Selectors" above. Selectors in qualifier format strings may also be any other Objective-C selector, followed by a colon. Note that the method signature for this selector must take a single id argument and return a BOOL value.

Values in qualifier format strings may be decimal numbers, strings surrounded by single quotation marks, "casted" strings preceded by an Objective-C class name in parenthesis, variable names preceded by a dollar sign, or null/nil. Strings may be UTF-8 encoded Unicode strings; they are not limited to US-ASCII.

A "casted" string causes the qualifier parser to look up the class name using NSClassFromString, create an instance of the class, and attempt to initialize it by sending it -initWithString: with the contents of the string. This makes it possible to include (for instance) NSDate objects in qualifier format strings; however, the string must be in the format the object is expecting. (This is counter-intuitive for NSDate; it must be in full international date format, as described in the documentation for -[NSDate initWithString:].)


Adopted Protocols

NSCopying
-copyWithZone:

Method Types

Initialization
+qualifierWithQualifierFormat:
+qualifierWithQualifierFormat:varargList:
+qualifierToMatchAllValues:
+qualifierToMatchAnyValue:
-qualifierWithBindings:requiresAllVariables:
-init
 
Evaluation
-evaluateWithObject
 
Operator Selectors
+operatorSelectorForString:
+stringForOperatorSelector:
+allQualifierOperators
+relationalQualifierOperators
 
Qualifier Keys
-allQualifierKeys
-addQualifierKeysToSet:
-validateKeysWithRootClassDescription:
 
Binding Keys
-bindingKeys
-keyPathForBindingKey:
 
Qualifier Expressions
-count
-subqualifiers

Class Methods

+allQualifierOperators

+ (NSArray *)allQualifierOperators

Returns an array containing the printable form of every default qualifier comparison selector. (That is, "=", "!=", "<", ">", "<=", ">=", "contains", "like", and "caseInsensitiveLike".)

+operatorSelectorForString:

+ (SEL)operatorSelectorForString:(NSString *)aString

Returns the selector corresponding to the printable form of a given qualifier comparison selector.

+qualifierToMatchAllValues:

+ (BDQualifier *)qualifierToMatchAllValues:(NSDictionary *)bindings

Returns a qualifier that will match all values in the dictionary. This is a BDAndQualifier containing one BDKeyValueQualifier for each object in the dictionary.

+qualifierToMatchAnyValue:

+ (BDQualifier *)qualifierToMatchAnyValue:(NSDictionary *)bindings

Returns a qualifier that will match any value in the dictionary. This is a BDOrQualifier containing one BDKeyValueQualifier for each object in the dictionary.

+qualifierWithQualifierFormat:

+ (BDQualifier *)qualifierWithQualifierFormat:(NSString *)qualifierFormat, ...

Returns a qualifier created by parsing the given format string. The format string is converted to a string to pass to the parser with -[NSString stringWithFormat:], so any formatting directives appropriate in -[NSString stringWithFormat:] will work here.

+qualifierWithQualifierFormat:varargList:

+ (BDQualifier *)qualifierWithQualifierFormat:(NSString *)qualifierFormat varargList:(va_list)args

Returns a qualifier created by parsing the given format string. The format string is converted to a string to pass to the parser with -[NSString stringWithFormat:], so any formatting directives appropriate in -[NSString stringWithFormat:] will work here.

+relationalQualifierOperators

+ (NSArray *)relationalQualifierOperators

Returns an array of all of the printable forms of the non-array, non-string qualifier comparison selectors. (That is, "=", "!=", "<", ">", "<=", and ">=".)

+stringForOperatorSelector:

+ (NSString *)stringForOperatorSelector:(SEL)aSelector

Returns the printable string for a given qualifier comparison selector.


Instance Methods

-addQualifierKeysToSet:

- (void)addQualifierKeysToSet:(NSMutableSet *)qualKeys

Adds the key paths for this qualifier to the given mutable set.

Override this method in subclasses that can have keys or sub-qualifiers.

-allQualifierKeys

- (NSArray *)allQualifierKeys

Returns all of the key paths used in the qualifier.

Subclasses should not need to override this method; override -addQualifierKeysToSet: instead.

-bindingKeys

- (NSArray *)bindingKeys

Returns all of the binding keys (variables) used in this qualifier.

Override this method in subclasses that can use BDQualifierVariable instances or that can have sub-qualifiers.

-count

- (int)count

Returns the number of qualifiers in the qualifier expression rooted at this qualifier.

Override this method in subclasses that can have sub-qualifiers.

-evaluateWithObject:

- (BOOL)evaluateWithObject:(NSArray *)object

Evaluates the qualifier using the given object as the root for all key paths. Returns YES if all conditions in the qualifier were matched by the object, NO otherwise.

BDQualifier's implementation always returns NO.

Override this method in concrete subclasses, and declare that the subclass implements the BDQualifierEvaluation protocol.

-init

- (id)init

Initializes a BDQualifier instance. This is BDQualifier's designated initializer, which subclasses should send to super. However, subclasses do not need to override this method.

-keyPathForBindingKey:

- (NSString *)keyPathForBindingKey:(NSString *)key

Given a variable key, returns the first key path in the qualifier which that variable key is compared against.

Override this method in subclasses that can use BDQualifierVariable instances or that can have sub-qualifiers.

-qualifierWithBindings:requiresAllVariables:

- (BDQualifier *)qualifierWithBindings:(NSDictionary *)bindings requiresAllVariables:(BOOL)requiresAll

Returns a new qualifier by replacing all possible variables in the qualifier with values from the bindings dictionary. If requiresAll is YES and a binding cannot be found in the bindings dictionary, this method raises a BDQualifierVariableSubstitutionException exception. If requiresAll is NO and a binding cannot be found in the bindings dictionary, this method "prunes" the qualifier containing that binding from the returned qualifier. If this qualifier is the one to be pruned, this method returns nil.

If this method returns a qualifier, that qualifier should always be safe to evaluate.

Override this method in subclasses that can use BDQualifierVariable instances or that can have sub-qualifiers.

-subqualifiers

- (NSArray *)subqualifiers

Returns all of the direct sub-qualifiers of this qualifier. Returns nil if this qualifier does not support sub-qualifiers. Returns an empty array if this qualifier does support sub-qualifiers but currently has none.

Note that only direct sub-qualifiers are returned; this method does not recurse through an entire qualifier expression.

Override this method in subclasses that can have sub-qualifiers.

-validateKeysWithRootClassDescription:

- (NSException *)validateKeysWithRootClassDescription:(NSClassDescription *)classDesc

Currently unimplemented; always returns nil.

This method validates all of the key paths in the qualifier against the given class description. If any key is unreachable, it returns an NSInternalInconsistencyException. Otherwise, it returns nil.

Override this method in subclasses that can have keys or sub-qualifiers.


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