Browse files

Guides/ sports a global description of classes and their re…

  • Loading branch information...
1 parent c8bfc14 commit d87bd1a41be076e282c9a65008d1327f5d1c7cfa @groue committed Jul 27, 2012
Showing with 69 additions and 2 deletions.
  1. +69 −2 Guides/
@@ -8,25 +8,92 @@ You'll find below some useful information on each of those topics.
## Change GRMustache
+### Classes in a glance
+The library features are described in the guides. This section describes the classes that implement those features. They are organized in a few big domains:
+- **Parsing**
+ - `GRMustacheParser`
+ - `GRMustacheToken`
+ The *parser* is able to produce a [parse tree]( of *tokens* out of a template string.
+ For instance, a parser generates three tokens from `Hello {{name}}!`: two text tokens and a variable token.
+- **Compiling**
+ - `GRMustacheCompiler`
+ - `GRMustacheRenderingElement`
+ - `GRMustacheSectionElement`
+ - `GRMustacheTemplate`
+ - `GRMustacheTextElement`
+ - `GRMustacheVariableElement`
+ The *compiler* consumes a parse tree of tokens and outputs an [abstract syntax tree]( of *rendering elements*.
+ Rendering elements are actually able to provide the rendering expected by the library user. *Templates* render full templates and partials, *section elements* render Mustache sections, *text elements* render raw text, and *variable elements* perform variable substitution.
+ For instance, from the tokens parsed from `Hello {{name}}!`, a compiler outputs an AST made of one template containing two text elements and a variable element.
+- **Runtime**
+ - `GRMustacheContext`
+ - `GRMustacheHelper`
+ - `GRMustacheInvocation`
+ - `GRMustacheSection`
+ - `GRMustacheTemplateDelegate`
+ During a template rendering, a *context* implements a state of the context stack that is initialized with the initial object that the library user provides in order to "fill" the template, extends when entering sections, and shrinks when leaving those.
+ A context is able to provide the value for an identifier such as `name` found in a `{{name}}` tag.
+ However, it is not fully responsible for the value lookup. *Invocations* are the definitive objects that provide values that should be rendered. For instance, invocations are able to perform a lookup for key paths such as ``.
+ Invocations are generated by the compiler. Each variable and section element, also generated by the compiler, own an invocation that provides the value that should be rendered.
+ Those invocations are exposed to the *template delegate*, so that the library user can inspect or override values that are rendered.
+ There is another way for the library user to hook into the template rendering: she can implement *helpers* in order to have some sections behave as "Mustache lambda sections". In order to be able to perform the job described by the Mustache specification, they are provided with *section* objects that provide the minimum required information.
+- **Template repositories**
+ - `GRMustacheTemplateRepository`
+ *Template repositories* are objects that provide templates out of template strings from various sources.
+ GRMustache ships with various template repositories that are able to load templates from the file system, and from a dictionary of template strings. The library user can also provide a *data source* to a template repository, in order to load template strings from unimagined locations.
+ Finally, template repositories are responsible for providing the compiler with template partials.
+- **Misc**
+ - GRMustache
+ - GRMustacheNSUndefinedKeyExceptionGuard
+ *GRMustache* provides with library configuration.
+ *GRMustacheNSUndefinedKeyExceptionGuard* is a funny tool that allow the library user to avoid his debugger to stop on every NSUndefinedKeyException raised by the template rendering.
+### Project organisation
Objective-C files that make GRMustache are stored in the `src/classes` folder. They are added to both `GRMustache4-MacOS` and `GRMustache4-iOS` targets of the `src/GRMustache.xcodeproj` project.
Headers are splitted in two categories:
- public headers
- private headers
-### Public headers
+#### Public headers
Public headers must contain only declarations for APIs that are exposed to the GRMustache users. They must not import or include any private header.
Methods and functions declared in public headers must be decorated with the macros defined in `Classes/GRMustacheAvailabilityMacros.h`. Check existing public headers for inspiration.
`src/classes/GRMustacheAvailabilityMacros.h` is generated by `src/bin/buildGRMustacheAvailabilityMacros`.
-### Private headers
+#### Private headers
Private headers have names ending in `_private.h`. They must not import or include any public header. The set of public APIs must be duplicated in both public and private headers.
## Test GRMustache
Before running the tests, make sure git submodules are downloaded:

0 comments on commit d87bd1a

Please sign in to comment.