Skip to content

Commit

Permalink
v5.0.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@groue
groue committed Sep 12, 2012
1 parent 1e845ee commit 7924382
Show file tree
Hide file tree
Showing 21 changed files with 130 additions and 760 deletions.
10 changes: 3 additions & 7 deletions Guides/delegate.md
View file
Expand Up @@ -42,17 +42,16 @@ The following methods are called before, and after the rendering of substitution
- (void)template:(GRMustacheTemplate *)template didInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation;
```

Maybe verbose. But quite on target: as a matter of fact, in order to render a tag, GRMustache has to *invoke* the tag name on the rendered object, the one you've given to the template, and then to *interpret* it.
Maybe verbose. But quite on target: as a matter of fact, in order to render a tag, GRMustache has to *invoke* the tag expression on the rendered object, the one you've given to the template, and then to *interpret* it.

You can read the following properties of the *invocation* parameter:

- `id returnValue`: the return value of the invocation.
- `NSString *key`: the key that did provide this value.
- `NSString *description`: a string that helps you locate the corresponding Mustache tag.

Note that those methods do not allow you to build a complete "stack trace" of GRMustache rendering. They are not called for each accessed key. They are called for each tag rendering, which is quite different.

For instance, a tag like `{{person.name}}` is rendered once. Thus `template:willInterpretReturnValueOfInvocation:as:` will be called once. If the person has been found, the invocation's key will be `@"name"`, and the return value the name of the person. If the person could not be found, the key will be `@"person"`, and the return value `nil`.
For instance, a tag like `{{person.name}}` is rendered once. Thus `template:willInterpretReturnValueOfInvocation:as:` will be called once. If the person has been found, the return value will be the name of the person. If the person could not be found, the return value will be `nil`.

Also: if a section tag `{{#name}}...{{/name}}` is provided with an NSArray, its content is rendered several times. However `template:willInterpretReturnValueOfInvocation:as:` will be called once, with the array stored in the return value of the invocation.

Expand All @@ -62,16 +61,13 @@ The *interpretation* parameter tells you how the return value of the invocation
typedef enum {
GRMustacheInterpretationSection,
GRMustacheInterpretationVariable,
GRMustacheInterpretationFilterArgument,
} GRMustacheInterpretation;
```

`GRMustacheInterpretationVariable` tells you that the return value is rendered by a Mustache variable tag such as `{{name}}`. Basically, GRMustache simply invokes its `description` method. See [Guides/runtime.md](runtime.md) for more information.

`GRMustacheInterpretationSection` tells you that the return value is used by a Mustache section such as `{{#name}}...{{/name}}`. Mustache sections are versatile: there are boolean sections, loop sections, and lambda sections, and this depends solely on the rendered value, that is to say: the return value of the invocation. Again, see [Guides/runtime.md](runtime.md) for more information.

`GRMustacheInterpretationFilterArgument` tells you that the return value is about to be processed by a filter such as `{{ f(name) }}`. See [Guides/filters.md](filters.md) for more information.


### A practical use: debugging templates

Expand Down Expand Up @@ -120,7 +116,7 @@ The `returnValue` property of the *invocation* parameter can be written. If you

Usually, [filters](filters.md) and [helpers](helpers.md) should do the trick when you want to alter a template's rendering.

However, they both require to be explicited invoked from the template: `{{#helper}}...{{/helper}}`, and `{{ filter(...) }}`.
However, they both require to be explicitly invoked from the template: `{{#helper}}...{{/helper}}`, and `{{ filter(...) }}`.

GRMustacheTemplateDelegate will help you when you can not, or do not want, to embed your extra behaviors right into the template.

Expand Down
2 changes: 1 addition & 1 deletion Guides/filters.md
View file
Expand Up @@ -84,7 +84,7 @@ You can for instance declare a filter that outputs numbers as percentages:
id percentFilters = [[PercentFilter alloc] init];
```

Starting iOS4 and MacOS 10.6, the Objective-C language provides us with blocks. This can relieve the burden of declaring a full class for each filter:
The protocol comes with a `GRMustacheFilter` class, which provides a convenient method for building a filter without implementing a full class that conforms to the protocol:

```objc
id percentFilter = [GRMustacheFilter filterWithBlock:^id(id object) {
Expand Down
4 changes: 2 additions & 2 deletions README.md
View file
Expand Up @@ -3,7 +3,7 @@ GRMustache

GRMustache is a production-ready implementation of [Mustache](http://mustache.github.com/) templates for MacOS Cocoa and iOS.

**September 6th, 2012: GRMustache 4.3.4 is out.** [Release notes](GRMustache/blob/master/RELEASE_NOTES.md)
**September 12th, 2012: GRMustache 5.0.0 is out.** [Release notes](GRMustache/blob/master/RELEASE_NOTES.md)

Breaking news on Twitter: http://twitter.com/GRMustache

Expand All @@ -19,7 +19,7 @@ How To

Alternatively, you may use [CocoaPods](https://github.com/CocoaPods/CocoaPods): append `pod 'GRMustache', '~> 4.3'` to your Podfile.

GRMustache targets MacOS down to 10.6 Snow Leopard, iOS down to version 3, and only depends on the Foundation framework.
GRMustache targets MacOS down to 10.6 Snow Leopard, iOS down to version 4, and only depends on the Foundation framework.

### 2. Start rendering templates

Expand Down
43 changes: 41 additions & 2 deletions RELEASE_NOTES.md
View file
Expand Up @@ -4,6 +4,45 @@ GRMustache Release Notes
You can compare the performances of GRMustache versions at https://github.com/groue/GRMustacheBenchmark.


## v5.0.0

**[Performance improvements](https://github.com/groue/GRMustacheBenchmark), and fix for flaws in the GRMustacheDelegate API.**

Besides the removal of already deprecated methods, the changes introduced in this version are very unlikely to introduce incompatibilities in your code:

- Dropped support for iOS3.
- Before v5.0.0, [template delegates](Guides/delegate.md) could know that the value `Arthur` was provided by the key `name` when the tag `{{name}}` is rendered. Delegates are now only provided with the value.
- Before v5.0.0, a tag containing a filter expression like `{{uppercase(name)}}` would have a template delegate invoked with the raw `Arthur` value, not the filter result: `ARTHUR`. In v5.0.0, delegate callbacks are given always given the value GRMustache is about to render.

Removed APIs:

```objc
@interface GRMustacheInvocation : NSObject
// Removed without deprecation warning
@property (nonatomic, readonly) NSString *key;
@end

@interface GRMustacheSection: NSObject
// Deprecated in v4.3.0
@property (nonatomic, retain, readonly) id renderingContext;
@end

@interface GRMustacheTemplate: NSObject
// Deprecated in v4.3.0
- (NSString *)renderObjects:(id)object, ...;
@end

// Removed without deprecation warning
GRMustacheInterpretationFilterArgument // was part of the GRMustacheInterpretation enum.

@protocol GRMustacheTemplateDelegate<NSObject>
// Deprecated in v4.1.0
- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation;
- (void)template:(GRMustacheTemplate *)template didRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation;
@end
```
## v4.3.4
Restored compatibility with iOS3 and OSX6 (thanks [@Bertrand](https://github.com/Bertrand)).
Expand Down Expand Up @@ -414,11 +453,11 @@ Upgrade GRMustache, and get deprecation warnings when you use deprecated APIs. Y

## v1.10.2

**Drastic rendering performance improvements**
**[Performance improvements](https://github.com/groue/GRMustacheBenchmark)**

## v1.10.1

**Rendering performance improvements**
**[Performance improvements](https://github.com/groue/GRMustacheBenchmark)**

## v1.10

Expand Down
72 changes: 0 additions & 72 deletions Reference/html/Classes/GRMustacheInvocation.html
View file
Expand Up @@ -40,8 +40,6 @@ <h1 class="hideInXcode">GRMustacheInvocation Class Reference</h1>

<option value="properties">Properties</option>

<option value="//api/name/key">&nbsp;&nbsp;&nbsp;&nbsp;key</option>

<option value="//api/name/returnValue">&nbsp;&nbsp;&nbsp;&nbsp;returnValue</option>


Expand Down Expand Up @@ -72,8 +70,6 @@ <h1 class="hideInXcode">GRMustacheInvocation Class Reference</h1>

<li role="treeitem" class="children"><span class="disclosure"></span><span class="sectionName"><a href="#properties">Properties</a></span><ul>

<li><span class="nodisclosure"></span><span class="sectionName"><a href="#//api/name/key">key</a></span></li>

<li><span class="nodisclosure"></span><span class="sectionName"><a href="#//api/name/returnValue">returnValue</a></span></li>

</ul></li>
Expand Down Expand Up @@ -140,13 +136,6 @@ <h2 class="subtitle subtitle-tasks">Tasks</h2>

<ul class="task-list">
<li>
<span class="tooltip">
<code><a href="#//api/name/key">&nbsp;&nbsp;key</a></code>
<span class="tooltip"><p>The key that did provide the return value of the invocation.</p></span>
</span>
<span class="task-item-suffix">property</span>

</li><li>
<span class="tooltip">
<code><a href="#//api/name/returnValue">&nbsp;&nbsp;returnValue</a></code>
<span class="tooltip"><p>The return value of the invocation.</p></span>
Expand All @@ -166,67 +155,6 @@ <h2 class="subtitle subtitle-tasks">Tasks</h2>
<a title="Properties" name="properties"></a>
<h2 class="subtitle subtitle-methods">Properties</h2>

<div class="section-method">
<a name="//api/name/key" title="key"></a>
<h3 class="subsubtitle method-title">key</h3>



<div class="method-subsection brief-description">
<p>The key that did provide the return value of the invocation.</p>
</div>



<div class="method-subsection method-declaration"><code>@property (nonatomic, readonly) NSString *key</code></div>







<div class="method-subsection availability">
<h4 class="method-subtitle parameter-title">Availability</h4>
<p>v1.12</p>
</div>



<div class="method-subsection discussion-section">
<h4 class="method-subtitle">Discussion</h4>
<p>For instance, the invocation that you would get for a <code>{{name}}</code> tag would
have @&ldquo;name&rdquo; in its <code>key</code> property, and the name in the <a href="#//api/name/returnValue"><code>returnValue</code></a>
property.</p>

<p>For tags with compound keys, such as <code>{{person.name}}</code>, the key will be
@&ldquo;name&rdquo; if the person could be found in the context stack. It would be
@&ldquo;person&rdquo; otherwise.</p>
</div>





<div class="method-subsection see-also-section">
<h4 class="method-subtitle">See Also</h4>
<ul>

<li><code><p><a href="#//api/name/returnValue">@property returnValue</a></p></code></li>

</ul>
</div>



<div class="method-subsection declared-in-section">
<h4 class="method-subtitle">Declared In</h4>
<code class="declared-in-ref">GRMustacheInvocation.h</code><br />
</div>


</div>

<div class="section-method">
<a name="//api/name/returnValue" title="returnValue"></a>
<h3 class="subsubtitle method-title">returnValue</h3>
Expand Down
61 changes: 1 addition & 60 deletions Reference/html/Classes/GRMustacheSection.html
View file
Expand Up @@ -42,8 +42,6 @@ <h1 class="hideInXcode">GRMustacheSection Class Reference</h1>

<option value="//api/name/innerTemplateString">&nbsp;&nbsp;&nbsp;&nbsp;innerTemplateString</option>

<option value="//api/name/renderingContext">&nbsp;&nbsp;&nbsp;&nbsp;renderingContext</option>




Expand Down Expand Up @@ -89,8 +87,6 @@ <h1 class="hideInXcode">GRMustacheSection Class Reference</h1>

<li><span class="nodisclosure"></span><span class="sectionName"><a href="#//api/name/innerTemplateString">innerTemplateString</a></span></li>

<li><span class="nodisclosure"></span><span class="sectionName"><a href="#//api/name/renderingContext">renderingContext</a></span></li>

</ul></li>


Expand Down Expand Up @@ -159,21 +155,6 @@ <h2 class="subtitle subtitle-overview">Overview</h2>
<h2 class="subtitle subtitle-tasks">Tasks</h2>


<a title="Accessing the current rendering context" name="task_Accessing the current rendering context"></a>
<h3 class="subsubtitle task-title">Accessing the current rendering context</h3>

<ul class="task-list">
<li>
<span class="tooltip">
<code><a href="#//api/name/renderingContext">&nbsp;&nbsp;renderingContext</a></code>
<span class="tooltip"><p>The current rendering context.</p></span>
</span>
<span class="task-item-suffix">property</span>

</li>
</ul>


<a title="Accessing the literal inner content" name="task_Accessing the literal inner content"></a>
<h3 class="subsubtitle task-title">Accessing the literal inner content</h3>

Expand Down Expand Up @@ -271,47 +252,7 @@ <h4 class="method-subtitle">Declared In</h4>

</div>

<div class="section-method">
<a name="//api/name/renderingContext" title="renderingContext"></a>
<h3 class="subsubtitle method-title">renderingContext</h3>



<div class="method-subsection brief-description">
<p>The current rendering context.</p>
</div>



<div class="method-subsection method-declaration"><code>@property (nonatomic, retain, readonly) id renderingContext</code></div>







<div class="method-subsection availability">
<h4 class="method-subtitle parameter-title">Availability</h4>
<p>v2.0
@deprecated v4.3</p>
</div>









<div class="method-subsection declared-in-section">
<h4 class="method-subtitle">Declared In</h4>
<code class="declared-in-ref">GRMustacheSection.h</code><br />
</div>


</div>


</div>

Expand Down

0 comments on commit 7924382

Please sign in to comment.