- Inherits from:
- NSObject
- Conforms to:
- NSCopying
- Declared in:
- BDControl/BDQualifier.h
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.
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:
.
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.
isEqualTo:
, "=" or "==")isNotEqualTo:
, "!=")isLessThan:
, "<")isGreaterThan:
, ">")isLessThanOrEqualTo:
, "<=")isGreaterThanOrEqualTo:
, ">=")contains:
, "contains")like:
, "like")caseInsensitiveLike:
, "caseInsensitiveLike")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 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) |
And | qualifier and qualifier |
Or | qualifier or qualifier |
Not | not qualifier |
key comparison | key1 selector key2 |
key value | key selector number |
key value | key selector 'string' |
key value | key selector (class) 'string' |
key value | key selector $variable |
key value | key selector null |
key value | key 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:]
.)
- NSCopying
- -copyWithZone:
- 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
+ (NSArray *)allQualifierOperators
Returns an array containing the printable form of every default qualifier comparison selector. (That is, "=", "!=", "<", ">", "<=", ">=", "contains", "like", and "caseInsensitiveLike".)
+ (SEL)operatorSelectorForString:(NSString *)aString
Returns the selector corresponding to the printable form of a given qualifier comparison selector.
+ (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.
+ (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.
+ (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.
+ (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.
+ (NSArray *)relationalQualifierOperators
Returns an array of all of the printable forms of the non-array, non-string qualifier comparison selectors. (That is, "=", "!=", "<", ">", "<=", and ">=".)
+ (NSString *)stringForOperatorSelector:(SEL)aSelector
Returns the printable string for a given qualifier comparison selector.
- (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.
- (NSArray *)allQualifierKeys
Returns all of the key paths used in the qualifier.
Subclasses should not need to override this method; override -addQualifierKeysToSet:
instead.
- (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.
- (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.
- (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.
- (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.
- (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.
- (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.
- (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.
- (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.