Inherits from NSObject
Conforms to NSCopying
Declared in RKPathMatcher.h

Overview

The RKPathMatcher class performs pattern matching and parameter parsing of strings, typically representing the path portion of an NSURL object. It provides much of the necessary tools to map a given path to local objects (the inverse of RKRouter’s function). This makes it easier to implement the RKManagedObjectCaching protocol and generate NSFetchRequest objects from a given 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

Matching Paths to Patterns

Matching Patterns to Paths

Creating Paths from Objects

Class Methods

pathMatcherWithPath:

Creates a path match object starting from a path string. This method should be followed by matchesPattern:tokenizeQueryStrings:parsedArguments:

+ (instancetype)pathMatcherWithPath:(NSString *)pathString

Parameters

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.h

pathMatcherWithPattern:

Creates a path matcher object 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.

+ (instancetype)pathMatcherWithPattern:(NSString *)patternString

Parameters

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.h

Instance Methods

matchesPath:tokenizeQueryStrings:parsedArguments:

Determines if the given path string matches a pattern, and yields a dictionary with the resulting matched key/value pairs. Use of this method should be preceded by pathMatcherWithPattern:.

- (BOOL)matchesPath:(NSString *)pathString tokenizeQueryStrings:(BOOL)shouldTokenize parsedArguments:(NSDictionary **)arguments

Parameters

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 value indicating if the path string successfully matched the pattern.

Declared In

RKPathMatcher.h

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 pathMatcherWithPath: 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 **)arguments

Parameters

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 value 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.h

pathFromObject:addingEscapes:interpolatedParameters:

Generates a path by interpolating the properties of the ‘object’ argument, assuming the existence of a previously specified pattern established via pathMatcherWithPattern:. Otherwise, this method is identical in function to RKPathFromPatternWithObject (in fact it is a shortcut for this method).

- (NSString *)pathFromObject:(id)object addingEscapes:(BOOL)addEscapes interpolatedParameters:(NSDictionary **)interpolatedParameters

Parameters

object

The object containing the properties to interpolate.

addEscapes

Conditionally add percent escapes to the interpolated property values

interpolatedParameters

On input, a pointer for a dictionary object. When the path pattern of the receiver is interpolated, this pointer is set to a new dictionary object in which the keys correspond to the named parameters within the path pattern and the values are taken from the corresponding keypaths of the interpolated object .

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 pathMatcherWithPattern:@"/articles/:articleID/:code"];
 NSString *path = [matcher pathFromObject:article addingEscapes:YES interpolatedParameters:nil];

… will produce a ‘path’ containing the string @"/articles/12345/This%2FThat"

Declared In

RKPathMatcher.h