cutaneous 0.1.3 → 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 702a4ccd825a31c0136fba20ad088b14e6594252
+  data.tar.gz: a1719c431d6f5b5c4c18575acab709d70082878e
+SHA512:
+  metadata.gz: 13a594778df91b6a0dc7524f7611982a198243646dc507317e227fb3f5ad7edd4530eb4496e8e2850a54eefe3b351a5da23b4abd1a2974993048e4492af73cf6
+  data.tar.gz: 7d792d27a5416f83787e4e860cfcb9d4ea3972c2b8afe578aee69df68a8557e508a572b0e4b9a5af3201afb0b2531db902e1823c12a81933da518a2fc3963b8a

data/README.md

@@ -1,5 +1,7 @@
 # Cutaneous
 
+**Cutaneous** _adj._ Of the skin.
+
 Cutaneous is a Ruby (1.9+) templating engine designed for flexibility and simplicity.
 
 It supports having multiple output formats, multiple syntaxes and borrows a template inheritance mechanism from Python template engines such as  [Django's](https://docs.djangoproject.com/en/dev/topics/templates/), [Jinja](http://jinja.pocoo.org/) and [Mako](http://www.makotemplates.org/).
@@ -12,6 +14,91 @@ Cutaneous is the template engine designed for and used by [Spontaneous CMS](http
 
 <script src="https://gist.github.com/3169327.js"> </script>
 
+The `Cutaneous::Engine` class provides two core methods:
+
+- `Cutaneous::Engine#render(template_path, context, format)`  
+  
+  This renders the template at `template_path` using the context `context` (which must be an instance of Cutaneous::Context (or a subclass)) and the format `format`.
+  
+  `template_path` should be specified as either a relative path which will be resolved using a search through the template roots specified in the engine's initialisation call. See below for more information about how templates are specified & resolved.
+  
+- `Cutaneous::Engine#render_string(template, context, format)`  
+  
+  This takes the input string as the template and renders it. If this string references other templates through includes (see below) these are resolved as if you had made a call to `Engine#render`.
+
+### Template Naming & Resolution
+
+By default Cutaneous templates should be given a `.cut` file extension.
+
+Cutaneous generally relies upon relative template names. If we consider the following code:
+
+```ruby
+
+engine  = Cutaneous::Engine.new([
+	"/home/user/templates",
+	"/home/user/shared_templates"
+])
+
+context = Cutaneous::Context.new(Object.new, title: "Welcome")
+
+result  = engine.render("welcome", context, "html")
+```
+
+The `#render` call will look for a file called `welcome.html.cut` under each of the supplied template roots & return the first one it finds:
+
+```ruby
+
+# The template resolution is equivalent to the following Ruby code:
+search_paths =  [
+	"/home/user/templates/welcome.html.cut",
+	"/home/user/shared_templates/welcome.html.cut"
+]
+
+template_path = search_paths.detect { |path| File.exist?(path) }
+
+```
+
+Template filenames are derived from `[template_relative_path, format, "cut"].join(".")`.
+
+If you specified a different format for the render call, e.g. `engine.render("welcome", context, "txt")` then the engine would instead look for a file named `welcome.txt.cut`.
+
+If you want to organise your templates into subdirectories then you are completely free to do so, you just need to add the subdirectory name onto the relative path:
+
+```ruby
+    
+result  = engine.render("layouts/welcome", context, "html")
+
+#=> Renders the file "/home/user/templates/layouts/welcome.html.cut"
+```
+
+#### Includes
+
+To include one template file into another you use the `include` directive within your template:
+
+    %{ include 'partial/header' }
+
+This will include the output of rendering the file "/home/user/templates/partial/header.html.cut" directly in your original template's output (assuming you're rendering the "html" format).
+
+Note that Cutaneous has no special treatment of "partials", there is no special `partial` command and no preceeding underscore in the template name.
+
+#### Passing a Proc as a Template
+
+If you want to switch between rendering file based & string based templates then Cutaneous provides a way of using the same `Engine#render` call by passing a Proc as the template path:
+
+```ruby
+
+# This
+template = "Hello ${ name }!"
+engine.render(Proc.new { template }, context)
+
+# is the same as:
+engine.render_string(template, context)
+
+```
+
+This allows us to use simple strings as template paths and still use a consistent calling mechanism.
+
+
 ## Features
 
 ### Template Inheritance
@@ -49,6 +136,8 @@ So for example using the following templates:
 
 The template hierarchy can be as long as you need/like. Template 'd' could extend 'c' which extends 'b' which extends 'a' etc..
 
+
+
 ### Formats
 
 Cutaneous allows templates for multiple formats to exist alongside each other. In the examples above the `html` format is exclsuively used but instead of this I could render the same template as `txt`
@@ -111,20 +200,20 @@ If you want to add features to your context, or `helpers` as they would be known
 
 ```ruby
 
-    module MyHelperMethods
-     def my_helpful_method
-       # ... do something complex that you want to keep out of the template
-     end
-    end
+module MyHelperMethods
+ def my_helpful_method
+	 # ... do something complex that you want to keep out of the template
+ end
+end
 
-    # You *must* inherit from Cutaneous::Context!
-    class MyContext < Cutaneous::Context
-      include MyHelperMethods
-    end
+# You *must* inherit from Cutaneous::Context!
+class MyContext < Cutaneous::Context
+	include MyHelperMethods
+end
 
-    context = MyContext.new(instance, parameter: "value")
+context = MyContext.new(instance, parameter: "value")
 
-    result  = engine.render("template", context)
+result  = engine.render("template", context)
 ```
 
 ### Errors
@@ -132,11 +221,11 @@ If you want to add features to your context, or `helpers` as they would be known
 Cutaneous silently swallows errors about missing expressions in templates. If you want to instead report these errors override the `__handle_error` context method:
 
 ```ruby
-    class MyContext < Cutaneous::Context
-      def __handle_error(e)
-        logger.warn(e)
-      end
-    end
+class MyContext < Cutaneous::Context
+	def __handle_error(e)
+		logger.warn(e)
+	end
+end
 ```
 
 Cutaneous will do its best to keep the line numbers consistent between templates and the generated code (although see "Bugs" below...). This will hopefully make debugging easier.

data/cutaneous.gemspec

@@ -14,15 +14,15 @@ Gem::Specification.new do |s|
   ## If your rubyforge_project name is different, then edit it and comment out
   ## the sub! line in the Rakefile
   s.name              = 'cutaneous'
-  s.version           = '0.1.3'
-  s.date              = '2012-07-25'
+  s.version           = '0.1.4'
+  s.date              = '2013-08-17'
   s.rubyforge_project = 'cutaneous'
 
   ## Make sure your summary is short. The description may be as long
   ## as you like.
   s.summary     = "A Ruby templating language with Django style template inheritance"
   s.description = "Cutaneous is the Ruby templating language designed for " \
-    "use with Spontaneous CMS. It has a simple syntax but powerful" \
+    "use with Spontaneous CMS. It has a simple syntax but powerful " \
     "features such as Djano style template inheritance through blocks."
 
   ## List the primary authors. If there are a bunch of authors, it's probably

data/lib/cutaneous.rb

@@ -7,7 +7,7 @@ require 'cutaneous/lexer'
 require 'cutaneous/compiler'
 
 module Cutaneous
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 
   class CompilationError < Exception; end
 
@@ -30,8 +30,8 @@ module Cutaneous
 
   SecondPassSyntax = Cutaneous::Syntax.new({
     :comment => %w(!{ }),
-    :expression => %w({{ }}),
-    :escaped_expression => %w({$ $}),
+    :expression => %w({{{ }}}),
+    :escaped_expression => %w({{ }}),
     :statement => %w({% %})
   })
 end

data/test/fixtures/expressions2.html.cut

@@ -1 +1 @@
-This is {{  right  }} {$ code $}
+This is {{  right  }} {{ code }} {{{ code }}}

data/test/test_core.rb

@@ -37,7 +37,7 @@ describe "Second pass parser" do
   it "will parse & execute a simple template with expressions" do
     context = ContextHash(right: "right", code: "<tag/>")
     result = subject.render("expressions2", context)
-    result.must_equal "This is right &lt;tag/&gt;\n"
+    result.must_equal "This is right &lt;tag/&gt; <tag/>\n"
   end
 
   it "will parse & execute a simple template with statements" do

metadata

@@ -1,18 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: cutaneous
 version: !ruby/object:Gem::Version
-  version: 0.1.3
-  prerelease: 
+  version: 0.1.4
 platform: ruby
 authors:
 - Garry Hill
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-25 00:00:00.000000000 Z
+date: 2013-08-17 00:00:00.000000000 Z
 dependencies: []
 description: Cutaneous is the Ruby templating language designed for use with Spontaneous
-  CMS. It has a simple syntax but powerfulfeatures such as Djano style template inheritance
+  CMS. It has a simple syntax but powerful features such as Djano style template inheritance
   through blocks.
 email: garry@magnetised.net
 executables: []
@@ -69,26 +68,25 @@ files:
 - test/test_core.rb
 homepage: https://github.com/SpontaneousCMS/cutaneous
 licenses: []
+metadata: {}
 post_install_message: 
 rdoc_options:
 - --charset=UTF-8
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: cutaneous
-rubygems_version: 1.8.21
+rubygems_version: 2.0.3
 signing_key: 
 specification_version: 2
 summary: A Ruby templating language with Django style template inheritance