RKPathMatcher Class Reference
| Inherits from | NSObject |
| Conforms to | NSCopying |
| Declared in | RKPathMatcher.h RKPathMatcher.m |
Overview
This class performs pattern matching and parameter parsing of strings, usually resource paths. It provides much of the necessary tools to map a given resource path to local objects (the inverse of RKRouter’s function). This makes it easier to implement RKManagedObjectCache, and generate fetched requests from a given resource path. There are two means of instantiating and using a matcher object in order to provide more flexibility in implementations, and to improve efficiency by eliminating repetitive and costly pattern initializations.
Tasks
-
+ matcherWithPath:Creates an RKPathMatcher starting from a resource path string. This method should be followed by matchesPattern:tokenizeQueryStrings:parsedArguments:
-
– matchesPattern:tokenizeQueryStrings:parsedArguments:Determines if the path string matches the provided pattern, and yields a dictionary with the resulting matched key/value pairs. Use of this method should be preceded by matcherWithPath: Pattern strings should include encoded parameter keys, delimited by a single colon at the beginning of the key name.
-
+ matcherWithPattern:Creates an RKPathMatcher starting from a pattern string. This method should be followed by matchesPath:tokenizeQueryStrings:parsedArguments: Patterns should include encoded parameter keys, delimited by a single colon at the beginning of the key name.
-
– matchesPath:tokenizeQueryStrings:parsedArguments:Determines if the provided resource path string matches a pattern, and yields a dictionary with the resulting matched key/value pairs. Use of this method should be preceded by matcherWithPattern:
-
– pathFromObject:This generates a resource path by interpolating the properties of the ‘object’ argument, assuming the existence of a previously specified pattern established via matcherWithPattern:. Otherwise, this method is identical in function to RKMakePathWithObject (in fact it is a shortcut for this method).
For example, given an ‘article’ object with an ‘articleID’ property value of 12345 …
-
– pathFromObject:addingEscapes:This generates a resource path by interpolating the properties of the ‘object’ argument, assuming the existence of a previously specified pattern established via matcherWithPattern:. Otherwise, this method is identical in function to RKMakePathWithObject (in fact it is a shortcut for this method).
Class Methods
matcherWithPath:
Creates an RKPathMatcher starting from a resource path string. This method should be followed by matchesPattern:tokenizeQueryStrings:parsedArguments:
+ (RKPathMatcher *)matcherWithPath:(NSString *)pathStringParameters
- pathString
The string to evaluate and parse, such as /districts/tx/upper/?apikey=GC5512354
Return Value
An instantiated RKPathMatcher without an established pattern.
Declared In
RKPathMatcher.hmatcherWithPattern:
Creates an RKPathMatcher starting from a pattern string. This method should be followed by matchesPath:tokenizeQueryStrings:parsedArguments: Patterns should include encoded parameter keys, delimited by a single colon at the beginning of the key name.
+ (RKPathMatcher *)matcherWithPattern:(NSString *)patternStringParameters
- patternString
The pattern to use for evaluating, such as /:entityName/:stateID/:chamber/
Return Value
An instantiated RKPathMatcher with an established pattern.
Discussion
NOTE 1 – Numerous colon-encoded parameter keys can be joined in a long pattern, but each key must be separated by at least one unmapped character. For instance, /:key1:key2:key3/ is invalid, whereas /:key1/:key2/:key3/ is acceptable.
NOTE 2 – The pattern matcher supports KVM, so :key1.otherKey normally resolves as it would in any other KVM situation, … otherKey is a sub-key on a the object represented by key1. This presents problems in circumstances where you might want to build a pattern like /:filename.json, where the dot isn’t intended as a sub-key on the filename, but rather part of the json static string. In these instances, you need to escape the dot with two backslashes, like so: /:filename\.json
Declared In
RKPathMatcher.hInstance Methods
matchesPath:tokenizeQueryStrings:parsedArguments:
Determines if the provided resource path string matches a pattern, and yields a dictionary with the resulting matched key/value pairs. Use of this method should be preceded by matcherWithPattern:
- (BOOL)matchesPath:(NSString *)pathString tokenizeQueryStrings:(BOOL)shouldTokenize parsedArguments:(NSDictionary **)argumentsParameters
- pathString
The string to evaluate and parse, such as /districts/tx/upper/?apikey=GC5512354
- shouldTokenize
If YES, any query parameters will be tokenized and inserted into the parsed argument dictionary.
- arguments
A pointer to a dictionary that contains the key/values from the pattern (and parameter) matching.
Return Value
A boolean indicating if the path string successfully matched the pattern.
Declared In
RKPathMatcher.hmatchesPattern:tokenizeQueryStrings:parsedArguments:
Determines if the path string matches the provided pattern, and yields a dictionary with the resulting matched key/value pairs. Use of this method should be preceded by matcherWithPath: Pattern strings should include encoded parameter keys, delimited by a single colon at the beginning of the key name.
- (BOOL)matchesPattern:(NSString *)patternString tokenizeQueryStrings:(BOOL)shouldTokenize parsedArguments:(NSDictionary **)argumentsParameters
- patternString
The pattern to use for evaluating, such as /:entityName/:stateID/:chamber/
- shouldTokenize
If YES, any query parameters will be tokenized and inserted into the parsed argument dictionary.
- arguments
A pointer to a dictionary that contains the key/values from the pattern (and parameter) matching.
Return Value
A boolean indicating if the path string successfully matched the pattern.
Discussion
NOTE 1 – Numerous colon-encoded parameter keys can be joined in a long pattern, but each key must be separated by at least one unmapped character. For instance, /:key1:key2:key3/ is invalid, whereas /:key1/:key2/:key3/ is acceptable.
NOTE 2 – The pattern matcher supports KVM, so :key1.otherKey normally resolves as it would in any other KVM situation, … otherKey is a sub-key on a the object represented by key1. This presents problems in circumstances where you might want to build a pattern like /:filename.json, where the dot isn’t intended as a sub-key on the filename, but rather part of the json static string. In these instances, you need to escape the dot with two backslashes, like so: /:filename\.json
Declared In
RKPathMatcher.hpathFromObject:
This generates a resource path by interpolating the properties of the ‘object’ argument, assuming the existence of a previously specified pattern established via matcherWithPattern:. Otherwise, this method is identical in function to RKMakePathWithObject (in fact it is a shortcut for this method).
For example, given an ‘article’ object with an ‘articleID’ property value of 12345 …
- (NSString *)pathFromObject:(id)objectParameters
- object
The object containing the properties to interpolate.
Return Value
A string with the object’s interpolated property values inserted into the receiver’s established pattern.
Discussion
RKPathMatcher matcher = [RKPathMatcher matcherWithPattern:@“/articles/:articleID”]; NSString resourcePath = [matcher pathFromObject:article];
… will produce a ‘resourcePath’ containing the string “/articles/12345”
See Also
Declared In
RKPathMatcher.hpathFromObject:addingEscapes:
This generates a resource path by interpolating the properties of the ‘object’ argument, assuming the existence of a previously specified pattern established via matcherWithPattern:. Otherwise, this method is identical in function to RKMakePathWithObject (in fact it is a shortcut for this method).
- (NSString *)pathFromObject:(id)object addingEscapes:(BOOL)addEscapesParameters
- object
The object containing the properties to interpolate.
- addEscapes
Conditionally add percent escapes to the interpolated property values
Return Value
A string with the object’s interpolated property values inserted into the receiver’s established pattern.
Discussion
For example, given an ‘article’ object with an ‘articleID’ property value of 12345 and a code of “This/That”…
RKPathMatcher matcher = [RKPathMatcher matcherWithPattern:@“/articles/:articleID/:code”]; NSString resourcePath = [matcher pathFromObject:article addingEscapes:YES];
… will produce a ‘resourcePath’ containing the string “/articles/12345/This%2FThat”
See Also
Declared In
RKPathMatcher.h