cutaneous 0.1.1 → 0.1.2

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2012 Garry Hill
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,151 @@
+# Cutaneous
+
+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/).
+
+Cutaneous is the template engine designed for and used by [Spontaneous CMS](http://spontaneouscms.org).
+
+## Quickstart
+
+<script src="https://gist.github.com/3169319.js"> </script>
+
+<script src="https://gist.github.com/3169327.js"> </script>
+
+## Features
+
+### Template Inheritance
+
+Cutaneous features a block based template inheritance mechanism.
+
+Including a `%{ extends "parent" }` tag at the start of a template
+makes it inherit from the named template ("parent" in this case).
+
+Parent templates define a series of blocks using a `%{ block :block_name}
+... %{ endblock}` syntax. Child templates can then override any of
+these individual blocks with their own content.
+
+Calling `%{ blocksuper }` within a child template's block allows you
+to insert the code from the parent template (much like calling `super`
+in an object subclass).
+
+So for example using the following templates:
+
+<script src="https://gist.github.com/3169196.js"> </script>
+
+<script src="https://gist.github.com/3169203.js"> </script>
+
+`engine.render("child", context, "html")` would result in the following output:
+
+
+    Title
+
+    Template inheritance is great!
+    Template inheritance is great!
+
+    Do it like this...
+
+    And like this...
+
+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`
+
+    result = engine.render("quickstart", context, "txt")
+
+This would look for a `quickstart.txt.cut` template under the template roots. The format used is maintained across both `include` and `extend` calls so when using these you should reference them without any extension.
+
+If your standard format isn't "html" then you can set a new default when creating your template engine instance:
+
+    engine = Cutaneous::Engine.new("/template/root", Cutaneous::FirstPassSyntax, "txt")
+
+
+### Whitespace
+
+If you want to remove trailing whitespace after a tag, then suffix it with a `-` character, e.g.
+
+    %{ include "something" -}
+
+### Caching
+
+If you create an instance of `Cutaneous::CachingEngine` instead of the default `Engine` class then the compiled templates will be cached in-memory for the lifetime of the engine. In order to render templates Cutaneous converts them to simple Ruby code. As part of the caching this generated code will be written to disk alongside the original template with the extension `.format.rb`.
+
+If you want to turn off the writing of the compiled Ruby files (such as in a development environment), set `write_compiled_scripts` to false:
+
+    engine.write_compiled_scripts = false
+
+The cached ruby will only be used if it is fresher than the template it was compiled from so updating the template will re-write the `.rb` equivalent.
+
+
+### Syntaxes
+
+Cutaneous supports the concept of syntaxes. This is used by Spontaneous to provide a two-stage rendering process (first-pass templates output second-pass templates which are rendered on demand -- in this way you can create a very responsive dynamic site because you have precached 99% of the page).
+
+The two syntaxes are:
+
+#### First-pass
+
+- Statements: `%{ ruby code... }`
+- Expressions: `${ value }`
+- Escaped expressions: `$${ unsafe value }`
+- Comments: `!{ comment... }`
+
+#### Second-pass
+
+- Statements: `{% ruby code... %}`
+- Expressions: `{{ value }}`
+- Escaped expressions: `{$ unsafe value $}`
+- Comments: `!{ comment... }`
+
+You choose which one of these you wish to use when you create your `Cutaneous::Engine` instance:
+
+    engine = Cutaneous::Engine.new("/template/root", Cutaneous::SecondPassSyntax)
+
+## Contexts
+
+Cutaneous doesn't try to remove code from your templates it instead allows you to write as much Ruby as you want directly in-place. This is done in order to make the development of your front-end code as quick as possible. If you later want to clean up your template code you can instead use helper methods either on the context you pass to the renderer or the object you wrap that context around.
+
+If you want to add features to your context, or `helpers` as they would be known in Rails-land then create a new Context class and include your helper methods there:
+
+```ruby
+
+    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
+
+    context = MyContext.new(instance, parameter: "value")
+
+    result  = engine.render("template", context)
+```
+
+### Errors
+
+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
+```
+
+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.
+
+## Bugs/TODO
+
+- Make the Syntax more powerful and capable of dealing with any syntax (e.g. implement an ERB like syntax). At the moment they only deal with brace-based syntaxes and brace counting is built into the Lexer.
+- Using template inheritance messes up the line numbers of errors... Not sure what to do about that...
+
+## License
+
+Cutaneous is released under an MIT license (see LICENSE).

data/cutaneous.gemspec

@@ -8,25 +8,28 @@ Gem::Specification.new do |s|
   s.specification_version = 2 if s.respond_to? :specification_version=
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.rubygems_version = '1.3.5'
+  s.required_ruby_version = ">= 1.9.2"
 
   ## Leave these as is they will be modified for you by the rake gemspec task.
   ## 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.1'
-  s.date              = '2012-07-23'
+  s.version           = '0.1.2'
+  s.date              = '2012-07-25'
   s.rubyforge_project = 'cutaneous'
 
   ## Make sure your summary is short. The description may be as long
   ## as you like.
-  s.summary     = "Short description used in Gem listings."
-  s.description = "Long description. Maybe copied from the README."
+  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" \
+    "features such as Djano style template inheritance through blocks."
 
   ## List the primary authors. If there are a bunch of authors, it's probably
   ## better to set the email to an email list or something. If you don't have
   ## a custom homepage, consider using your GitHub URL or the like.
   s.authors  = ["Garry Hill"]
-  s.email    = 'garry@spontaneous.io'
+  s.email    = 'garry@magnetised.net'
   s.homepage = 'https://github.com/SpontaneousCMS/cutaneous'
 
   ## This gets added to the $LOAD_PATH so that 'lib/NAME.rb' can be required as
@@ -71,11 +74,13 @@ Gem::Specification.new do |s|
     test/fixtures/a.html.cut
     test/fixtures/b.html.cut
     test/fixtures/c.html.cut
-    test/fixtures/comments.html.cut
+    test/fixtures/comments1.html.cut
+    test/fixtures/comments2.html.cut
     test/fixtures/d.html.cut
     test/fixtures/e.html.cut
     test/fixtures/error.html.cut
-    test/fixtures/expressions.html.cut
+    test/fixtures/expressions1.html.cut
+    test/fixtures/expressions2.html.cut
     test/fixtures/include.html.cut
     test/fixtures/include.rss.cut
     test/fixtures/included_error.html.cut
@@ -87,9 +92,11 @@ Gem::Specification.new do |s|
     test/fixtures/partial.html.cut
     test/fixtures/partial.rss.cut
     test/fixtures/render.html.cut
-    test/fixtures/statements.html.cut
+    test/fixtures/statements1.html.cut
+    test/fixtures/statements2.html.cut
     test/fixtures/target.html.cut
-    test/fixtures/whitespace.html.cut
+    test/fixtures/whitespace1.html.cut
+    test/fixtures/whitespace2.html.cut
     test/helper.rb
     test/test_blocks.rb
     test/test_cache.rb

data/lib/cutaneous/context.rb

@@ -1,4 +1,5 @@
 require 'delegate'
+require 'cgi'
 
 module Cutaneous
   class Context < Delegator
@@ -15,7 +16,7 @@ module Cutaneous
     end
 
     def escape(value)
-      value
+      CGI::escapeHTML(value)
     end
 
     def include(template_name, locals = {})
@@ -57,8 +58,26 @@ module Cutaneous
       end
     end
 
+    # Sets up the local variables and also creates singleton methods on this
+    # instance so that the local values will override any method implementations
+    # on the context itself. i.e.:
+    #
+    # class MyContext < Cutanteous::Context
+    #   def monkey
+    #     "puzzle"
+    #   end
+    # end
+    #
+    # context = MyContext.new(Object.new, monkey: "magic")
+    #
+    # context.monkey #=> "magic" not "puzzle"
+    #
     def __update_with_locals(locals)
       @__locals.update(locals)
+      singleton = singleton_class
+      locals.each do |name, value|
+        singleton.__send__(:define_method, name) { value }
+      end
       self
     end
 

data/lib/cutaneous/engine.rb

@@ -5,7 +5,7 @@ module Cutaneous
     attr_reader   :roots
     attr_accessor :loader_class, :default_format
 
-    def initialize(template_roots, syntax, default_format = "html")
+    def initialize(template_roots, syntax = Cutaneous::FirstPassSyntax, default_format = "html")
       @roots          = Array(template_roots)
       @syntax    = syntax
       @loader_class   = FileLoader

data/lib/cutaneous/lexer.rb

@@ -75,18 +75,4 @@ module Cutaneous
       [:text, expression]
     end
   end
-
-  FirstPassSyntax = Cutaneous::Syntax.new({
-    :comment => %w(!{ }),
-    :expression => %w(${ }),
-    :escaped_expression => %w($${ }),
-    :statement => %w(%{ })
-  })
-
-  SecondPassSyntax = Cutaneous::Syntax.new({
-    :comment => %w(!{ }),
-    :expression => %w({{ }}),
-    :escaped_expression => %w({$ $}),
-    :statement => %w({% %})
-  })
 end

data/lib/cutaneous.rb

@@ -7,7 +7,7 @@ require 'cutaneous/lexer'
 require 'cutaneous/compiler'
 
 module Cutaneous
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 
   class CompilationError < Exception; end
 
@@ -20,4 +20,18 @@ module Cutaneous
   def self.extension
     "cut"
   end
+
+  FirstPassSyntax = Cutaneous::Syntax.new({
+    :comment => %w(!{ }),
+    :expression => %w(${ }),
+    :escaped_expression => %w($${ }),
+    :statement => %w(%{ })
+  })
+
+  SecondPassSyntax = Cutaneous::Syntax.new({
+    :comment => %w(!{ }),
+    :expression => %w({{ }}),
+    :escaped_expression => %w({$ $}),
+    :statement => %w({% %})
+  })
 end

data/test/fixtures/comments2.html.cut

@@ -0,0 +1 @@
+!{ this is a comment }

data/test/fixtures/expressions2.html.cut

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

data/test/fixtures/statements2.html.cut

@@ -0,0 +1,3 @@
+{% 3.times do |n| %}
+This is {{ right }} {{ n }}
+{% end %}

data/test/fixtures/whitespace2.html.cut

@@ -0,0 +1,3 @@
+{% 3.times do |n| -%}
+here {{ n }}
+{% end -%}

data/test/helper.rb

@@ -6,9 +6,6 @@ require 'minitest/autorun'
 require 'cutaneous'
 
 class TestContext < Cutaneous::Context
-  def escape(value)
-    value.gsub(/</, "&lt;").gsub(/>/, "&gt;")
-  end
 end
 
 class MiniTest::Spec

data/test/test_core.rb

@@ -1,33 +1,70 @@
 require File.expand_path('../helper', __FILE__)
 
-describe Cutaneous do
+describe "First pass parser" do
   let(:template_root) { File.expand_path("../fixtures", __FILE__)                     }
-  let(:engine)        { Cutaneous::Engine.new(template_root, Cutaneous::FirstPassSyntax, "html") }
+  subject { Cutaneous::Engine.new(template_root, Cutaneous::FirstPassSyntax, "html") }
 
-  it "Will parse & execute a simple template with expressions" do
+  it "will parse & execute a simple template with expressions" do
     context = ContextHash(right: "right", code: "<tag/>")
-    result = engine.render("expressions", context)
+    result = subject.render("expressions1", context)
     result.must_equal "This is right &lt;tag/&gt;\n"
   end
 
-  it "Will parse & execute a simple template with statements" do
+  it "will parse & execute a simple template with statements" do
     context = ContextHash(right: "right")
-    result = engine.render("statements", context)
+    result = subject.render("statements1", context)
     result.must_equal "\nThis is right 0\n\nThis is right 1\n\nThis is right 2\n\n"
   end
 
-  it "Will parse & execute a simple template with comments" do
+  it "will parse & execute a simple template with comments" do
     context = ContextHash(right: "right")
-    result = engine.render("comments", context)
+    result = subject.render("comments1", context)
     result.must_equal "\n"
   end
 
-  it "Will remove whitespace after tags with a closing '-'" do
+  it "will remove whitespace after tags with a closing '-'" do
     context = ContextHash(right: "right")
-    result = engine.render("whitespace", context)
+    result = subject.render("whitespace1", context)
     expected = ["aa", "here 0", "here 1", "here 2\n", "ac\n", "ad\n", "ae\n", "af\n", "ag\n"].join("\n")
     result.must_equal expected
   end
+end
+
+describe "Second pass parser" do
+  let(:template_root) { File.expand_path("../fixtures", __FILE__)                     }
+  subject { Cutaneous::Engine.new(template_root, Cutaneous::SecondPassSyntax, "html") }
+
+  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"
+  end
+
+  it "will parse & execute a simple template with statements" do
+    context = ContextHash(right: "right")
+    result = subject.render("statements2", context)
+    result.must_equal "\nThis is right 0\n\nThis is right 1\n\nThis is right 2\n\n"
+  end
+
+  it "will parse & execute a simple template with comments" do
+    context = ContextHash(right: "right")
+    result = subject.render("comments2", context)
+    result.must_equal "\n"
+  end
+
+  it "will remove whitespace after tags with a closing '-'" do
+    context = ContextHash(right: "right")
+    result = subject.render("whitespace2", context)
+    expected = ["here 0", "here 1", "here 2\n"].join("\n")
+    result.must_equal expected
+  end
+end
+
+describe Cutaneous do
+  let(:template_root) { File.expand_path("../fixtures", __FILE__)                     }
+  let(:engine)        { engine1 }
+  let(:engine1)        { Cutaneous::Engine.new(template_root, Cutaneous::FirstPassSyntax, "html") }
+  let(:engine2)        { Cutaneous::Engine.new(template_root, Cutaneous::SecondPassSyntax, "html") }
 
   it "Allows you to include other templates and pass them parameters" do
     context = ContextHash(right: "right")
@@ -129,12 +166,12 @@ describe Cutaneous do
 
   it "Accepts absolute template paths" do
     context = ContextHash(right: "right", code: "<tag/>")
-    result = engine.render(File.join(template_root, "expressions"), context)
+    result = engine.render(File.join(template_root, "expressions1"), context)
     result.must_equal "This is right &lt;tag/&gt;\n"
   end
 
   it "Tests for the existence of a template file for a certain format" do
-    assert engine.template_exists?(template_root, "expressions", "html")
+    assert engine.template_exists?(template_root, "expressions1", "html")
     assert engine.template_exists?(template_root, "other/error", "html")
     assert engine.template_exists?(template_root, "include", "rss")
     refute engine.template_exists?(template_root, "missing", "rss")
@@ -157,12 +194,25 @@ describe Cutaneous do
   it "Overwrites object methods with parameters" do
     klass = Class.new(Object) do
       def monkey; "see"; end
+      def to_s  ; "object"; end
     end
     context = TestContext.new(klass.new)
-    result = engine.render_string("${ monkey }", context)
-    result.must_equal "see"
-    context = TestContext.new(klass.new, monkey: "magic")
-    result = engine.render_string("${ monkey }", context)
-    result.must_equal "magic"
+    result = engine.render_string("${ monkey } ${ to_s }", context)
+    result.must_equal "see object"
+    context = TestContext.new(klass.new, monkey: "magic", to_s: "fairy")
+    result = engine.render_string("${ monkey } ${ to_s }", context)
+    result.must_equal "magic fairy"
+  end
+
+  it "Overwrites helper methods with local values" do
+    context_class = Class.new(TestContext) do
+      def monkey
+        "wrong"
+      end
+    end
+    context = context_class.new(Object.new, monkey: "magic", to_s: "fairy")
+    # def context.monkey; "wrong"; end
+    result = engine.render_string("${ monkey } ${ to_s }", context)
+    result.must_equal "magic fairy"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cutaneous
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,10 +9,12 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-23 00:00:00.000000000 Z
+date: 2012-07-25 00:00:00.000000000 Z
 dependencies: []
-description: Long description. Maybe copied from the README.
-email: garry@spontaneous.io
+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
+  through blocks.
+email: garry@magnetised.net
 executables: []
 extensions: []
 extra_rdoc_files:
@@ -36,11 +38,13 @@ files:
 - test/fixtures/a.html.cut
 - test/fixtures/b.html.cut
 - test/fixtures/c.html.cut
-- test/fixtures/comments.html.cut
+- test/fixtures/comments1.html.cut
+- test/fixtures/comments2.html.cut
 - test/fixtures/d.html.cut
 - test/fixtures/e.html.cut
 - test/fixtures/error.html.cut
-- test/fixtures/expressions.html.cut
+- test/fixtures/expressions1.html.cut
+- test/fixtures/expressions2.html.cut
 - test/fixtures/include.html.cut
 - test/fixtures/include.rss.cut
 - test/fixtures/included_error.html.cut
@@ -52,9 +56,11 @@ files:
 - test/fixtures/partial.html.cut
 - test/fixtures/partial.rss.cut
 - test/fixtures/render.html.cut
-- test/fixtures/statements.html.cut
+- test/fixtures/statements1.html.cut
+- test/fixtures/statements2.html.cut
 - test/fixtures/target.html.cut
-- test/fixtures/whitespace.html.cut
+- test/fixtures/whitespace1.html.cut
+- test/fixtures/whitespace2.html.cut
 - test/helper.rb
 - test/test_blocks.rb
 - test/test_cache.rb
@@ -71,7 +77,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -83,7 +89,7 @@ rubyforge_project: cutaneous
 rubygems_version: 1.8.21
 signing_key: 
 specification_version: 2
-summary: Short description used in Gem listings.
+summary: A Ruby templating language with Django style template inheritance
 test_files:
 - test/test_blocks.rb
 - test/test_cache.rb