Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

v4.1.0

  • Loading branch information...
commit 459f57b3bca90af54bec7c969c61d3dd8dbabf60 1 parent 59e778e
Gwendal Roué authored
34 Guides/delegate.md
Source Rendered
@@ -23,13 +23,13 @@ The following methods are called before, and after the whole template rendering:
23 23 The following methods are called before, and after the rendering of substitution and sections tags (`{{name}}` and `{{#name}}...{{/name}}`):
24 24
25 25 ```objc
26   -- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation;
27   -- (void)template:(GRMustacheTemplate *)template didRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation;
  26 +- (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation;
  27 +- (void)template:(GRMustacheTemplate *)template didInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation;
28 28 ```
29 29
30   -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.
  30 +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.
31 31
32   -You can read the following properties of the *invocation* argument:
  32 +You can read the following properties of the *invocation* parameter:
33 33
34 34 - `id returnValue`: the return value of the invocation.
35 35 - `NSString *key`: the key that did provide this value.
@@ -37,16 +37,32 @@ You can read the following properties of the *invocation* argument:
37 37
38 38 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.
39 39
40   -For instance, a tag like `{{person.name}}` is rendered once. Thus `template:willRenderReturnValueOfInvocation:` 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`.
  40 +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`.
  41 +
  42 +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.
  43 +
  44 +The *interpretation* parameter tells you how the return value of the invocation is used:
  45 +
  46 +```objc
  47 +typedef enum {
  48 + GRMustacheInterpretationSection,
  49 + GRMustacheInterpretationVariable,
  50 +} GRMustacheInterpretation;
  51 +```
  52 +
  53 +`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.
  54 +
  55 +`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.
  56 +
  57 +You will find an actual use of this *interpretation* parameter in the [number formatting sample code](sample_code/number_formatting.md).
