Inherits from NSObject
Declared in GRMustacheContext.h

Overview

The GRMustacheContext represents a Mustache rendering context: it internally maintains three stacks:

  • a context stack, that makes it able to provide the current context object, and to perform key lookup.

  • a priority context stack, whose objects define important keys that should not be overriden.

  • a tag delegate stack, so that tag delegates are notified when a Mustache tag is rendered.

Companion guides:

Warning: GRMustacheContext is not suitable for subclassing.

Properties

topMustacheObject

Returns the object at the top of the receiver’s context stack.

@property (nonatomic, readonly) id topMustacheObject

Return Value

The object at the top of the receiver’s context stack.

Availability

v6.7

Discussion

The returned object is the same as the one that would be rendered by a {{ . }} tag.

user = ...;
context = [GRMustacheContext contextWithObject:user];
context.topMustacheObject;  // user

Declared In

GRMustacheContext.h

unsafeKeyAccess

Returns whether this context allows unsafe key access or not.

@property (nonatomic, readonly) BOOL unsafeKeyAccess

Availability

v7.0

Declared In

GRMustacheContext.h

Class Methods

context

Returns an empty rendering context.

+ (instancetype)context

Return Value

A rendering context.

Availability

v6.4

Discussion

Empty contexts do not provide any value for any key.

If you wish to use the services provided by the GRMustache standard library, you should create a context with the [GRMustacheContext contextWithObject:] method, like this:

[GRMustacheContext contextWithObject:[GRMustache standardLibrary]]

Declared In

GRMustacheContext.h

contextWithObject:

Returns a rendering context containing a single object.

+ (instancetype)contextWithObject:(id)object

Parameters

object

An object

Return Value

A rendering context.

Availability

v6.4

Discussion

Keys defined by object gets available for template rendering.

context = [GRMustacheContext contextWithObject:@{ @"name": @"Arthur" }];
[context valueForMustacheKey:@"name"];   // @"Arthur"

If object conforms to the GRMustacheTemplateDelegate protocol, it is also made the top of the tag delegate stack.

Companion guide: https://github.com/groue/GRMustache/blob/master/Guides/delegate.md

Declared In

GRMustacheContext.h

contextWithProtectedObject:

Returns a context containing a single priority object.

+ (instancetype)contextWithProtectedObject:(id)object

Parameters

object

An object

Return Value

A rendering context.

Availability

v6.4

Discussion

Keys defined by object are given priority, which means that they can not be overriden by other objects that will eventually enter the context stack.

// Create a context with a priority `precious` key
context = [GRMustacheContext contextWithProtectedObject:@{ @"precious": @"gold" }];

// Derive a new context by attempting to override the `precious` key:
context = [context contextByAddingObject:@{ @"precious": @"lead" }];

// Priority keys can't be overriden
[context valueForMustacheKey:@"precious"];   // @"gold"

Companion guide: https://github.com/groue/GRMustache/blob/master/Guides/security.md#priority-keys

Declared In

GRMustacheContext.h

contextWithTagDelegate:

Returns a context containing a single tag delegate.

+ (instancetype)contextWithTagDelegate:(id<GRMustacheTagDelegate>)tagDelegate

Parameters

tagDelegate

A tag delegate

Return Value

A rendering context.

Availability

v6.4

Discussion

tagDelegate will be notified of the rendering of all tags rendered from the receiver or from contexts derived from the receiver.

Unlike contextWithObject: and contextWithProtectedObject:, tagDelegate will not provide any key to the templates. It will only be notified of the rendering of tags.

Companion guide: https://github.com/groue/GRMustache/blob/master/Guides/delegate.md

Declared In

GRMustacheContext.h

contextWithUnsafeKeyAccess

Returns a new context with unsafe key access.

+ (instancetype)contextWithUnsafeKeyAccess

Availability

v7.0

Discussion

Unsafe key access allows this context, and all contexts derived from it, to access keys that are normally forbidden: keys that are not declared as Objective-C properties, or keys that do not belong to the result of the safeMustacheKeys method.

Compare:

@interface DBRecord : NSObject
- (void)deleteRecord;
@end

@implementation DBRecord
- (void)deleteRecord
{
    NSLog(@"Oooops, your record was just deleted!");
}
@end

DBRecord *record = ...;
NSString *templateString = @"{{ deleteRecord }}";
GRMustacheTemplate * template = [GRMustacheTemplate templateWithString:templateString error:NULL];

// Safe rendering of the dangerous template: record is not deleted.
[template renderObject:record error:NULL];

// Unsafe rendering of the dangerous template: record is deleted.
template.baseContext = [GRMustacheContext contextWithUnsafeKeyAccess];
[template renderObject:record error:NULL];

Companion guide: https://github.com/groue/GRMustache/blob/master/Guides/security.md

Declared In

GRMustacheContext.h

Instance Methods

contextByAddingObject:

Returns a new rendering context that is the copy of the receiver, and the given object added at the top of the context stack.

- (instancetype)contextByAddingObject:(id)object

Parameters

object

An object

Return Value

A new rendering context.

Availability

v6.0

Discussion

Keys defined by object gets available for template rendering, and override the values defined by objects already contained in the context stack. Keys unknown to object will be looked up deeper in the context stack.

context = [GRMustacheContext contextWithObject:@{ @"a": @"ignored", @"b": @"foo" }];
context = [context contextByAddingObject:@{ @"a": @"bar" }];

// `a` is overriden
[context valueForMustacheKey:@"a"];   // @"bar"

// `b` is inherited
[context valueForMustacheKey:@"b"];   // @"foo"

