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

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]]

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

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

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

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

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

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

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

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

Discussion

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

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]]

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