Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 442 lines (297 sloc) 18.724 kb
48b63af @groue ViewModel guide
authored
1 [up](../../../../GRMustache#documentation), [next](view_model.md)
1a1555f @groue guides wip
authored
2
6aa657e @groue guides wip
authored
3 GRMustache runtime
4 ==================
1a1555f @groue guides wip
authored
5
46f5ea1 @groue ViewModel Guide WIP
authored
6 You'll learn here how your data is rendered. The loading of templates is covered in the [Templates Guide](templates.md). Common patterns for feeding templates are described in the [ViewModel Guide](view_model.md).
e1ce058 @groue Simplify the Runtime Guide
authored
7
e450983 @groue Guides WIP
authored
8 - [How keys are accessed](#how-keys-are-accessed)
9 - [Variable tags](#variable-tags)
10 - [Expressions](#expressions)
11 - [Section tags](#section-tags)
12 - [The context stack](#the-context-stack)
13 - [Fine tuning of key lookup](#fine-tuning-of-key-lookup)
14 - [Detailed description of GRMustache handling of `valueForKey:`](#detailed-description-of-grmustache-handling-of-valueforkey)
15 - [Compatibility with other Mustache implementations](#compatibility-with-other-mustache-implementations)
16
17 How keys are accessed
18 ---------------------
e1ce058 @groue Simplify the Runtime Guide
authored
19
71c17a1 @groue Safe Key Access documentation
authored
20 Most Mustache tags will look for keys in your rendered objects. In the example below, the `{{name}}` tag fetches the key `name` from a dictionary, leading to the "Hello Arthur!" rendering:
cc892a6 @groue Runtime Guide clean up
authored
21
22 ```objc
71c17a1 @groue Safe Key Access documentation
authored
23 NSDictionary *dictionary = @{ @"name": @"Arthur" };
24 NSString *rendering = [GRMustacheTemplate renderObject:dictionary fromString:@"Hello {{name}}!" error:NULL];
25 ```
e1ce058 @groue Simplify the Runtime Guide
authored
26
71c17a1 @groue Safe Key Access documentation
authored
27 Dictionaries are an easy way to provide keys. Your own custom objects can be rendered as well, as long as they declare properties for keys used in templates:
28
29 ```objc
30 @interface Person : NSObject
31 @property (nonatomic) NSString *name;
32 @end
33
34 NSDictionary *person = [[Person alloc] init];
35 person.name = @"Arthur";
36
37 // "Hello Arthur!"
38 NSString *rendering = [GRMustacheTemplate renderObject:person fromString:@"Hello {{name}}!" error:NULL];
e1ce058 @groue Simplify the Runtime Guide
authored
39 ```
40
71c17a1 @groue Safe Key Access documentation
authored
41 Precisely, here is how keys are fetched:
3f366df @groue v6.9.0
authored
42
71c17a1 @groue Safe Key Access documentation
authored
43 1. If the object responds to the [keyed subscripting](http://clang.llvm.org/docs/ObjectiveCLiterals.html#dictionary-style-subscripting) `objectForKeyedSubscript:` method, this method is used.
44 2. Otherwise, if the key is safe, then the `valueForKey:` method is used.
45 3. Otherwise, the key is considered missed.
e1ce058 @groue Simplify the Runtime Guide
authored
46
71c17a1 @groue Safe Key Access documentation
authored
47 By default, a key is *safe* if it is backed by a declared Objective-C property, or a Core Data attribute (for managed objects).
cc892a6 @groue Runtime Guide clean up
authored
48
6871be7 @groue Rewrite documentation for default values for any keys
authored
49 You can mitigate this limitation, though. For example, `-[NSArray count]` is a method, not a property. However, GRMustache can render `{{ items.count }}`. This is because NSArray conforms to the `GRMustacheSafeKeyAccess` protocol. Check the [Security Guide](security.md#safe-key-access) for more information.
cc892a6 @groue Runtime Guide clean up
authored
50
51
71c17a1 @groue Safe Key Access documentation
authored
52 Variable tags
53 -------------
e1ce058 @groue Simplify the Runtime Guide
authored
54
71c17a1 @groue Safe Key Access documentation
authored
55 Variable tags `{{ name }}`, `{{{ name }}}` and `{{& name }}` look for the `name` key in the object you provide, and render the returned value.
cc892a6 @groue Runtime Guide clean up
authored
56
71c17a1 @groue Safe Key Access documentation
authored
57 `{{ name }}` renders HTML-escaped values, when `{{{ name }}}` and `{{& name }}` render unescaped values (the two last forms are equivalent).
cc892a6 @groue Runtime Guide clean up
authored
58
71c17a1 @groue Safe Key Access documentation
authored
59 Most objects are rendered with the `description` [standard method](http://developer.apple.com/documentation/Cocoa/Reference/Foundation/Protocols/NSObject_Protocol/Reference/NSObject.html).
60
61 Objects conforming to the [NSFastEnumeration](http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Chapters/ocFastEnumeration.html) protocol (but NSDictionary), such as NSArray are rendered as the concatenation of their elements:
e1ce058 @groue Simplify the Runtime Guide
authored
62
63 ```objc
64 id data = @{ @"voyels": @[@"A", @"E", @"I", @"O", @"U"] };
cc892a6 @groue Runtime Guide clean up
authored
65
e1ce058 @groue Simplify the Runtime Guide
authored
66 // Renders "AEIOU"
67 NSString *rendering = [GRMustacheTemplate renderObject:data
68 fromString:@"{{voyels}}"
69 error:NULL];
70 ```
cc892a6 @groue Runtime Guide clean up
authored
71
71c17a1 @groue Safe Key Access documentation
authored
72 Finally, objects that implement the `GRMustacheRendering` protocol take full charge of their own rendering. See the [Rendering Objects Guide](rendering_objects.md) for further details.
73
4f170ea @groue Typos
authored
74
e1ce058 @groue Simplify the Runtime Guide
authored
75 Expressions
76 -----------
cc892a6 @groue Runtime Guide clean up
authored
77
e1ce058 @groue Simplify the Runtime Guide
authored
78 Variable tags render simple keys as seen above, and, more generally, *expressions*, such as the key path `person.name` and the filtered expression `uppercase(person.name)`.
cc892a6 @groue Runtime Guide clean up
authored
79
e1ce058 @groue Simplify the Runtime Guide
authored
80 ```objc
81 Person *craig = [Person personWithName:@"Craig"];
82 id data = @{ @"person": craig };
cc892a6 @groue Runtime Guide clean up
authored
83
e1ce058 @groue Simplify the Runtime Guide
authored
84 // Renders "Hello CRAIG!"
85 NSString *rendering = [GRMustacheTemplate renderObject:data
86 fromString:@"Hello {{ uppercase(person.name) }}!"
87 error:NULL];
88 ```
cc892a6 @groue Runtime Guide clean up
authored
89
47e5bc1 @groue Documentation and cleanup obsolete sample code
authored
90 GRMustache first looks for the `person` key, extracts its `name`, and applies the `uppercase` built-in filter of the [standard library](standard_library.md#uppercase). The variable tag eventually renders the resulting string.
1a1555f @groue guides wip
authored
91
92
e1ce058 @groue Simplify the Runtime Guide
authored
93 Section tags
94 ------------
1a1555f @groue guides wip
authored
95
e1ce058 @groue Simplify the Runtime Guide
authored
96 The rendering of section tags such as `{{# name }}...{{/ name }}` and `{{^ name }}...{{/ name }}` depend on the value attached to the `name` expression.
97
b9bec57 @groue Wording
authored
98 Generally speaking, *inverted sections* `{{^ name }}...{{/ name }}` render when *regular sections* `{{# name }}...{{/ name }}` do not. You can think of the caret `^` as the Mustache "unless".
e1ce058 @groue Simplify the Runtime Guide
authored
99
100 Precisely speaking:
101
102 ### False sections
103
104 If the value is *false*, regular sections are omitted, and inverted sections rendered:
105
106 ```objc
107 id data = @{ @"red": @NO, @"blue": @YES };
108
109 // Renders "Not red"
110 NSString *rendering = [GRMustacheTemplate renderObject:data
111 fromString:@"{{#red}}Red{{/red}}{{^red}}Not red{{/red}}"
112 error:NULL];
113
114 // Renders "Blue"
115 NSString *rendering = [GRMustacheTemplate renderObject:data
116 fromString:@"{{#blue}}Blue{{/blue}}{{^blue}}Not blue{{/blue}}"
117 error:NULL];
118
119 ```
120
bd73358 @groue Wording
authored
121 When an inverted sections follows a regular section with the same expression, you can use the short `{{# name }}...{{^ name }}...{{/ name }}` form, avoiding the closing tag for `{{# name }}`. Think of "if ... else ... end". For brevity's sake, you can also omit the expression after the opening tag: `{{#name}}...{{^}}...{{/}}` is valid.
cc892a6 @groue Runtime Guide clean up
authored
122
e1ce058 @groue Simplify the Runtime Guide
authored
123 The full list of false values are:
cc892a6 @groue Runtime Guide clean up
authored
124
e1ce058 @groue Simplify the Runtime Guide
authored
125 - `nil` and missing keys
cc892a6 @groue Runtime Guide clean up
authored
126 - `[NSNull null]`
127 - `NSNumber` instances whose `boolValue` method returns `NO`
7704634 @groue Runtime Guide WIP
authored
128 - empty strings `@""`
e1ce058 @groue Simplify the Runtime Guide
authored
129 - empty enumerables.
cc892a6 @groue Runtime Guide clean up
authored
130
e1ce058 @groue Simplify the Runtime Guide
authored
131 They all prevent Mustache sections `{{# name }}...{{/ name }}` rendering.
cc892a6 @groue Runtime Guide clean up
authored
132
e1ce058 @groue Simplify the Runtime Guide
authored
133 They all trigger inverted sections `{{^ name }}...{{/ name }}` rendering.
cc892a6 @groue Runtime Guide clean up
authored
134
e1ce058 @groue Simplify the Runtime Guide
authored
135 ### Enumerable sections
cc892a6 @groue Runtime Guide clean up
authored
136
7e94c24 @groue Wording
authored
137 If the value attached to a section conforms to the [NSFastEnumeration](http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Chapters/ocFastEnumeration.html) protocol (except NSDictionary), regular sections are rendered as many times as there are items in the enumerable object:
cc892a6 @groue Runtime Guide clean up
authored
138
e1ce058 @groue Simplify the Runtime Guide
authored
139 ```objc
140 NSArray *friends = @[
141 [Person personWithName:@"Dennis"],
142 [Person personWithName:@"Eugene"],
143 [Person personWithName:@"Fiona"]];
144 id data = @{ @"friends": friends };
145
146 NSString *templateString = @"My friends are:\n"
147 @"{{# friends }}"
148 @"- {{ name }}\n"
149 @"{{/ friends }}";
150
4f170ea @groue Typos
authored
151 // My friends are:
e1ce058 @groue Simplify the Runtime Guide
authored
152 // - Dennis
153 // - Eugene
154 // - Fiona
155 NSString *rendering = [GRMustacheTemplate renderObject:data
156 fromString:templateString
157 error:NULL];
158 ```
cc892a6 @groue Runtime Guide clean up
authored
159
998690d @groue Documentation
authored
160 Each item in the collection gets, each on its turn, available for the key lookup: that is how the `{{ name }}` tag renders each of my friend's name. Items that conform to the `GRMustacheRendering` protocol can provide their own rendering of their iteration step (see the [Rendering Objects Guide](rendering_objects.md)).
cc892a6 @groue Runtime Guide clean up
authored
161
e1ce058 @groue Simplify the Runtime Guide
authored
162 Inverted sections render if and only if the collection is empty:
163
164 ```objc
165 id data = @{ @"friends": @[] }; // empty array
166
a856baf @groue Explicitely states support for implicit iterator
authored
167 NSString *templateString = @"{{^ friends }}"
e1ce058 @groue Simplify the Runtime Guide
authored
168 @"I have no friend, sob."
169 @"{{/ friends }}";
170
4f170ea @groue Typos
authored
171 // I have no friend, sob.
e1ce058 @groue Simplify the Runtime Guide
authored
172 NSString *rendering = [GRMustacheTemplate renderObject:data
173 fromString:templateString
174 error:NULL];
175 ```
cc892a6 @groue Runtime Guide clean up
authored
176
a856baf @groue Explicitely states support for implicit iterator
authored
177 #### Rendering a collection of strings
178
179 You may render a collection of strings with the dot expression `.`, aka "implicit iterator":
180
181 ```objc
182 id data = @{ @"items": @[@"Ham", @"Jam"] };
183
184 NSString *templateString = @"{{# items }}"
185 @"- {{ . }}"
186 @"{{/ items }}";
187
188 // - Ham
189 // - Jam
190 NSString *rendering = [GRMustacheTemplate renderObject:data
191 fromString:templateString
192 error:NULL];
193 ```
194
195
e1ce058 @groue Simplify the Runtime Guide
authored
196 #### Rendering a section once when a collection contains several items
cc892a6 @groue Runtime Guide clean up
authored
197
e1ce058 @groue Simplify the Runtime Guide
authored
198 Sections render as many times as they contain items.
cc892a6 @groue Runtime Guide clean up
authored
199
7658aa7 @groue Typo
authored
200 However, you may want to render a section *once* if and only if a collection is not empty. For example, when rendering a single `<ul>` HTML element that wraps several `<li>`.
cc892a6 @groue Runtime Guide clean up
authored
201
4f170ea @groue Typos
authored
202 A template that is compatible with [other Mustache implementations](https://github.com/defunkt/mustache/wiki/Other-Mustache-implementations) needs an extra boolean key that states whether the collection is empty or not:
cc892a6 @groue Runtime Guide clean up
authored
203
e1ce058 @groue Simplify the Runtime Guide
authored
204 ```objc
205 NSArray *friends = ...;
206 id data = @{
8874ccb @groue Typo
authored
207 @"hasFriends": @(friends.count > 0),
e1ce058 @groue Simplify the Runtime Guide
authored
208 @"friends": friends };
209
210 NSString *templateString = @"{{# hasFriends }}"
211 @"<ul>"
212 @" {{# friends }}"
213 @" <li>{{ name }}</li>"
214 @" {{/ friends }}";
215 @"</ul>"
216 @"{{/ hasFriends }}";
217
218 // <ul>
219 // <li>Dennis</li>
220 // <li>Eugene</li>
221 // <li>Fiona</li>
222 // </ul>
223 NSString *rendering = [GRMustacheTemplate renderObject:data
224 fromString:templateString
225 error:NULL];
226 ```
cc892a6 @groue Runtime Guide clean up
authored
227
12d1a3d @groue Wording
authored
228 If you do not care about compatibility, you can simply use the `count` property of NSArray, and use the fact that GRMustache considers zero numbers as false:
cc892a6 @groue Runtime Guide clean up
authored
229
e1ce058 @groue Simplify the Runtime Guide
authored
230 ```objc
231 NSArray *friends = ...;
232 id data = @{ @"friends": friends };
233
234 NSString *templateString = @"{{# friends.count }}"
235 @"<ul>"
236 @" {{# friends }}"
237 @" <li>{{ name }}</li>"
238 @" {{/ friends }}";
239 @"</ul>"
240 @"{{/ friends.count }}";
241
242 // <ul>
243 // <li>Dennis</li>
244 // <li>Eugene</li>
245 // <li>Fiona</li>
246 // </ul>
247 NSString *rendering = [GRMustacheTemplate renderObject:data
248 fromString:templateString
249 error:NULL];
250 ```
f26037b @groue More guide rewriting for 6.0.0
authored
251
86dfa82 @groue runtime.md guide focuses on valueForKey:, description, and NSFastEnumera...
authored
252
e1ce058 @groue Simplify the Runtime Guide
authored
253 ### Lambda sections
cc892a6 @groue Runtime Guide clean up
authored
254
3ecaef7 @groue mustache.github.com -> mustache.github.io
authored
255 Mustache defines [lambda sections](http://mustache.github.io/mustache.5.html), that is, sections that execute your own application code, and allow you to extend the core Mustache engine.
cc892a6 @groue Runtime Guide clean up
authored
256
e1ce058 @groue Simplify the Runtime Guide
authored
257 Such sections are fully documented in the [Rendering Objects Guide](rendering_objects.md), but here is a preview:
cc892a6 @groue Runtime Guide clean up
authored
258
e1ce058 @groue Simplify the Runtime Guide
authored
259 ```objc
260 id data = @{
261 @"name1": @"Gustave",
262 @"name2": @"Henriett" };
263
264 NSString *templateString = @"{{#localize}}Hello {{name1}}, do you know {{name2}}?{{/localize}}";
265
266 // Assuming a Spanish locale:
267 // Hola Gustave, sabes Henriett?
268 NSString *rendering = [GRMustacheTemplate renderObject:data
269 fromString:templateString
270 error:NULL];
271 ```
cc892a6 @groue Runtime Guide clean up
authored
272
47e5bc1 @groue Documentation and cleanup obsolete sample code
authored
273 The `localize` key is attached to a rendering object that is built in the [standard library](standard_library.md#localize) shipped with GRMustache.
cc892a6 @groue Runtime Guide clean up
authored
274
275
e1ce058 @groue Simplify the Runtime Guide
authored
276 ### Other sections
cc892a6 @groue Runtime Guide clean up
authored
277
8fde787 @groue Guides WIP
authored
278 When a section renders a value that is not false, not enumerable, not a [rendering object](rendering_objects.md), it renders once, making the value available for the key lookup inside the section:
e1ce058 @groue Simplify the Runtime Guide
authored
279
280 ```objc
281 Person *ignacio = [Person personWithName:@"Ignacio"];
282 id data = @{ @"person": ignacio };
283
284 // Renders "Hello Ignacio!"
285 NSString *templateString = @"{{# person }}Hello {{ name }}!{{/ person }}";
286 NSString *rendering = [GRMustacheTemplate renderObject:data
287 fromString:templateString
288 error:NULL];
cc892a6 @groue Runtime Guide clean up
authored
289 ```
86dfa82 @groue runtime.md guide focuses on valueForKey:, description, and NSFastEnumera...
authored
290
3436a68 @groue Explicitely states support for expressions in section tags
authored
291 ### Expressions in sections
292
293 Just as variable tags, section tags render any well-formed expressions:
294
295 ```objc
296 id data = @{
297 @"person": @{
298 @"friends": @[
299 [Person personWithName:@"José"],
300 [Person personWithName:@"Karl"],
301 [Person personWithName:@"Lubitza"]]
302 }
303 };
304
47e5bc1 @groue Documentation and cleanup obsolete sample code
authored
305 NSString *templateString = @"{{# each(person.friends) }}"
306 @" {{ @indexPlusOne }}: {{ name }}"
3436a68 @groue Explicitely states support for expressions in section tags
authored
307 @"{{/}}";
308
309 // 1: José
d1c09d9 @groue Typo
authored
310 // 2: Karl
3436a68 @groue Explicitely states support for expressions in section tags
authored
311 // 3: Lubitza
312 NSString *rendering = [GRMustacheTemplate renderObject:data
313 fromString:templateString
314 error:NULL];
315 ```
316
47e5bc1 @groue Documentation and cleanup obsolete sample code
authored
317 The `each` filter is part of the [standard library](standard_library.md#each).
3436a68 @groue Explicitely states support for expressions in section tags
authored
318
3d83fb0 @groue GitHub Flavored Markdown
authored
319
e450983 @groue Guides WIP
authored
320 The context stack
e1ce058 @groue Simplify the Runtime Guide
authored
321 -----------------
322
323 We have seen that values rendered by sections are made available for the key lookup inside the section.
324
325 As a matter of fact, objects that were the context of enclosing sections are still available: the latest object has just entered the top of the *context stack*.
326
327 An example should make this clearer. Let's consider the template below:
328
329 {{# title }}
330 {{ length }}
331 {{/ title }}
332
333 {{# title }}
334 {{ title }}
335 {{/ title }}
336
337 In the first section, the `length` key will be fetched from the `title` string which has just entered the context stack: it will be rendered as "6" if the title is "Hamlet".
338
4970396 @groue Wording
authored
339 In the last section, the title string is still the context. However it has no `title` key. Thus GRMustache looks for it in the enclosing context, finds again the title string, and renders it:
e1ce058 @groue Simplify the Runtime Guide
authored
340
341 6
342 Hamlet
343
344 This technique allows, for example, the conditional rendering of a `<h1>` HTML tag if and only if the title is not empty (empty strings are considered false, see "false sections" above):
345
346 {{# title }}
347 <h1>{{ title }}</h1> {{! rendered if there is a title }}
348 {{/ title }}
349
350
13c0ac2 @groue Wording
authored
351 Fine tuning of key lookup
352 -------------------------
353
354 ### Focus on the current context
d31d8cf @groue runtime.md guide focuses on valueForKey:, description, and NSFastEnumera...
authored
355
e1ce058 @groue Simplify the Runtime Guide
authored
356 These three template snippets are quite similar, but not stricly equivalent:
d31d8cf @groue runtime.md guide focuses on valueForKey:, description, and NSFastEnumera...
authored
357
e1ce058 @groue Simplify the Runtime Guide
authored
358 - `...{{# foo }}{{ bar }}{{/ foo }}...`
359 - `...{{# foo }}{{ .bar }}{{/ foo }}...`
360 - `...{{ foo.bar }}...`
f5fb58f @groue wording
authored
361
cc892a6 @groue Runtime Guide clean up
authored
362 The first will look for `bar` anywhere in the context stack, starting with the `foo` object.
363
e1ce058 @groue Simplify the Runtime Guide
authored
364 The two others are identical: they ensure the `bar` key comes from the very `foo` object. If `foo` is not found, the `bar` lookup will fail as well, regardless of `bar` keys defined by enclosing contexts.
cc892a6 @groue Runtime Guide clean up
authored
365
7eee65d @groue Rename "protected context" to "Priority keys"
authored
366 ### Priority keys
cc892a6 @groue Runtime Guide clean up
authored
367
7eee65d @groue Rename "protected context" to "Priority keys"
authored
368 A *priority key* is always evaluated to the same value, regardless of objects that enter the context stack. Check the [Security Guide](security.md#priority-keys).
daa3e3e @groue Runtime Guide links to Tag Delegates and Protected Context Guides
authored
369
13c0ac2 @groue Wording
authored
370 ### Tag delegates
daa3e3e @groue Runtime Guide links to Tag Delegates and Protected Context Guides
authored
371
13c0ac2 @groue Wording
authored
372 Values extracted from the context stack are directly rendered unless you had some *tag delegates* enter the game. They help you render default values for missing keys, for example. See the [Tag Delegates Guide](delegate.md) for a full discussion.
daa3e3e @groue Runtime Guide links to Tag Delegates and Protected Context Guides
authored
373
374
e1ce058 @groue Simplify the Runtime Guide
authored
375 Detailed description of GRMustache handling of `valueForKey:`
376 -------------------------------------------------------------
cc892a6 @groue Runtime Guide clean up
authored
377
7abcfaf @groue Runtime Guide WIP
authored
378 As seen above, GRMustache looks for a key in your data objects with the `objectForKeyedSubscript:` and `valueForKey:` methods. If an object responds to `objectForKeyedSubscript:`, this method is used. For other objects, `valueForKey:` is used, as long as the key is safe (see the [Security Guide](security.md)).
379
380
381 ### NSArray, NSSet, NSOrderedSet
382
383 GRMustache does not use `valueForKey:` for NSArray, NSSet, and NSOrderedSet. Instead, it directly invokes methods of those objects. As a consequence, keys like `count`, `firstObject`, etc. can be used in templates.
cc892a6 @groue Runtime Guide clean up
authored
384
3c71cb8 @groue Restore documentation for [GRMustache preventNSUndefinedKeyExceptionAtta...
authored
385
386 ### NSUndefinedKeyException Handling
cc892a6 @groue Runtime Guide clean up
authored
387
388 NSDictionary never complains when asked for an unknown key. However, the default NSObject implementation of `valueForKey:` raises an `NSUndefinedKeyException`.
389
3c71cb8 @groue Restore documentation for [GRMustache preventNSUndefinedKeyExceptionAtta...
authored
390 *GRMustache catches those exceptions*, so that the key lookup can continue down the context stack.
391
c6feff5 @groue Runtime Guide clarification
authored
392 Some of you may feel uncomfortable with those exceptions. See the paragraph below.
393
3c71cb8 @groue Restore documentation for [GRMustache preventNSUndefinedKeyExceptionAtta...
authored
394
395 ### NSUndefinedKeyException Prevention
396
3f366df @groue v6.9.0
authored
397 Objective-C exceptions have several drawbacks, particularly:
398
399 1. they play badly with autorelease pools, and are reputed to leak memory.
400 2. they usually stop your debugger when you are developping your application.
401
402 The first point is indeed a matter of worry: Apple does not guarantee that exceptions raised by `valueForKey:` do not leak memory. However, I never had any evidence of such a leak from NSObject's implementation.
403
404 Should you still worry, we recommend that you avoid the `valueForKey:` method altogether. Instead, implement the [keyed subscripting](http://clang.llvm.org/docs/ObjectiveCLiterals.html#dictionary-style-subscripting) `objectForKeyedSubscript:` method on objects that you provide to GRMustache.
405
406 The second point is valid also: NSUndefinedKeyException raised by template rendering may become a real annoyance when you are debugging your project, because it's likely you've told your debugger to stop on every Objective-C exceptions.
3c71cb8 @groue Restore documentation for [GRMustache preventNSUndefinedKeyExceptionAtta...
authored
407
3f366df @groue v6.9.0
authored
408 You can avoid them as well: make sure you invoke once, early in your application, the following method:
3c71cb8 @groue Restore documentation for [GRMustache preventNSUndefinedKeyExceptionAtta...
authored
409
410 ```objc
411 [GRMustache preventNSUndefinedKeyExceptionAttack];
412 ```
413
414 Depending on the number of NSUndefinedKeyException that get prevented, you will experience a slight performance hit, or a performance improvement.
415
2612858 @groue Wording
authored
416 Since the main use case for this method is to avoid Xcode breaks on rendering exceptions, the best practice is to conditionally invoke this method, using the [NS_BLOCK_ASSERTIONS](http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Functions/Reference/reference.html) that helps identifying the Debug configuration of your targets:
3c71cb8 @groue Restore documentation for [GRMustache preventNSUndefinedKeyExceptionAtta...
authored
417
418 ```objc
419 #if !defined(NS_BLOCK_ASSERTIONS)
2612858 @groue Wording
authored
420 // Debug configuration: keep GRMustache quiet
3c71cb8 @groue Restore documentation for [GRMustache preventNSUndefinedKeyExceptionAtta...
authored
421 [GRMustache preventNSUndefinedKeyExceptionAttack];
422 #endif
423 ```
424
cc892a6 @groue Runtime Guide clean up
authored
425
7704634 @groue Runtime Guide WIP
authored
426 Compatibility with other Mustache implementations
427 -------------------------------------------------
428
429 The [Mustache specification](https://github.com/mustache/spec) does not enforce the list of *false* values, the values that trigger or prevent the rendering of sections and inverted sections:
430
431 There is *no guarantee* that `{{# value }}...{{/ value }}` and `{{^ value }}...{{/ value }}` will render the same, provided with the exact same input, in all Mustache implementations.
432
433 That's unfortunate. Anyway, for the record, here is a reminder of all false values in GRMustache:
434
435 - `nil` and missing keys
436 - `[NSNull null]`
437 - `NSNumber` instances whose `boolValue` method returns `NO`
438 - empty strings `@""`
439 - empty enumerables.
440
48b63af @groue ViewModel guide
authored
441 [up](../../../../GRMustache#documentation), [next](view_model.md)
Something went wrong with that request. Please try again.