41 58
42   -Also: if a section tag `{{#name}}...{{/name}}` is provided with an NSArray, it will be rendered several times. However `template:willRenderReturnValueOfInvocation:` will be called once, with the array stored in the return value of the invocation.
43 59
44 60 ### A practical use: debugging templates
45 61
46 62 You may, for instance, locate keys that could not find any data:
47 63
48 64 ```objc
49   -- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation
  65 +- (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
50 66 {
51 67 // When returnValue is nil, GRMustache could not find any value to render.
52 68 if (invocation.returnValue == nil) {
@@ -66,7 +82,7 @@ GRMustache missing key: `items` for <GRMustacheInvocation: {{#items}} at line 23
66 82 Alter the template rendering
67 83 ----------------------------
68 84
69   -The `returnValue` property of the *invocation* argument can be written. If you set it in `template:willRenderReturnValueOfInvocation:`, GRMustache will render the value you have provided.
  85 +The `returnValue` property of the *invocation* parameter can be written. If you set it in `template:willInterpretReturnValueOfInvocation:as:`, GRMustache will render the value you have provided.
70 86
71 87 **Warning: If your goal is to design templates that remain compatible with [other Mustache implementations](https://github.com/defunkt/mustache/wiki/Other-Mustache-implementations), use this feature with great care.**
72 88
@@ -74,7 +90,7 @@ The `returnValue` property of the *invocation* argument can be written. If you s
74 90 ### A practical use: providing default values for missing keys
75 91
76 92 ```objc
77   -- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation
  93 +- (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
78 94 {
79 95 // When returnValue is nil, GRMustache could not find any value to render.
80 96 if (invocation.returnValue == nil) {
2  Guides/sample_code/indexes.md
Source Rendered
@@ -95,7 +95,7 @@ Now let's replace array elements with proxies before they are rendered:
95 95 /**
96 96 This method is called when the template is about to render a tag.
97 97 */
98   -- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation
  98 +- (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
99 99 {
100 100 /**
101 101 The invocation object tells us which object is about to be rendered.
41 Guides/sample_code/number_formatting.md
Source Rendered
@@ -171,7 +171,7 @@ And then implement the delegate methods:
171 171
172 172 Each time we'll enter a section that is attached to a NSNumberFormatter,
173 173 we'll enqueue this NSNumberFormatter in the stack. This is done in
174   - [template:willRenderReturnValueOfInvocation:]
  174 + [template:willInterpretReturnValueOfInvocation:as:]
175 175 */
176 176 self.templateNumberFormatterStack = [NSMutableArray array];
177 177 }
@@ -179,7 +179,7 @@ And then implement the delegate methods:
179 179 /**
180 180 This method is called when the template is about to render a tag.
181 181 */
182   -- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation
  182 +- (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
183 183 {
184 184 /**
185 185 The invocation object tells us which object is about to be rendered.
@@ -188,17 +188,42 @@ And then implement the delegate methods:
188 188 {
189 189 /**
190 190 If it is a NSNumberFormatter, enqueue it in
191   - templateNumberFormatterStack.
  191 + templateNumberFormatterStack, and return.
192 192 */
193 193 [self.templateNumberFormatterStack addObject:invocation.returnValue];
  194 + return;
194 195 }
195   - else if (self.templateNumberFormatterStack.count > 0 && [invocation.returnValue isKindOfClass:[NSNumber class]])
  196 +
  197 + if (interpretation == GRMustacheInterpretationSection)
  198 + {
  199 + /**
  200 + We actually only format numbers for variable tags such as `{{name}}`.
  201 + We must carefully avoid messing with sections: they as well can be
  202 + provided with numbers, that they interpret as booleans. We surely
  203 + do not want to convert booleans to strings...
  204 +
  205 + So let's ignore sections, and return.
  206 + */
  207 + return;
  208 + }
  209 +
  210 + if (self.templateNumberFormatterStack.count == 0)
  211 + {
  212 + /**
  213 + If our number formatter stack is empty, we can not format anything:
  214 + let's return.
  215 + */
  216 + return;
  217 + }
  218 +
  219 + if ([invocation.returnValue isKindOfClass:[NSNumber class]])
196 220 {
197 221 /**
198   - If it is a NSNumber, and if our templateNumberFormatterStack is not
199   - empty, use the top NSNumberFormatter to format the number.
  222 + There we are: invocation's return value is a NSNumber, and our
  223 + templateNumberFormatterStack is not empty.
200 224
201   - Set the invocation's returnValue: this is the object that will be
  225 + Let's use the top NSNumberFormatter to format this number, and set
  226 + the invocation's returnValue: this is the object that will be
202 227 rendered.
203 228 */
204 229 NSNumberFormatter *numberFormatter = self.templateNumberFormatterStack.lastObject;
@@ -210,7 +235,7 @@ And then implement the delegate methods:
210 235 /**
211 236 This method is called right after the template has rendered a tag.
212 237 */
213   -- (void)template:(GRMustacheTemplate *)template didRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation
  238 +- (void)template:(GRMustacheTemplate *)template didInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
214 239 {
215 240 /**
216 241 Make sure we dequeue NSNumberFormatters when we leave their scope.
39 RELEASE_NOTES.md
Source Rendered
@@ -3,6 +3,45 @@ GRMustache Release Notes
3 3
4 4 You can compare the performances of GRMustache versions at https://github.com/groue/GRMustacheBenchmark.
5 5
  6 +## v4.1.0
  7 +
  8 +### GRMustacheDelegate protocol
  9 +
  10 +A template's delegate is now able to know how a value will be interpreted by GRMustache.
  11 +
  12 +New APIs:
  13 +
  14 +```objc
  15 +typedef enum {
  16 + GRMustacheInterpretationSection,
  17 + GRMustacheInterpretationVariable,
  18 +} GRMustacheInterpretation;
  19 +
  20 +@protocol GRMustacheTemplateDelegate<NSObject>
  21 +- (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation;
  22 +- (void)template:(GRMustacheTemplate *)template didInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation;
  23 +@end
  24 +```
  25 +
  26 +Deprecated APIs:
  27 +
  28 +```objc
  29 +@protocol GRMustacheTemplateDelegate<NSObject>
  30 +- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation;
  31 +- (void)template:(GRMustacheTemplate *)template didRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation;
  32 +@end
  33 +```
  34 +
  35 +The new APIs are documented in [Guides/delegate.md](Guides/delegate.md).
  36 +
  37 +### GRMustacheTemplateRepositoryDataSource protocol
  38 +
  39 +The return type of `-[GRMustacheTemplateRepositoryDataSource templateRepository:templateIDForName:relativeToTemplateID:]` as changed from `id` to `id<NSCopying>`.
  40 +
  41 +### Errors
  42 +
  43 +GRMustache used to output badly formatted errors. They are now easier to read.
  44 +
6 45 ## v4.0.0
7 46
8 47 **Performance improvements**
58 include/GRMustacheAvailabilityMacros.h
@@ -29,6 +29,7 @@
29 29 * Set up standard GRMustache versions
30 30 */
31 31 #define GRMUSTACHE_VERSION_4_0 4000
  32 +#define GRMUSTACHE_VERSION_4_1 4010
32 33
33 34
34 35
@@ -36,10 +37,10 @@
36 37
37 38
38 39 /*
39   - * If max GRMustacheVersion not specified, assume 4.0
  40 + * If max GRMustacheVersion not specified, assume 4.1
40 41 */
41 42 #ifndef GRMUSTACHE_VERSION_MAX_ALLOWED
42   -#define GRMUSTACHE_VERSION_MAX_ALLOWED GRMUSTACHE_VERSION_4_0
  43 +#define GRMUSTACHE_VERSION_MAX_ALLOWED GRMUSTACHE_VERSION_4_1
43 44 #endif
44 45
45 46 /*
@@ -91,3 +92,56 @@
91 92
92 93
93 94
  95 +/*
  96 + * AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER
  97 + *
  98 + * Used on declarations introduced in GRMustache 4.1
  99 + */
  100 +#if GRMUSTACHE_VERSION_MAX_ALLOWED < GRMUSTACHE_VERSION_4_1
  101 +#define AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER UNAVAILABLE_ATTRIBUTE
  102 +#elif GRMUSTACHE_VERSION_MIN_REQUIRED < GRMUSTACHE_VERSION_4_1
  103 +#define AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER WEAK_IMPORT_ATTRIBUTE
  104 +#else
  105 +#define AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER
  106 +#endif
  107 +
  108 +/*
  109 + * AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER_BUT_DEPRECATED
  110 + *
  111 + * Used on declarations introduced in GRMustache 4.1,
  112 + * and deprecated in GRMustache 4.1
  113 + */
  114 +#if GRMUSTACHE_VERSION_MIN_REQUIRED >= GRMUSTACHE_VERSION_4_1
  115 +#define AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER_BUT_DEPRECATED DEPRECATED_ATTRIBUTE
  116 +#else
  117 +#define AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER_BUT_DEPRECATED AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER
  118 +#endif
  119 +
  120 +/*
  121 + * AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER_BUT_DEPRECATED_IN_GRMUSTACHE_VERSION_4_1
  122 + *
  123 + * Used on declarations introduced in GRMustache 4.0,
  124 + * but later deprecated in GRMustache 4.1
  125 + */
  126 +#if GRMUSTACHE_VERSION_MIN_REQUIRED >= GRMUSTACHE_VERSION_4_1
  127 +#define AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER_BUT_DEPRECATED_IN_GRMUSTACHE_VERSION_4_1 DEPRECATED_ATTRIBUTE
  128 +#else
  129 +#define AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER_BUT_DEPRECATED_IN_GRMUSTACHE_VERSION_4_1 AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER
  130 +#endif
  131 +
  132 +/*
  133 + * DEPRECATED_IN_GRMUSTACHE_VERSION_4_1_AND_LATER
  134 + *
  135 + * Used on types deprecated in GRMustache 4.1
  136 + */
  137 +#if GRMUSTACHE_VERSION_MIN_REQUIRED >= GRMUSTACHE_VERSION_4_1
  138 +#define DEPRECATED_IN_GRMUSTACHE_VERSION_4_1_AND_LATER DEPRECATED_ATTRIBUTE
  139 +#else
  140 +#define DEPRECATED_IN_GRMUSTACHE_VERSION_4_1_AND_LATER
  141 +#endif
  142 +
  143 +
  144 +
  145 +
  146 +
  147 +
11 include/GRMustacheSection.h
@@ -26,12 +26,15 @@
26 26 @class GRMustacheInvocation;
27 27 @class GRMustacheTemplate;
28 28
  29 +/**
  30 + A GRMustacheSection represents a Mustache section such as `{{#name}}...{{/name}}`.
  31 + */
29 32 @interface GRMustacheSection: NSObject {
30 33 @private
31 34 GRMustacheInvocation *_invocation;
32 35 GRMustacheTemplate *_rootTemplate;
33 36 NSString *_templateString;
34   - NSRange _range;
  37 + NSRange _innerRange;
35 38 BOOL _inverted;
36 39 NSArray *_elems;
37 40 id _renderingContext;
@@ -44,8 +47,6 @@
44 47
45 48 /**
46 49 Returns the current rendering context.
47   -
48   - @since v2.0
49 50 */
50 51 @property (nonatomic, readonly) id renderingContext AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
51 52
@@ -58,8 +59,6 @@
58 59
59 60 /**
60 61 Returns the literal inner content of the section, with unprocessed mustache `{{tags}}`.
61   -
62   - @since v2.0
63 62 */
64 63 @property (nonatomic, readonly) NSString *innerTemplateString AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
65 64
@@ -72,8 +71,6 @@
72 71 Renders the inner content of the receiver with the current context
73 72
74 73 @return A string containing the rendered inner content.
75   -
76   - @since v2.0
77 74 */
78 75 - (NSString *)render AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
79 76
3  include/GRMustacheTemplate.h
@@ -46,12 +46,9 @@
46 46 /**
47 47 Parses a template string, and returns a compiled template.
48 48
49   - The behavior of the returned template is determined by [GRMustache defaultTemplateOptions].
50   -
51 49 @return A GRMustacheTemplate instance
52 50 @param templateString The template string
53 51 @param outError If there is an error loading or parsing template and partials, upon return contains an NSError object that describes the problem.
54   - @see [GRMustache defaultTemplateOptions]
55 52 @since v1.11
56 53 */
57 54 + (id)templateFromString:(NSString *)templateString error:(NSError **)outError AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
11 include/GRMustacheTemplateDelegate.h
@@ -26,10 +26,17 @@
26 26 @class GRMustacheTemplate;
27 27 @class GRMustacheInvocation;
28 28
  29 +typedef enum {
  30 + GRMustacheInterpretationSection,
  31 + GRMustacheInterpretationVariable,
  32 +} GRMustacheInterpretation;
  33 +
29 34 @protocol GRMustacheTemplateDelegate<NSObject>
30 35 @optional
31 36 - (void)templateWillRender:(GRMustacheTemplate *)template AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
32 37 - (void)templateDidRender:(GRMustacheTemplate *)template AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
33   -- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
34   -- (void)template:(GRMustacheTemplate *)template didRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
  38 +- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER_BUT_DEPRECATED_IN_GRMUSTACHE_VERSION_4_1;
  39 +- (void)template:(GRMustacheTemplate *)template didRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER_BUT_DEPRECATED_IN_GRMUSTACHE_VERSION_4_1;
  40 +- (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER;
  41 +- (void)template:(GRMustacheTemplate *)template didInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER;
35 42 @end
408 include/GRMustacheTemplateRepository.h
@@ -27,39 +27,443 @@
27 27 @class GRMustacheTemplate;
28 28 @class GRMustacheTemplateRepository;
29 29
  30 +/**
  31 + The protocol for a GRMustacheTemplateRepository's dataSource.
  32 +
  33 + The dataSource's responsability is to provide Mustache template strings for template and partial names.
  34 +
  35 + @see GRMustacheTemplateRepository
  36 + */
30 37 @protocol GRMustacheTemplateRepositoryDataSource <NSObject>
31 38 @required
32   -- (id)templateRepository:(GRMustacheTemplateRepository *)templateRepository templateIDForName:(NSString *)name relativeToTemplateID:(id)templateID AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
  39 +
  40 +/**
  41 + Returns a template ID, that is to say an object that uniquely identifies a template or a template partial.
  42 +
  43 + The class of this ID is opaque: your implementation of a GRMustacheTemplateRepositoryDataSource
  44 + would define, for itself, what kind of object would identity a template or a partial.
  45 +
  46 + For instance, a file-based data source may use NSString objects containing paths to the templates.
  47 +
  48 + You should try to choose "human-readable" template IDs. That is because template IDs are embedded in
  49 + the description of errors that may happen during a template processing, in order to help the library
  50 + user locate, and fix, the faulting template.
  51 +
  52 + Whenever relevant, template and partial hierarchies are supported via the _baseTemplateID_ parameter: it contains
  53 + the template ID of the enclosing template, or nil when the data source is asked for a template ID for a partial
  54 + that is referred from a raw template string (see [GRMustacheTemplateRepository templateFromString:error:]).
  55 +
  56 + Not all data sources have to implement hierarchies: they can simply ignore this parameter.
  57 +
  58 + The returned value can be nil: the library user would then eventually get an NSError of domain
  59 + GRMustacheErrorDomain and code GRMustacheErrorCodeTemplateNotFound.
  60 +
  61 + @return a template ID
  62 + @param templateRepository The GRMustacheTemplateRepository asking for a template ID.
  63 + @param name The name of the template or template partial.
  64 + @param baseTemplateID The template ID of the enclosing template, or nil.
  65 + */
  66 +- (id<NSCopying>)templateRepository:(GRMustacheTemplateRepository *)templateRepository templateIDForName:(NSString *)name relativeToTemplateID:(id)baseTemplateID AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
  67 +
  68 +/**
  69 + Provided with a template ID that comes from templateRepository:templateIDForName:relativeToTemplateID:,
  70 + returns a Mustache template string.
  71 +
  72 + For instance, a file-based data source may interpret the template ID as a NSString object
  73 + containing paths to the template, and return the file content.
  74 +
  75 + A few words about the way your implementation of this method must handle errors:
  76 +
  77 + As usually, whenever this method returns nil, the _outError_ parameter should point to
  78 + a valid NSError. This NSError would eventually reach the library user.
  79 +
  80 + However, should you "forget" to set the _outError_ parameter, GRMustache would generate for you
  81 + an NSError of domain GRMustacheErrorDomain and code GRMustacheErrorCodeTemplateNotFound.
  82 +
  83 + @return a Mustache template string
  84 + @param templateRepository The GRMustacheTemplateRepository asking for a Mustache template string.
  85 + @param templateID The template ID of the template
  86 + @param outError If there is an error returning a template string, upon return contains nil, or an NSError object that describes the problem.
  87 + */
33 88 - (NSString *)templateRepository:(GRMustacheTemplateRepository *)templateRepository templateStringForTemplateID:(id)templateID error:(NSError **)outError AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
34 89 @end
35 90
  91 +
  92 +/**
  93 + Given a data source that provides Mustache template strings, a GRMustacheTemplateRepository's responsability
  94 + is to provide GRMustacheTemplate instances.
  95 +
  96 + You may provide your own template string data source. However common cases such as loading templates
  97 + from URLs, files, bundle resources, and dictionaries, are already implemented.
  98 +
  99 + @see GRMustacheTemplate
  100 + @see GRMustacheTemplateRepositoryDataSource
  101 + */
36 102 @interface GRMustacheTemplateRepository : NSObject {
37 103 @private
38 104 id<GRMustacheTemplateRepositoryDataSource> _dataSource;
39 105 NSMutableDictionary *_templateForTemplateID;
40 106 id _currentlyParsedTemplateID;
41 107 }
  108 +
  109 +/**
  110 + The repository's data source.
  111 + */
42 112 @property (nonatomic, assign) id<GRMustacheTemplateRepositoryDataSource> dataSource AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
43 113
44 114 #if !TARGET_OS_IPHONE || __IPHONE_OS_VERSION_MAX_ALLOWED >= 40000
  115 +
  116 +/**
  117 + Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of extension .mustache,
  118 + encoded in UTF8, stored in the provided base URL.
  119 +
  120 + For instance:
  121 +
  122 + @code
  123 + // Creates a repository for templates stored in /path/to/templates
  124 + NSURL *baseURL = [NSURL fileURLWithPath:@"/path/to/templates"];
  125 + GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBaseURL:baseURL];
  126 +
  127 + // Returns a template for the file stored in /path/to/templates/profile.mustache
  128 + GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
  129 + @endcode
  130 +
  131 + A partial tag `{{>partial}}` loads a partial template stored in a file named `partial.mustache`, located in the enclosing template's directory.
  132 +
  133 + You may use the slash `/`, and `..`, in order to navigate the URL hierarchical system: `{{>partials/achievements}}`
  134 + would load /path/to/templates/partials/achievements.mustache, if invoked from /path/to/templates/profile.mustache.
  135 +
  136 + When you ask the repository to parse a raw template string, partials are loaded from the base URL:
  137 +
  138 + @code
  139 + // The partial would be loaded from /path/to/templates/partials/achievements.mustache
  140 + GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];
  141 + @endcode
  142 +
  143 + @return a GRMustacheTemplateRepository
  144 + @param URL the base URL where to look templates from.
  145 + */
45 146 + (id)templateRepositoryWithBaseURL:(NSURL *)URL AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
  147 +
  148 +/**
  149 + Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of provided extension,
  150 + encoded in UTF8, stored in the provided base URL.
  151 +
  152 + For instance:
  153 +
  154 + @code
  155 + // Creates a repository for templates of extension `.txt` stored in /path/to/templates
  156 + NSURL *baseURL = [NSURL fileURLWithPath:@"/path/to/templates"];
  157 + GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBaseURL:baseURL
  158 + templateExtension:@"txt"];
  159 +
  160 + // Returns a template for the file stored in /path/to/templates/profile.txt
  161 + GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
  162 + @endcode
  163 +
  164 + A partial tag `{{>partial}}` loads a partial template stored in a file named `partial.txt`, located in the enclosing template's directory.
  165 +
  166 + You may use the slash `/`, and `..`, in order to navigate the URL hierarchical system: `{{>partials/achievements}}`
  167 + would load /path/to/templates/partials/achievements.txt, if invoked from /path/to/templates/profile.txt.
  168 +
  169 + When you ask the repository to parse a raw template string, partials are loaded from the base URL:
  170 +
  171 + @code
  172 + // The partial would be loaded from /path/to/templates/partials/achievements.txt
  173 + GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];
  174 + @endcode
  175 +
  176 + @return a GRMustacheTemplateRepository
  177 + @param URL The base URL where to look templates from.
  178 + @param ext The extension of template files.
  179 + */
46 180 + (id)templateRepositoryWithBaseURL:(NSURL *)URL templateExtension:(NSString *)ext AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
47   -+ (id)templateRepositoryWithBaseURL:(NSURL *)URL templateExtension:(NSString *)ext AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
  181 +
  182 +/**
  183 + Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of provided extension,
  184 + encoded in the provided encoding, stored in the provided base URL.
  185 +
  186 + For instance:
  187 +
  188 + @code
  189 + // Creates a repository for templates of extension `.txt` stored in /path/to/templates, encoded with NSMacOSRomanStringEncoding:
  190 + NSURL *baseURL = [NSURL fileURLWithPath:@"/path/to/templates"];
  191 + GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBaseURL:baseURL
  192 + templateExtension:@"txt"
  193 + encoding:NSMacOSRomanStringEncoding];
  194 +
  195 + // Returns a template for the file stored in /path/to/templates/profile.txt
  196 + GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
  197 + @endcode
  198 +
  199 + A partial tag `{{>partial}}` loads a partial template stored in a file named `partial.txt`, located in the enclosing template's directory.
  200 +
  201 + You may use the slash `/`, and `..`, in order to navigate the URL hierarchical system: `{{>partials/achievements}}`
  202 + would load /path/to/templates/partials/achievements.txt, if invoked from /path/to/templates/profile.txt.
  203 +
  204 + When you ask the repository to parse a raw template string, partials are loaded from the base URL:
  205 +
  206 + @code
  207 + // The partial would be loaded from /path/to/templates/partials/achievements.txt
  208 + GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];
  209 + @endcode
  210 +
  211 + @return a GRMustacheTemplateRepository
  212 + @param URL The base URL where to look templates from.
  213 + @param ext The extension of template files.
  214 + @param encoding The encoding of template files.
  215 + */
48 216 + (id)templateRepositoryWithBaseURL:(NSURL *)URL templateExtension:(NSString *)ext encoding:(NSStringEncoding)encoding AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
49 217 #endif /* if !TARGET_OS_IPHONE || __IPHONE_OS_VERSION_MAX_ALLOWED >= 40000 */
50 218
  219 +/**
  220 + Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of extension .mustache,
  221 + encoded in UTF8, stored in the provided directory.
  222 +
  223 + For instance:
  224 +
  225 + @code
  226 + // Creates a repository for templates stored in /path/to/templates
  227 + GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithDirectory:@"/path/to/templates"];
  228 +
  229 + // Returns a template for the file stored in /path/to/templates/profile.mustache
  230 + GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
  231 + @endcode
  232 +
  233 + A partial tag `{{>partial}}` loads a partial template stored in a file named `partial.mustache`, located in the enclosing template's directory.
  234 +
  235 + You may use the slash `/`, and `..`, in order to navigate the hierarchical file system: `{{>partials/achievements}}`
  236 + would load /path/to/templates/partials/achievements.mustache, if invoked from /path/to/templates/profile.mustache.
  237 +
  238 + When you ask the repository to parse a raw template string, partials are loaded from the base directory:
  239 +
  240 + @code
  241 + // The partial would be loaded from /path/to/templates/partials/achievements.mustache
  242 + GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];
  243 + @endcode
  244 +
  245 + @return a GRMustacheTemplateRepository
  246 + @param path The path of the directory that stores templates.
  247 + */
51 248 + (id)templateRepositoryWithDirectory:(NSString *)path AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
  249 +
  250 +/**
  251 + Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of provided extension,
  252 + encoded in UTF8, stored in the provided directory.
  253 +
  254 + For instance:
  255 +
  256 + @code
  257 + // Creates a repository for templates of extension `.txt` stored in /path/to/templates
  258 + GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithDirectory:@"/path/to/templates"
  259 + templateExtension:@"txt"];
  260 +
  261 + // Returns a template for the file stored in /path/to/templates/profile.txt
  262 + GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
  263 + @endcode
  264 +
  265 + A partial tag `{{>partial}}` loads a partial template stored in a file named `partial.txt`, located in the enclosing template's directory.
  266 +
  267 + You may use the slash `/`, and `..`, in order to navigate the hierarchical file system: `{{>partials/achievements}}`
  268 + would load /path/to/templates/partials/achievements.txt, if invoked from /path/to/templates/profile.txt.
  269 +
  270 + When you ask the repository to parse a raw template string, partials are loaded from the base directory:
  271 +
  272 + @code
  273 + // The partial would be loaded from /path/to/templates/partials/achievements.txt
  274 + GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];
  275 + @endcode
  276 +
  277 + @return a GRMustacheTemplateRepository
  278 + @param path The path of the directory that stores templates.
  279 + @param ext The extension of template files.
  280 + */
52 281 + (id)templateRepositoryWithDirectory:(NSString *)path templateExtension:(NSString *)ext AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
  282 +
  283 +/**
  284 + Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of provided extension,
  285 + encoded in the provided encoding, stored in the provided directory.
  286 +
  287 + For instance:
  288 +
  289 + @code
  290 + // Creates a repository for templates of extension `.txt` stored in /path/to/templates, encoded with NSMacOSRomanStringEncoding:
  291 + GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithDirectory:@"/path/to/templates"
  292 + templateExtension:@"txt"
  293 + encoding:NSMacOSRomanStringEncoding];
  294 +
  295 + // Returns a template for the file stored in /path/to/templates/profile.txt
  296 + GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
  297 + @endcode
  298 +
  299 + A partial tag `{{>partial}}` loads a partial template stored in a file named `partial.txt`, located in the enclosing template's directory.
  300 +
  301 + You may use the slash `/`, and `..`, in order to navigate the hierarchical file system: `{{>partials/achievements}}`
  302 + would load /path/to/templates/partials/achievements.txt, if invoked from /path/to/templates/profile.txt.
  303 +
  304 + When you ask the repository to parse a raw template string, partials are loaded from the base directory:
  305 +
  306 + @code
  307 + // The partial would be loaded from /path/to/templates/partials/achievements.txt
  308 + GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];
  309 + @endcode
  310 +
  311 + @return a GRMustacheTemplateRepository
  312 + @param path The path of the directory that stores templates.
  313 + @param ext The extension of template files.
  314 + @param encoding The encoding of template files.
  315 + */
53 316 + (id)templateRepositoryWithDirectory:(NSString *)path templateExtension:(NSString *)ext encoding:(NSStringEncoding)encoding AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
54 317
  318 +/**
  319 + Returns a GRMustacheTemplateRepository that loads Mustache template strings from resources of extension .mustache,
  320 + encoded in UTF8, stored in the provided bundle.
  321 +
  322 + For instance:
  323 +
  324 + @code
  325 + // Creates a repository for templates stored in the main bundle:
  326 + GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBundle:[NSBundle mainBundle]];
  327 +
  328 + // Returns a template for the resource profile.mustache
  329 + GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
  330 + @endcode
  331 +
  332 + You may provide nil for the bundle parameter: the repository will use the main bundle.
  333 +
  334 + A partial tag `{{>partial}}` loads a partial template from the `partial.mustache` resource in the bundle.
  335 +
  336 + @return a GRMustacheTemplateRepository
  337 + @param bundle The bundle that stores templates as resources.
  338 + */
55 339 + (id)templateRepositoryWithBundle:(NSBundle *)bundle AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
  340 +
  341 +/**
  342 + Returns a GRMustacheTemplateRepository that loads Mustache template strings from resources of provided extension,
  343 + encoded in UTF8, stored in the provided bundle.
  344 +
  345 + For instance:
  346 +
  347 + @code
  348 + // Creates a repository for templates of extension `.txt` stored in the main bundle:
  349 + GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBundle:[NSBundle mainBundle]
  350 + templateExtension:@"txt"];
  351 +
  352 + // Returns a template for the resource profile.txt
  353 + GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
  354 + @endcode
  355 +
  356 + You may provide nil for the bundle parameter: the repository will use the main bundle.
  357 +
  358 + A partial tag `{{>partial}}` loads a partial template from the `partial.txt` resource in the bundle.
  359 +
  360 + @return a GRMustacheTemplateRepository
  361 + @param bundle The bundle that stores templates as resources.
  362 + */
56 363 + (id)templateRepositoryWithBundle:(NSBundle *)bundle templateExtension:(NSString *)ext AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
  364 +
  365 +/**
  366 + Returns a GRMustacheTemplateRepository that loads Mustache template strings from resources of provided extension,
  367 + encoded in the provided encoding, stored in the provided bundle.
  368 +
  369 + For instance:
  370 +
  371 + @code
  372 + // Creates a repository for templates of extension `.txt` stored in the main bundle, encoded with NSMacOSRomanStringEncoding:
  373 + GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBundle:[NSBundle mainBundle]
  374 + templateExtension:@"txt"
  375 + encoding:NSMacOSRomanStringEncoding];
  376 +
  377 + // Returns a template for the resource profile.txt
  378 + GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
  379 + @endcode
  380 +
  381 + You may provide nil for the bundle parameter: the repository will use the main bundle.
  382 +
  383 + A partial tag `{{>partial}}` loads a partial template from the `partial.txt` resource in the bundle.
  384 +
  385 + @return a GRMustacheTemplateRepository
  386 + @param bundle The bundle that stores templates as resources.
  387 + */
57 388 + (id)templateRepositoryWithBundle:(NSBundle *)bundle templateExtension:(NSString *)ext encoding:(NSStringEncoding)encoding AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
58 389
  390 +/**
  391 + Returns a GRMustacheTemplateRepository that loads Mustache template strings from a dictionary
  392 + whose keys are template names, and values template strings.
  393 +
  394 + For instance:
  395 +
  396 + @code
  397 + NSDictionary *partialsDictionary = [NSDictionary dictionaryWithObject:@"It works." forKey:@"partial"];
  398 + GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithPartialsDictionary:partialsDictionary];
  399 +
  400 + // Two templates that would render "It works."
  401 + GRMustacheTemplate *template1 = [repository templateForName:@"partial" error:NULL];
  402 + GRMustacheTemplate *template2 = [repository templateFromString:@"{{>partial}}" error:NULL];
  403 + @endcode
  404 +
  405 + @return a GRMustacheTemplateRepository
  406 + @param partialsDictionary A dictionary of template strings for partial names.
  407 + */
59 408 + (id)templateRepositoryWithPartialsDictionary:(NSDictionary *)partialsDictionary AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
60 409
  410 +/**
  411 + Returns a GRMustacheTemplateRepository.
  412 +
  413 + Until it is provided with a data source, it is unable to load template by names, and unable to process partial tags such as `{{>partial}}`:
  414 +
  415 + @code
  416 + GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepository];
  417 + NSError *error;
  418 +
  419 + // Returns nil, and sets error to an NSError of domain GRMustacheErrorDomain, code GRMustacheErrorCodeTemplateNotFound.
  420 + [repository templateForName:@"foo" error:&error];
  421 +
  422 + // Returns nil, and sets error to an NSError of domain GRMustacheErrorDomain, code GRMustacheErrorCodeTemplateNotFound.
  423 + [repository templateFromString:@"{{>partial}}" error:&error];
  424 + @endcode
  425 +
  426 + It is, however, able to process Mustache template strings without any partial:
  427 +
  428 + @code
  429 + GRMustacheTemplate *template = [repository templateFromString:@"Hello {{name}}!" error:NULL];
  430 + @endcode
  431 +
  432 + You will give it a data source conforming to the GRMustacheTemplateRepositoryDataSource protocol in order to
  433 + load template and partials by name:
  434 +
  435 + @code
  436 + repository.dataSource = ...;
  437 +
  438 + // Returns a template built from the string provided by the dataSource.
  439 + [repository templateForName:@"foo" error:NULL];
  440 + @endcode
  441 +
  442 + @return a GRMustacheTemplateRepository
  443 + */
61 444 + (id)templateRepository AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
62 445
  446 +/**
  447 + Returns a template identified by its name.
  448 +
  449 + Depending on the way the repository has been created, the name identifies a URL, a file path, a key in a dictionary,
  450 + or whatever is relevant to the repository's data source.
  451 +
  452 + @return a GRMustacheTemplate
  453 + @param name The template name
  454 + @param outError If there is an error loading or parsing template and partials, upon return contains an NSError object that describes the problem.
  455 + */
63 456 - (GRMustacheTemplate *)templateForName:(NSString *)name error:(NSError **)outError AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
  457 +
  458 +/**
  459 + Returns a template built from the provided Mustache template string.
  460 +
  461 + Depending on the way the repository has been created, partial tags such as `{{>partial}}` load partial templates from URLs, file paths, keys in a dictionary,
  462 + or whatever is relevant to the repository's data source.
  463 +
  464 + @return a GRMustacheTemplate
  465 + @param templateString A Mustache template string
  466 + @param outError If there is an error loading or parsing template and partials, upon return contains an NSError object that describes the problem.
  467 + */
64 468 - (GRMustacheTemplate *)templateFromString:(NSString *)templateString error:(NSError **)outError AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
65 469 @end
2  include/GRMustacheVersion.h
@@ -33,7 +33,7 @@
33 33
34 34 @since v1.0
35 35 */
36   -#define GRMUSTACHE_MINOR_VERSION 0
  36 +#define GRMUSTACHE_MINOR_VERSION 1
37 37
38 38 /**
39 39 The patch-level component of GRMustache version
BIN  lib/libGRMustache4-MacOS.a
Binary file not shown
BIN  lib/libGRMustache4-iOS.a
Binary file not shown
2  src/classes/GRMustacheVersion.h
@@ -33,7 +33,7 @@
33 33
34 34 @since v1.0
35 35 */
36   -#define GRMUSTACHE_MINOR_VERSION 0
  36 +#define GRMUSTACHE_MINOR_VERSION 1
37 37
38 38 /**
39 39 The patch-level component of GRMustache version

0 comments on commit 459f57b

Please sign in to comment.
Something went wrong with that request. Please try again.