Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

v4.1.0

  • Loading branch information...
commit 459f57b3bca90af54bec7c969c61d3dd8dbabf60 1 parent 59e778e
Gwendal Roué authored
34 Guides/delegate.md
View
@@ -23,13 +23,13 @@ The following methods are called before, and after the whole template rendering:
The following methods are called before, and after the rendering of substitution and sections tags (`{{name}}` and `{{#name}}...{{/name}}`):
```objc
-- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation;
-- (void)template:(GRMustacheTemplate *)template didRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation;
+- (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation;
+- (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.
+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.
-You can read the following properties of the *invocation* argument:
+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.
@@ -37,16 +37,32 @@ You can read the following properties of the *invocation* argument:
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: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`.
+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`.
+
+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.
+
+The *interpretation* parameter tells you how the return value of the invocation is used:
+
+```objc
+typedef enum {
+ GRMustacheInterpretationSection,
+ GRMustacheInterpretationVariable,
+} 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.
+
+You will find an actual use of this *interpretation* parameter in the [number formatting sample code](sample_code/number_formatting.md).
-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.
### A practical use: debugging templates
You may, for instance, locate keys that could not find any data:
```objc
-- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation
+- (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
{
// When returnValue is nil, GRMustache could not find any value to render.
if (invocation.returnValue == nil) {
@@ -66,7 +82,7 @@ GRMustache missing key: `items` for <GRMustacheInvocation: {{#items}} at line 23
Alter the template rendering
----------------------------
-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.
+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.
**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.**
@@ -74,7 +90,7 @@ The `returnValue` property of the *invocation* argument can be written. If you s
### A practical use: providing default values for missing keys
```objc
-- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation
+- (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
{
// When returnValue is nil, GRMustache could not find any value to render.
if (invocation.returnValue == nil) {
2  Guides/sample_code/indexes.md
View
@@ -95,7 +95,7 @@ Now let's replace array elements with proxies before they are rendered:
/**
This method is called when the template is about to render a tag.
*/
-- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation
+- (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
{
/**
The invocation object tells us which object is about to be rendered.
41 Guides/sample_code/number_formatting.md
View
@@ -171,7 +171,7 @@ And then implement the delegate methods:
Each time we'll enter a section that is attached to a NSNumberFormatter,
we'll enqueue this NSNumberFormatter in the stack. This is done in
- [template:willRenderReturnValueOfInvocation:]
+ [template:willInterpretReturnValueOfInvocation:as:]
*/
self.templateNumberFormatterStack = [NSMutableArray array];
}
@@ -179,7 +179,7 @@ And then implement the delegate methods:
/**
This method is called when the template is about to render a tag.
*/
-- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation
+- (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
{
/**
The invocation object tells us which object is about to be rendered.
@@ -188,17 +188,42 @@ And then implement the delegate methods:
{
/**
If it is a NSNumberFormatter, enqueue it in
- templateNumberFormatterStack.
+ templateNumberFormatterStack, and return.
*/
[self.templateNumberFormatterStack addObject:invocation.returnValue];
+ return;
}
- else if (self.templateNumberFormatterStack.count > 0 && [invocation.returnValue isKindOfClass:[NSNumber class]])
+
+ if (interpretation == GRMustacheInterpretationSection)
+ {
+ /**
+ We actually only format numbers for variable tags such as `{{name}}`.
+ We must carefully avoid messing with sections: they as well can be
+ provided with numbers, that they interpret as booleans. We surely
+ do not want to convert booleans to strings...
+
+ So let's ignore sections, and return.
+ */
+ return;
+ }
+
+ if (self.templateNumberFormatterStack.count == 0)
+ {
+ /**
+ If our number formatter stack is empty, we can not format anything:
+ let's return.
+ */
+ return;
+ }
+
+ if ([invocation.returnValue isKindOfClass:[NSNumber class]])
{
/**
- If it is a NSNumber, and if our templateNumberFormatterStack is not
- empty, use the top NSNumberFormatter to format the number.
+ There we are: invocation's return value is a NSNumber, and our
+ templateNumberFormatterStack is not empty.
- Set the invocation's returnValue: this is the object that will be
+ Let's use the top NSNumberFormatter to format this number, and set
+ the invocation's returnValue: this is the object that will be
rendered.
*/
NSNumberFormatter *numberFormatter = self.templateNumberFormatterStack.lastObject;
@@ -210,7 +235,7 @@ And then implement the delegate methods:
/**
This method is called right after the template has rendered a tag.
*/
-- (void)template:(GRMustacheTemplate *)template didRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation
+- (void)template:(GRMustacheTemplate *)template didInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation
{
/**
Make sure we dequeue NSNumberFormatters when we leave their scope.
39 RELEASE_NOTES.md
View
@@ -3,6 +3,45 @@ GRMustache Release Notes
You can compare the performances of GRMustache versions at https://github.com/groue/GRMustacheBenchmark.
+## v4.1.0
+
+### GRMustacheDelegate protocol
+
+A template's delegate is now able to know how a value will be interpreted by GRMustache.
+
+New APIs:
+
+```objc
+typedef enum {
+ GRMustacheInterpretationSection,
+ GRMustacheInterpretationVariable,
+} GRMustacheInterpretation;
+
+@protocol GRMustacheTemplateDelegate<NSObject>
+- (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation;
+- (void)template:(GRMustacheTemplate *)template didInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation;
+@end
+```
+
+Deprecated APIs:
+
+```objc
+@protocol GRMustacheTemplateDelegate<NSObject>
+- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation;
+- (void)template:(GRMustacheTemplate *)template didRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation;
+@end
+```
+
+The new APIs are documented in [Guides/delegate.md](Guides/delegate.md).
+
+### GRMustacheTemplateRepositoryDataSource protocol
+
+The return type of `-[GRMustacheTemplateRepositoryDataSource templateRepository:templateIDForName:relativeToTemplateID:]` as changed from `id` to `id<NSCopying>`.
+
+### Errors
+
+GRMustache used to output badly formatted errors. They are now easier to read.
+
## v4.0.0
**Performance improvements**
58 include/GRMustacheAvailabilityMacros.h
View
@@ -29,6 +29,7 @@
* Set up standard GRMustache versions
*/
#define GRMUSTACHE_VERSION_4_0 4000
+#define GRMUSTACHE_VERSION_4_1 4010
@@ -36,10 +37,10 @@
/*
- * If max GRMustacheVersion not specified, assume 4.0
+ * If max GRMustacheVersion not specified, assume 4.1
*/
#ifndef GRMUSTACHE_VERSION_MAX_ALLOWED
-#define GRMUSTACHE_VERSION_MAX_ALLOWED GRMUSTACHE_VERSION_4_0
+#define GRMUSTACHE_VERSION_MAX_ALLOWED GRMUSTACHE_VERSION_4_1
#endif
/*
@@ -91,3 +92,56 @@
+/*
+ * AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER
+ *
+ * Used on declarations introduced in GRMustache 4.1
+ */
+#if GRMUSTACHE_VERSION_MAX_ALLOWED < GRMUSTACHE_VERSION_4_1
+#define AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER UNAVAILABLE_ATTRIBUTE
+#elif GRMUSTACHE_VERSION_MIN_REQUIRED < GRMUSTACHE_VERSION_4_1
+#define AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER WEAK_IMPORT_ATTRIBUTE
+#else
+#define AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER
+#endif
+
+/*
+ * AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER_BUT_DEPRECATED
+ *
+ * Used on declarations introduced in GRMustache 4.1,
+ * and deprecated in GRMustache 4.1
+ */
+#if GRMUSTACHE_VERSION_MIN_REQUIRED >= GRMUSTACHE_VERSION_4_1
+#define AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER_BUT_DEPRECATED DEPRECATED_ATTRIBUTE
+#else
+#define AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER_BUT_DEPRECATED AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER
+#endif
+
+/*
+ * AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER_BUT_DEPRECATED_IN_GRMUSTACHE_VERSION_4_1
+ *
+ * Used on declarations introduced in GRMustache 4.0,
+ * but later deprecated in GRMustache 4.1
+ */
+#if GRMUSTACHE_VERSION_MIN_REQUIRED >= GRMUSTACHE_VERSION_4_1
+#define AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER_BUT_DEPRECATED_IN_GRMUSTACHE_VERSION_4_1 DEPRECATED_ATTRIBUTE
+#else
+#define AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER_BUT_DEPRECATED_IN_GRMUSTACHE_VERSION_4_1 AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER
+#endif
+
+/*
+ * DEPRECATED_IN_GRMUSTACHE_VERSION_4_1_AND_LATER
+ *
+ * Used on types deprecated in GRMustache 4.1
+ */
+#if GRMUSTACHE_VERSION_MIN_REQUIRED >= GRMUSTACHE_VERSION_4_1
+#define DEPRECATED_IN_GRMUSTACHE_VERSION_4_1_AND_LATER DEPRECATED_ATTRIBUTE
+#else
+#define DEPRECATED_IN_GRMUSTACHE_VERSION_4_1_AND_LATER
+#endif
+
+
+
+
+
+
11 include/GRMustacheSection.h
View
@@ -26,12 +26,15 @@
@class GRMustacheInvocation;
@class GRMustacheTemplate;
+/**
+ A GRMustacheSection represents a Mustache section such as `{{#name}}...{{/name}}`.
+ */
@interface GRMustacheSection: NSObject {
@private
GRMustacheInvocation *_invocation;
GRMustacheTemplate *_rootTemplate;
NSString *_templateString;
- NSRange _range;
+ NSRange _innerRange;
BOOL _inverted;
NSArray *_elems;
id _renderingContext;
@@ -44,8 +47,6 @@
/**
Returns the current rendering context.
-
- @since v2.0
*/
@property (nonatomic, readonly) id renderingContext AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
@@ -58,8 +59,6 @@
/**
Returns the literal inner content of the section, with unprocessed mustache `{{tags}}`.
-
- @since v2.0
*/
@property (nonatomic, readonly) NSString *innerTemplateString AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
@@ -72,8 +71,6 @@
Renders the inner content of the receiver with the current context
@return A string containing the rendered inner content.
-
- @since v2.0
*/
- (NSString *)render AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
3  include/GRMustacheTemplate.h
View
@@ -46,12 +46,9 @@
/**
Parses a template string, and returns a compiled template.
- The behavior of the returned template is determined by [GRMustache defaultTemplateOptions].
-
@return A GRMustacheTemplate instance
@param templateString The template string
@param outError If there is an error loading or parsing template and partials, upon return contains an NSError object that describes the problem.
- @see [GRMustache defaultTemplateOptions]
@since v1.11
*/
+ (id)templateFromString:(NSString *)templateString error:(NSError **)outError AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
11 include/GRMustacheTemplateDelegate.h
View
@@ -26,10 +26,17 @@
@class GRMustacheTemplate;
@class GRMustacheInvocation;
+typedef enum {
+ GRMustacheInterpretationSection,
+ GRMustacheInterpretationVariable,
+} GRMustacheInterpretation;
+
@protocol GRMustacheTemplateDelegate<NSObject>
@optional
- (void)templateWillRender:(GRMustacheTemplate *)template AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
- (void)templateDidRender:(GRMustacheTemplate *)template AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
-- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
-- (void)template:(GRMustacheTemplate *)template didRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
+- (void)template:(GRMustacheTemplate *)template willRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER_BUT_DEPRECATED_IN_GRMUSTACHE_VERSION_4_1;
+- (void)template:(GRMustacheTemplate *)template didRenderReturnValueOfInvocation:(GRMustacheInvocation *)invocation AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER_BUT_DEPRECATED_IN_GRMUSTACHE_VERSION_4_1;
+- (void)template:(GRMustacheTemplate *)template willInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER;
+- (void)template:(GRMustacheTemplate *)template didInterpretReturnValueOfInvocation:(GRMustacheInvocation *)invocation as:(GRMustacheInterpretation)interpretation AVAILABLE_GRMUSTACHE_VERSION_4_1_AND_LATER;
@end
408 include/GRMustacheTemplateRepository.h
View
@@ -27,39 +27,443 @@
@class GRMustacheTemplate;
@class GRMustacheTemplateRepository;
+/**
+ The protocol for a GRMustacheTemplateRepository's dataSource.
+
+ The dataSource's responsability is to provide Mustache template strings for template and partial names.
+
+ @see GRMustacheTemplateRepository
+ */
@protocol GRMustacheTemplateRepositoryDataSource <NSObject>
@required
-- (id)templateRepository:(GRMustacheTemplateRepository *)templateRepository templateIDForName:(NSString *)name relativeToTemplateID:(id)templateID AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
+
+/**
+ Returns a template ID, that is to say an object that uniquely identifies a template or a template partial.
+
+ The class of this ID is opaque: your implementation of a GRMustacheTemplateRepositoryDataSource
+ would define, for itself, what kind of object would identity a template or a partial.
+
+ For instance, a file-based data source may use NSString objects containing paths to the templates.
+
+ You should try to choose "human-readable" template IDs. That is because template IDs are embedded in
+ the description of errors that may happen during a template processing, in order to help the library
+ user locate, and fix, the faulting template.
+
+ Whenever relevant, template and partial hierarchies are supported via the _baseTemplateID_ parameter: it contains
+ the template ID of the enclosing template, or nil when the data source is asked for a template ID for a partial
+ that is referred from a raw template string (see [GRMustacheTemplateRepository templateFromString:error:]).
+
+ Not all data sources have to implement hierarchies: they can simply ignore this parameter.
+
+ The returned value can be nil: the library user would then eventually get an NSError of domain
+ GRMustacheErrorDomain and code GRMustacheErrorCodeTemplateNotFound.
+
+ @return a template ID
+ @param templateRepository The GRMustacheTemplateRepository asking for a template ID.
+ @param name The name of the template or template partial.
+ @param baseTemplateID The template ID of the enclosing template, or nil.
+ */
+- (id<NSCopying>)templateRepository:(GRMustacheTemplateRepository *)templateRepository templateIDForName:(NSString *)name relativeToTemplateID:(id)baseTemplateID AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
+
+/**
+ Provided with a template ID that comes from templateRepository:templateIDForName:relativeToTemplateID:,
+ returns a Mustache template string.
+
+ For instance, a file-based data source may interpret the template ID as a NSString object
+ containing paths to the template, and return the file content.
+
+ A few words about the way your implementation of this method must handle errors:
+
+ As usually, whenever this method returns nil, the _outError_ parameter should point to
+ a valid NSError. This NSError would eventually reach the library user.
+
+ However, should you "forget" to set the _outError_ parameter, GRMustache would generate for you
+ an NSError of domain GRMustacheErrorDomain and code GRMustacheErrorCodeTemplateNotFound.
+
+ @return a Mustache template string
+ @param templateRepository The GRMustacheTemplateRepository asking for a Mustache template string.
+ @param templateID The template ID of the template
+ @param outError If there is an error returning a template string, upon return contains nil, or an NSError object that describes the problem.
+ */
- (NSString *)templateRepository:(GRMustacheTemplateRepository *)templateRepository templateStringForTemplateID:(id)templateID error:(NSError **)outError AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
@end
+
+/**
+ Given a data source that provides Mustache template strings, a GRMustacheTemplateRepository's responsability
+ is to provide GRMustacheTemplate instances.
+
+ You may provide your own template string data source. However common cases such as loading templates
+ from URLs, files, bundle resources, and dictionaries, are already implemented.
+
+ @see GRMustacheTemplate
+ @see GRMustacheTemplateRepositoryDataSource
+ */
@interface GRMustacheTemplateRepository : NSObject {
@private
id<GRMustacheTemplateRepositoryDataSource> _dataSource;
NSMutableDictionary *_templateForTemplateID;
id _currentlyParsedTemplateID;
}
+
+/**
+ The repository's data source.
+ */
@property (nonatomic, assign) id<GRMustacheTemplateRepositoryDataSource> dataSource AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
#if !TARGET_OS_IPHONE || __IPHONE_OS_VERSION_MAX_ALLOWED >= 40000
+
+/**
+ Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of extension .mustache,
+ encoded in UTF8, stored in the provided base URL.
+
+ For instance:
+
+ @code
+ // Creates a repository for templates stored in /path/to/templates
+ NSURL *baseURL = [NSURL fileURLWithPath:@"/path/to/templates"];
+ GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBaseURL:baseURL];
+
+ // Returns a template for the file stored in /path/to/templates/profile.mustache
+ GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
+ @endcode
+
+ A partial tag `{{>partial}}` loads a partial template stored in a file named `partial.mustache`, located in the enclosing template's directory.
+
+ You may use the slash `/`, and `..`, in order to navigate the URL hierarchical system: `{{>partials/achievements}}`
+ would load /path/to/templates/partials/achievements.mustache, if invoked from /path/to/templates/profile.mustache.
+
+ When you ask the repository to parse a raw template string, partials are loaded from the base URL:
+
+ @code
+ // The partial would be loaded from /path/to/templates/partials/achievements.mustache
+ GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];
+ @endcode
+
+ @return a GRMustacheTemplateRepository
+ @param URL the base URL where to look templates from.
+ */
+ (id)templateRepositoryWithBaseURL:(NSURL *)URL AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
+
+/**
+ Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of provided extension,
+ encoded in UTF8, stored in the provided base URL.
+
+ For instance:
+
+ @code
+ // Creates a repository for templates of extension `.txt` stored in /path/to/templates
+ NSURL *baseURL = [NSURL fileURLWithPath:@"/path/to/templates"];
+ GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBaseURL:baseURL
+ templateExtension:@"txt"];
+
+ // Returns a template for the file stored in /path/to/templates/profile.txt
+ GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
+ @endcode
+
+ A partial tag `{{>partial}}` loads a partial template stored in a file named `partial.txt`, located in the enclosing template's directory.
+
+ You may use the slash `/`, and `..`, in order to navigate the URL hierarchical system: `{{>partials/achievements}}`
+ would load /path/to/templates/partials/achievements.txt, if invoked from /path/to/templates/profile.txt.
+
+ When you ask the repository to parse a raw template string, partials are loaded from the base URL:
+
+ @code
+ // The partial would be loaded from /path/to/templates/partials/achievements.txt
+ GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];
+ @endcode
+
+ @return a GRMustacheTemplateRepository
+ @param URL The base URL where to look templates from.
+ @param ext The extension of template files.
+ */
+ (id)templateRepositoryWithBaseURL:(NSURL *)URL templateExtension:(NSString *)ext AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
-+ (id)templateRepositoryWithBaseURL:(NSURL *)URL templateExtension:(NSString *)ext AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
+
+/**
+ Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of provided extension,
+ encoded in the provided encoding, stored in the provided base URL.
+
+ For instance:
+
+ @code
+ // Creates a repository for templates of extension `.txt` stored in /path/to/templates, encoded with NSMacOSRomanStringEncoding:
+ NSURL *baseURL = [NSURL fileURLWithPath:@"/path/to/templates"];
+ GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBaseURL:baseURL
+ templateExtension:@"txt"
+ encoding:NSMacOSRomanStringEncoding];
+
+ // Returns a template for the file stored in /path/to/templates/profile.txt
+ GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
+ @endcode
+
+ A partial tag `{{>partial}}` loads a partial template stored in a file named `partial.txt`, located in the enclosing template's directory.
+
+ You may use the slash `/`, and `..`, in order to navigate the URL hierarchical system: `{{>partials/achievements}}`
+ would load /path/to/templates/partials/achievements.txt, if invoked from /path/to/templates/profile.txt.
+
+ When you ask the repository to parse a raw template string, partials are loaded from the base URL:
+
+ @code
+ // The partial would be loaded from /path/to/templates/partials/achievements.txt
+ GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];
+ @endcode
+
+ @return a GRMustacheTemplateRepository
+ @param URL The base URL where to look templates from.
+ @param ext The extension of template files.
+ @param encoding The encoding of template files.
+ */
+ (id)templateRepositoryWithBaseURL:(NSURL *)URL templateExtension:(NSString *)ext encoding:(NSStringEncoding)encoding AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
#endif /* if !TARGET_OS_IPHONE || __IPHONE_OS_VERSION_MAX_ALLOWED >= 40000 */
+/**
+ Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of extension .mustache,
+ encoded in UTF8, stored in the provided directory.
+
+ For instance:
+
+ @code
+ // Creates a repository for templates stored in /path/to/templates
+ GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithDirectory:@"/path/to/templates"];
+
+ // Returns a template for the file stored in /path/to/templates/profile.mustache
+ GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
+ @endcode
+
+ A partial tag `{{>partial}}` loads a partial template stored in a file named `partial.mustache`, located in the enclosing template's directory.
+
+ You may use the slash `/`, and `..`, in order to navigate the hierarchical file system: `{{>partials/achievements}}`
+ would load /path/to/templates/partials/achievements.mustache, if invoked from /path/to/templates/profile.mustache.
+
+ When you ask the repository to parse a raw template string, partials are loaded from the base directory:
+
+ @code
+ // The partial would be loaded from /path/to/templates/partials/achievements.mustache
+ GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];
+ @endcode
+
+ @return a GRMustacheTemplateRepository
+ @param path The path of the directory that stores templates.
+ */
+ (id)templateRepositoryWithDirectory:(NSString *)path AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
+
+/**
+ Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of provided extension,
+ encoded in UTF8, stored in the provided directory.
+
+ For instance:
+
+ @code
+ // Creates a repository for templates of extension `.txt` stored in /path/to/templates
+ GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithDirectory:@"/path/to/templates"
+ templateExtension:@"txt"];
+
+ // Returns a template for the file stored in /path/to/templates/profile.txt
+ GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
+ @endcode
+
+ A partial tag `{{>partial}}` loads a partial template stored in a file named `partial.txt`, located in the enclosing template's directory.
+
+ You may use the slash `/`, and `..`, in order to navigate the hierarchical file system: `{{>partials/achievements}}`
+ would load /path/to/templates/partials/achievements.txt, if invoked from /path/to/templates/profile.txt.
+
+ When you ask the repository to parse a raw template string, partials are loaded from the base directory:
+
+ @code
+ // The partial would be loaded from /path/to/templates/partials/achievements.txt
+ GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];
+ @endcode
+
+ @return a GRMustacheTemplateRepository
+ @param path The path of the directory that stores templates.
+ @param ext The extension of template files.
+ */
+ (id)templateRepositoryWithDirectory:(NSString *)path templateExtension:(NSString *)ext AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
+
+/**
+ Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of provided extension,
+ encoded in the provided encoding, stored in the provided directory.
+
+ For instance:
+
+ @code
+ // Creates a repository for templates of extension `.txt` stored in /path/to/templates, encoded with NSMacOSRomanStringEncoding:
+ GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithDirectory:@"/path/to/templates"
+ templateExtension:@"txt"
+ encoding:NSMacOSRomanStringEncoding];
+
+ // Returns a template for the file stored in /path/to/templates/profile.txt
+ GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
+ @endcode
+
+ A partial tag `{{>partial}}` loads a partial template stored in a file named `partial.txt`, located in the enclosing template's directory.
+
+ You may use the slash `/`, and `..`, in order to navigate the hierarchical file system: `{{>partials/achievements}}`
+ would load /path/to/templates/partials/achievements.txt, if invoked from /path/to/templates/profile.txt.
+
+ When you ask the repository to parse a raw template string, partials are loaded from the base directory:
+
+ @code
+ // The partial would be loaded from /path/to/templates/partials/achievements.txt
+ GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];
+ @endcode
+
+ @return a GRMustacheTemplateRepository
+ @param path The path of the directory that stores templates.
+ @param ext The extension of template files.
+ @param encoding The encoding of template files.
+ */
+ (id)templateRepositoryWithDirectory:(NSString *)path templateExtension:(NSString *)ext encoding:(NSStringEncoding)encoding AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
+/**
+ Returns a GRMustacheTemplateRepository that loads Mustache template strings from resources of extension .mustache,
+ encoded in UTF8, stored in the provided bundle.
+
+ For instance:
+
+ @code
+ // Creates a repository for templates stored in the main bundle:
+ GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBundle:[NSBundle mainBundle]];
+
+ // Returns a template for the resource profile.mustache
+ GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
+ @endcode
+
+ You may provide nil for the bundle parameter: the repository will use the main bundle.
+
+ A partial tag `{{>partial}}` loads a partial template from the `partial.mustache` resource in the bundle.
+
+ @return a GRMustacheTemplateRepository
+ @param bundle The bundle that stores templates as resources.
+ */
+ (id)templateRepositoryWithBundle:(NSBundle *)bundle AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
+
+/**
+ Returns a GRMustacheTemplateRepository that loads Mustache template strings from resources of provided extension,
+ encoded in UTF8, stored in the provided bundle.
+
+ For instance:
+
+ @code
+ // Creates a repository for templates of extension `.txt` stored in the main bundle:
+ GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBundle:[NSBundle mainBundle]
+ templateExtension:@"txt"];
+
+ // Returns a template for the resource profile.txt
+ GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
+ @endcode
+
+ You may provide nil for the bundle parameter: the repository will use the main bundle.
+
+ A partial tag `{{>partial}}` loads a partial template from the `partial.txt` resource in the bundle.
+
+ @return a GRMustacheTemplateRepository
+ @param bundle The bundle that stores templates as resources.
+ */
+ (id)templateRepositoryWithBundle:(NSBundle *)bundle templateExtension:(NSString *)ext AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
+
+/**
+ Returns a GRMustacheTemplateRepository that loads Mustache template strings from resources of provided extension,
+ encoded in the provided encoding, stored in the provided bundle.
+
+ For instance:
+
+ @code
+ // Creates a repository for templates of extension `.txt` stored in the main bundle, encoded with NSMacOSRomanStringEncoding:
+ GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBundle:[NSBundle mainBundle]
+ templateExtension:@"txt"
+ encoding:NSMacOSRomanStringEncoding];
+
+ // Returns a template for the resource profile.txt
+ GRMustacheTemplate *template = [repository templateForName:@"profile" error:NULL];
+ @endcode
+
+ You may provide nil for the bundle parameter: the repository will use the main bundle.
+
+ A partial tag `{{>partial}}` loads a partial template from the `partial.txt` resource in the bundle.
+
+ @return a GRMustacheTemplateRepository
+ @param bundle The bundle that stores templates as resources.
+ */
+ (id)templateRepositoryWithBundle:(NSBundle *)bundle templateExtension:(NSString *)ext encoding:(NSStringEncoding)encoding AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
+/**
+ Returns a GRMustacheTemplateRepository that loads Mustache template strings from a dictionary
+ whose keys are template names, and values template strings.
+
+ For instance:
+
+ @code
+ NSDictionary *partialsDictionary = [NSDictionary dictionaryWithObject:@"It works." forKey:@"partial"];
+ GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithPartialsDictionary:partialsDictionary];
+
+ // Two templates that would render "It works."
+ GRMustacheTemplate *template1 = [repository templateForName:@"partial" error:NULL];
+ GRMustacheTemplate *template2 = [repository templateFromString:@"{{>partial}}" error:NULL];
+ @endcode
+
+ @return a GRMustacheTemplateRepository
+ @param partialsDictionary A dictionary of template strings for partial names.
+ */
+ (id)templateRepositoryWithPartialsDictionary:(NSDictionary *)partialsDictionary AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
+/**
+ Returns a GRMustacheTemplateRepository.
+
+ 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}}`:
+
+ @code
+ GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepository];
+ NSError *error;
+
+ // Returns nil, and sets error to an NSError of domain GRMustacheErrorDomain, code GRMustacheErrorCodeTemplateNotFound.
+ [repository templateForName:@"foo" error:&error];
+
+ // Returns nil, and sets error to an NSError of domain GRMustacheErrorDomain, code GRMustacheErrorCodeTemplateNotFound.
+ [repository templateFromString:@"{{>partial}}" error:&error];
+ @endcode
+
+ It is, however, able to process Mustache template strings without any partial:
+
+ @code
+ GRMustacheTemplate *template = [repository templateFromString:@"Hello {{name}}!" error:NULL];
+ @endcode
+
+ You will give it a data source conforming to the GRMustacheTemplateRepositoryDataSource protocol in order to
+ load template and partials by name:
+
+ @code
+ repository.dataSource = ...;
+
+ // Returns a template built from the string provided by the dataSource.
+ [repository templateForName:@"foo" error:NULL];
+ @endcode
+
+ @return a GRMustacheTemplateRepository
+ */
+ (id)templateRepository AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
+/**
+ Returns a template identified by its name.
+
+ Depending on the way the repository has been created, the name identifies a URL, a file path, a key in a dictionary,
+ or whatever is relevant to the repository's data source.
+
+ @return a GRMustacheTemplate
+ @param name The template name
+ @param outError If there is an error loading or parsing template and partials, upon return contains an NSError object that describes the problem.
+ */
- (GRMustacheTemplate *)templateForName:(NSString *)name error:(NSError **)outError AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
+
+/**
+ Returns a template built from the provided Mustache template string.
+
+ 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,
+ or whatever is relevant to the repository's data source.
+
+ @return a GRMustacheTemplate
+ @param templateString A Mustache template string
+ @param outError If there is an error loading or parsing template and partials, upon return contains an NSError object that describes the problem.
+ */
- (GRMustacheTemplate *)templateFromString:(NSString *)templateString error:(NSError **)outError AVAILABLE_GRMUSTACHE_VERSION_4_0_AND_LATER;
@end
2  include/GRMustacheVersion.h
View
@@ -33,7 +33,7 @@
@since v1.0
*/
-#define GRMUSTACHE_MINOR_VERSION 0
+#define GRMUSTACHE_MINOR_VERSION 1
/**
The patch-level component of GRMustache version
BIN  lib/libGRMustache4-MacOS.a
View
Binary file not shown
BIN  lib/libGRMustache4-iOS.a
View
Binary file not shown
2  src/classes/GRMustacheVersion.h
View
@@ -33,7 +33,7 @@
@since v1.0
*/
-#define GRMUSTACHE_MINOR_VERSION 0
+#define GRMUSTACHE_MINOR_VERSION 1
/**
The patch-level component of GRMustache version
Please sign in to comment.
Something went wrong with that request. Please try again.