Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 470 lines (347 sloc) 22.613 kB
5e5ea55 @groue v1.13.0
authored
1 // The MIT License
2 //
3 // Copyright (c) 2012 Gwendal Roué
4 //
5 // Permission is hereby granted, free of charge, to any person obtaining a copy
6 // of this software and associated documentation files (the "Software"), to deal
7 // in the Software without restriction, including without limitation the rights
8 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 // copies of the Software, and to permit persons to whom the Software is
10 // furnished to do so, subject to the following conditions:
11 //
12 // The above copyright notice and this permission notice shall be included in
13 // all copies or substantial portions of the Software.
14 //
15 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21 // THE SOFTWARE.
22
23 #import <Foundation/Foundation.h>
24 #import "GRMustacheAvailabilityMacros.h"
25 #import "GRMustache.h"
26
27 @class GRMustacheTemplate;
28 @class GRMustacheTemplateRepository;
29
459f57b @groue v4.1.0
authored
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 */
5e5ea55 @groue v1.13.0
authored
37 @protocol GRMustacheTemplateRepositoryDataSource <NSObject>
38 @required
459f57b @groue v4.1.0
authored
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 */
6337526 @groue v4.0.0
authored
88 - (NSString *)templateRepository:(GRMustacheTemplateRepository *)templateRepository templateStringForTemplateID:(id)templateID error:(NSError **)outError AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
5e5ea55 @groue v1.13.0
authored
89 @end
90
459f57b @groue v4.1.0
authored
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 */
5e5ea55 @groue v1.13.0
authored
102 @interface GRMustacheTemplateRepository : NSObject {
103 @private
104 id<GRMustacheTemplateRepositoryDataSource> _dataSource;
105 NSMutableDictionary *_templateForTemplateID;
106 id _currentlyParsedTemplateID;
107 }
459f57b @groue v4.1.0
authored
108
109 /**
110 The repository's data source.
111 */
6337526 @groue v4.0.0
authored
112 @property (nonatomic, assign) id<GRMustacheTemplateRepositoryDataSource> dataSource AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
5e5ea55 @groue v1.13.0
authored
113
ed879f3 @groue v2.0.0
authored
114 #if !TARGET_OS_IPHONE || __IPHONE_OS_VERSION_MAX_ALLOWED >= 40000
459f57b @groue v4.1.0
authored
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 */
6337526 @groue v4.0.0
authored
146 + (id)templateRepositoryWithBaseURL:(NSURL *)URL AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
459f57b @groue v4.1.0
authored
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 */
6337526 @groue v4.0.0
authored
180 + (id)templateRepositoryWithBaseURL:(NSURL *)URL templateExtension:(NSString *)ext AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
459f57b @groue v4.1.0
authored
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 */
6337526 @groue v4.0.0
authored
216 + (id)templateRepositoryWithBaseURL:(NSURL *)URL templateExtension:(NSString *)ext encoding:(NSStringEncoding)encoding AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
ed879f3 @groue v2.0.0
authored
217 #endif /* if !TARGET_OS_IPHONE || __IPHONE_OS_VERSION_MAX_ALLOWED >= 40000 */
5e5ea55 @groue v1.13.0
authored
218
459f57b @groue v4.1.0
authored
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 */
6337526 @groue v4.0.0
authored
248 + (id)templateRepositoryWithDirectory:(NSString *)path AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
459f57b @groue v4.1.0
authored
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 */
6337526 @groue v4.0.0
authored
281 + (id)templateRepositoryWithDirectory:(NSString *)path templateExtension:(NSString *)ext AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
459f57b @groue v4.1.0
authored
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 */
6337526 @groue v4.0.0
authored
316 + (id)templateRepositoryWithDirectory:(NSString *)path templateExtension:(NSString *)ext encoding:(NSStringEncoding)encoding AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
5e5ea55 @groue v1.13.0
authored
317
459f57b @groue v4.1.0
authored
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 */
6337526 @groue v4.0.0
authored
339 + (id)templateRepositoryWithBundle:(NSBundle *)bundle AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
459f57b @groue v4.1.0
authored
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 */
6337526 @groue v4.0.0
authored
363 + (id)templateRepositoryWithBundle:(NSBundle *)bundle templateExtension:(NSString *)ext AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
459f57b @groue v4.1.0
authored
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 */
6337526 @groue v4.0.0
authored
388 + (id)templateRepositoryWithBundle:(NSBundle *)bundle templateExtension:(NSString *)ext encoding:(NSStringEncoding)encoding AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
5e5ea55 @groue v1.13.0
authored
389
459f57b @groue v4.1.0
authored
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 */
6337526 @groue v4.0.0
authored
408 + (id)templateRepositoryWithPartialsDictionary:(NSDictionary *)partialsDictionary AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
5e5ea55 @groue v1.13.0
authored
409
459f57b @groue v4.1.0
authored
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 */
6337526 @groue v4.0.0
authored
444 + (id)templateRepository AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
5e5ea55 @groue v1.13.0
authored
445
459f57b @groue v4.1.0
authored
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 */
6337526 @groue v4.0.0
authored
456 - (GRMustacheTemplate *)templateForName:(NSString *)name error:(NSError **)outError AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
459f57b @groue v4.1.0
authored
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 */
6337526 @groue v4.0.0
authored
468 - (GRMustacheTemplate *)templateFromString:(NSString *)templateString error:(NSError **)outError AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
5e5ea55 @groue v1.13.0
authored
469 @end
Something went wrong with that request. Please try again.