object can not override keys defined by the objects of the priority context stack, though. See contextWithProtectedObject: and contextByAddingProtectedObject:.

If object conforms to the GRMustacheTemplateDelegate protocol, it is also added at the top of the tag delegate stack.

Companion guide: https://github.com/groue/GRMustache/blob/master/Guides/delegate.md

Declared In

GRMustacheContext.h

contextByAddingProtectedObject:

Returns a new rendering context that is the copy of the receiver, and the given object added at the top of the priority context stack.

- (instancetype)contextByAddingProtectedObject:(id)object

Parameters

object

An object

Return Value

A new rendering context.

Availability

v6.0

Discussion

Keys defined by object are given priority, which means that they can not be overriden by other objects that will eventually enter the context stack.

// Derive a context with a priority `precious` key
context = [context contextByAddingProtectedObject:@{ @"precious": @"gold" }];

// Derive a new context by attempting to override the `precious` key:
context = [context contextByAddingObject:@{ @"precious": @"lead" }];

// Priority keys can't be overriden
[context valueForMustacheKey:@"precious"];   // @"gold"

Companion guide: https://github.com/groue/GRMustache/blob/master/Guides/security.md#priority-keys

Declared In

GRMustacheContext.h

contextByAddingTagDelegate:

Returns a new rendering context that is the copy of the receiver, and the given object added at the top of the tag delegate stack.

- (instancetype)contextByAddingTagDelegate:(id<GRMustacheTagDelegate>)tagDelegate

Parameters

tagDelegate

A tag delegate

Return Value

A new rendering context.

Availability

v6.0

Discussion

tagDelegate will be notified of the rendering of all tags rendered from the receiver or from contexts derived from the receiver.

Unlike contextByAddingObject: and contextByAddingProtectedObject:, tagDelegate will not provide any key to the templates. It will only be notified of the rendering of tags.

Companion guide: https://github.com/groue/GRMustache/blob/master/Guides/delegate.md

Declared In

GRMustacheContext.h

contextWithUnsafeKeyAccess

Returns a new rendering context that is the copy of the receiver, with unsafe key access.

- (instancetype)contextWithUnsafeKeyAccess

Availability

v7.0

Discussion

Unsafe key access allows this context, and all contexts derived from it, to access keys that are normally forbidden: keys that are not declared as Objective-C properties, or keys that do not belong to the result of the safeMustacheKeys method.

Compare:

@interface DBRecord : NSObject
- (void)deleteRecord;
@end

@implementation DBRecord
- (void)deleteRecord
{
    NSLog(@"Oooops, your record was just deleted!");
}
@end

DBRecord *record = ...;
NSString *templateString = @"{{ deleteRecord }}";
GRMustacheTemplate * template = [GRMustacheTemplate templateWithString:templateString error:NULL];

// Safe rendering of the dangerous template: record is not deleted.
[template renderObject:record error:NULL];

// Unsafe rendering of the dangerous template: record is deleted.
template.baseContext = [template.baseContext contextWithUnsafeKeyAccess];
[template renderObject:record error:NULL];

Companion guide: https://github.com/groue/GRMustache/blob/master/Guides/security.md

Declared In

GRMustacheContext.h

hasValue:forMustacheExpression:error:

Evaluates an expression such as name, or uppercase(user.name).

- (BOOL)hasValue:(id *)value forMustacheExpression:(NSString *)expression error:(NSError **)error

Parameters

value

Upon return contains the value of the expression.

expression

An expression.

error

If there is an error computing the value, upon return contains an NSError object that describes the problem.

Return Value

YES if the value could be computed.

Availability

v6.8

Declared In

GRMustacheContext.h

init

Returns an initialized empty rendering context.

- (instancetype)init

Return Value

A rendering context.

Discussion

Empty contexts do not provide any value for any key.

If you wish to use the services provided by the GRMustache standard library, you should create a context with the [GRMustacheContext contextWithObject:] method, like this:

[GRMustacheContext contextWithObject:[GRMustache standardLibrary]]

Declared In

GRMustacheContext.h

valueForMustacheKey:

Returns the value stored in the context stack for the given key.

- (id)valueForMustacheKey:(NSString *)key

Parameters

key

a key such as @“name”

Return Value

The value found in the context stack for the given key.

Availability

v6.6

Discussion

If you want the value for an full expression such as user.name or uppercase(user.name), use the hasValue:forMustacheExpression:error: method.

Search Pattern for valueForMustacheKey

The Mustache value of any object for a given key is defined as:

  1. If the object responds to the objectForKeyedSubscript: instance method, return the result of this method.

  2. Otherwise, build the list of safe keys:

  3. If the object responds to the safeMustacheKeys class method defined by the GRMustacheSafeKeyAccess protocol, use this method.
  4. Otherwise, use the list of Objective-C properties declared with @property.
  5. If object is an instance of NSManagedObject, add all the attributes of its Core Data entity.

  6. If the key belongs to the list of safe keys, return the result of the valueForKey: method, unless this method throws NSUndefinedKeyException.

  7. Otherwise, return nil.

Contexts with unsafe key access skip the key validation step.

In this method, the following search pattern is used:

  1. Searches the priority context stack for an object that has a non-nil Mustache value for the key.

  2. Otherwise (irrelevant priority context stack), search the context stack for an object that has a non-nil Mustache value for the key.

  3. If none of the above situations occurs, returns nil.

Companion guides: https://github.com/groue/GRMustache/blob/master/Guides/runtime.md, https://github.com/groue/GRMustache/blob/master/Guides/view_model.md

Declared In

GRMustacheContext.h