cutaneous 0.1.0

data/lib/cutaneous/lexer.rb

@@ -0,0 +1,92 @@
+# encoding: UTF-8
+
+require 'strscan'
+
+module Cutaneous
+  class Lexer
+    attr_reader :template, :syntax
+
+    def initialize(template, syntax)
+      @template, @syntax = template, syntax
+    end
+
+    def tokens
+      @tokens ||= parse
+    end
+
+    # def script
+    #   @script ||= compile
+    # end
+
+    protected
+
+    BRACES ||= /\{|\}/
+    STRIP_WS = "-"
+
+    def parse
+      tokens    = []
+      scanner   = StringScanner.new(@template.to_s)
+      tag_start = syntax.tag_start_pattern
+      tags      = syntax.tags
+      token_map = syntax.token_map
+      previous  = nil
+
+      while (text = scanner.scan_until(tag_start))
+        tag = scanner.matched
+        type, brace_count, endtag_length = token_map[tag]
+        text.slice!(text.length - tag.length, text.length)
+        expression = ""
+        strip_whitespace = false
+
+        begin
+          expression << scanner.scan_until(BRACES)
+          brace = scanner.matched
+          brace_count += ((123 - brace.ord)+1) # '{' = 1,  '}' = -1
+        end while (brace_count > 0)
+
+        length = expression.length
+        expression.slice!(length - endtag_length, length)
+
+        if expression.end_with?(STRIP_WS)
+          strip_whitespace = true
+          length = expression.length
+          expression.slice!(length - 1, length)
+        end
+
+        tokens << place_text_token(text) if text.length > 0
+        tokens << create_token(type, expression, strip_whitespace)
+        previous = type
+      end
+      tokens << place_text_token(scanner.rest) unless scanner.eos?
+      tokens
+    end
+
+    def create_token(type, expression, strip_whitespace)
+      [type, expression, strip_whitespace]
+    end
+
+    #BEGINNING_WHITESPACE ||= /\A\s*?[\r\n]+/
+    #ENDING_WHITESPACE    ||= /(\r?\n)[ \t]*\z/
+    ESCAPE_STRING        ||= /[`\\]/
+
+    def place_text_token(expression)
+      expression.gsub!(syntax.escaped_tag_pattern, '\1')
+      expression.gsub!(ESCAPE_STRING, '\\\\\&')
+      [: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/loader.rb

@@ -0,0 +1,147 @@
+module Cutaneous
+  # Converts a template path or Proc into a Template instance for a particular format
+  class FileLoader
+    attr_accessor :syntax
+    attr_writer   :template_class
+    attr_reader   :format
+
+    def initialize(template_roots, format, extension = Cutaneous.extension)
+      @roots, @format, @extension = template_roots, format, extension
+      @template_class = Template
+    end
+
+    def render(template, context)
+      template(template).render(context)
+    end
+
+    def template(template)
+      return proc_template(template) if template.is_a?(Proc)
+      template_path = path(template)
+      raise UnknownTemplateError.new(@roots, filename(template)) if template_path.nil?
+
+      @template_class.new(file_lexer(template_path)).tap do |template|
+        template.path   = template_path
+        template.loader = self
+      end
+    end
+
+    def proc_template(lmda)
+      StringLoader.new(self).template(lmda.call)
+    end
+
+    def file_lexer(template_path)
+      lexer(SourceFile.new(template_path))
+    end
+
+    def lexer(template_string)
+      Lexer.new(template_string, syntax)
+    end
+
+    def path(template_name)
+      filename = filename(template_name)
+      return filename if ::File.exists?(filename) # Test for an absolute path
+      @roots.map { |root| ::File.join(root, filename)}.detect { |path| ::File.exists?(path) }
+    end
+
+    def filename(template_name)
+      [template_name, @format, @extension].join(".")
+    end
+
+    def exists?(template_root, template_name)
+      File.exists?(File.join(template_root, filename(template_name)))
+    end
+  end
+
+  # Converts a template string into a Template instance.
+  #
+  # Because a string template can only come from the engine instance
+  # we need a FileLoader to delegate all future template loading to.
+  class StringLoader < FileLoader
+    def initialize(file_loader)
+      @file_loader = file_loader
+    end
+
+    def syntax
+      @file_loader.syntax
+    end
+
+    def template(template_string)
+      Template.new(lexer(template_string)).tap do |template|
+        template.loader = @file_loader
+      end
+    end
+  end
+
+  # Converts a filepath to a template string as and when necessary
+  class SourceFile
+    attr_reader :path
+
+    def initialize(filepath)
+      @path = filepath
+    end
+
+    def to_s
+      File.read(@path)
+    end
+  end
+
+  # Caches Template instances
+  class CachedFileLoader < FileLoader
+    def initialize(template_roots, format, extension = Cutaneous.extension)
+      super
+      @template_class = CachedTemplate
+    end
+
+    def template_cache
+      @template_cache ||= {}
+    end
+
+    def write_compiled_scripts=(flag)
+      if flag
+        @template_class = CachedTemplate
+      else
+        @template_class = Template
+      end
+    end
+
+    def template(template)
+      return template_cache[template] if template_cache.key?(template)
+      template_cache[template] = super
+    end
+  end
+
+  # Provides an additional caching mechanism by writing generated template
+  # scripts to a .rb file.
+  class CachedTemplate < Template
+
+    def script
+      if cached?
+        script = File.read(script_path)
+      else
+        script = super
+        File.open(script_path, "w") do |f|
+          f.write(script)
+        end
+      end
+      script
+    end
+
+    def cached?
+      File.exist?(script_path) && (File.mtime(script_path) >= File.mtime(template_path))
+    end
+
+    def template_path
+      lexer.template.path
+    end
+
+    def script_path
+      @source_path ||= generate_script_path
+    end
+
+    def generate_script_path
+      path = template_path
+      ext  = File.extname path
+      path.gsub(/#{ext}$/, ".rb")
+    end
+  end
+end

data/lib/cutaneous/syntax.rb

@@ -0,0 +1,39 @@
+# encoding: UTF-8
+
+module Cutaneous
+  class Syntax
+    attr_reader :tags
+
+    def initialize(tag_definitions)
+      @tags = tag_definitions
+    end
+
+    def is_dynamic?(text)
+      !text.index(tag_start_pattern).nil?
+    end
+
+    def tag_start_pattern
+      @tag_start_pattern ||= compile_start_pattern
+    end
+
+    def escaped_tag_pattern
+      @escaped_tag_pattern ||= compile_start_pattern_with_prefix("\\\\")
+    end
+
+    def compile_start_pattern
+      not_escaped = "(?<!\\\\)"
+      compile_start_pattern_with_prefix(not_escaped)
+    end
+
+    def compile_start_pattern_with_prefix(prefix)
+      openings = self.tags.map { |type, tags| Regexp.escape(tags[0]) }
+      Regexp.new("#{prefix}(#{ openings.join("|") })")
+    end
+
+    # map the set of tags into a hash used by the parse routine that converts an opening tag into a
+    # list of: tag type, the number of opening braces in the tag and the length of the closing tag
+    def token_map
+      @token_map ||= Hash[tags.map { |type, tags| [tags[0], [type, tags[0].count(?{), tags[1].length]] }]
+    end
+  end
+end

data/lib/cutaneous/template.rb

@@ -0,0 +1,40 @@
+module Cutaneous
+  class Template
+    attr_accessor :loader, :lexer, :path
+
+    def initialize(lexer)
+      @lexer = lexer
+    end
+
+    def compiler
+      @compiler ||= Compiler.new(lexer, loader)
+    end
+
+    def render(context)
+      context.__loader = loader
+      context.instance_eval(&template_proc)
+    end
+
+    def template_proc
+      @template_proc ||= eval(template_proc_src, nil, path || "(cutaneous)").tap do |proc|
+        @lexer = nil # release any memory used by the lexer, we don't need it anymore
+      end
+    end
+
+    def template_proc_src
+      "lambda { |context| self.__buf = __buf = ''; #{script}; __buf.to_s }"
+    end
+
+    def script
+      compiler.script
+    end
+
+    def block_order
+      compiler.block_order
+    end
+
+    def block(block_name)
+      compiler.block(block_name)
+    end
+  end
+end

data/lib/cutaneous.rb

@@ -0,0 +1,23 @@
+require 'cutaneous/engine'
+require 'cutaneous/template'
+require 'cutaneous/loader'
+require 'cutaneous/context'
+require 'cutaneous/syntax'
+require 'cutaneous/lexer'
+require 'cutaneous/compiler'
+
+module Cutaneous
+  VERSION = "0.1.0"
+
+  class CompilationError < Exception; end
+
+  class UnknownTemplateError < Exception
+    def initialize(template_roots, relative_path)
+      super("Template '#{relative_path}' not found under #{template_roots.inspect}")
+    end
+  end
+
+  def self.extension
+    "cut"
+  end
+end

data/test/fixtures/a.html.cut

@@ -0,0 +1,13 @@
+aa
+%{ block :b }
+ab
+%{ endblock }
+ac
+%{ block :d }
+ad
+%{ endblock :d }
+ae
+%{ block :f }
+af
+%{ endblock :f }
+ag

data/test/fixtures/b.html.cut

@@ -0,0 +1,8 @@
+%{ extends "a" }
+%{ block :b }
+%{ blocksuper }
+bb
+%{ endblock }
+%{ block :f }
+bf
+%{ endblock }

data/test/fixtures/c.html.cut

@@ -0,0 +1,8 @@
+%{ extends "b" }
+%{ block :b }
+%{ blocksuper }
+cb
+%{ endblock }
+%{ block :f }
+cf
+%{ endblock }

data/test/fixtures/comments.html.cut

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

data/test/fixtures/d.html.cut

@@ -0,0 +1,8 @@
+da
+%{ block :b }
+db
+%{ endblock :b }
+dc
+%{ block :d }
+%{ raise "WRONG" }
+%{ endblock :d }

data/test/fixtures/e.html.cut

@@ -0,0 +1,4 @@
+%{ extends "d" }
+%{ block :d }
+ed
+%{ endblock }

data/test/fixtures/error.html.cut

@@ -0,0 +1,30 @@
+
+
+%{
+	3.times do |n|
+}
+
+!{
+
+	comment
+
+	}
+${ n -}
+%{
+	end }
+%{ include "partial" -}
+%{ test = "here"
+
+-}
+
+
+
+
+here ${ test }
+
+!{
+	the error message should be the same as the line number of the expression
+	}
+%{
+	raise "29"
+}

data/test/fixtures/expressions.html.cut

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

data/test/fixtures/include.html.cut

@@ -0,0 +1,3 @@
+%{ include "partial" -}
+%{ include "partial", right: "wrong" -}
+%{ include "partial", right: "left" -}

data/test/fixtures/include.rss.cut

@@ -0,0 +1,3 @@
+%{ include "partial" -}
+%{ include "partial", right: "wrong" -}
+%{ include "partial", right: "left" -}

data/test/fixtures/included_error.html.cut

@@ -0,0 +1 @@
+%{ include "other/error" }

data/test/fixtures/instance.html.cut

@@ -0,0 +1,2 @@
+%{ @right = "left" -}
+%{ include "instance_include", right: "wrong" -}

data/test/fixtures/instance_include.html.cut

@@ -0,0 +1 @@
+${ @right } = ${ right }

data/test/fixtures/missing.html.cut

@@ -0,0 +1 @@
+missing: ${ unknown }

data/test/fixtures/other/different.html.cut

@@ -0,0 +1 @@
+${ right }

data/test/fixtures/other/error.html.cut

@@ -0,0 +1,5 @@
+!{
+
+
+	}
+%{ raise "5" }

data/test/fixtures/partial.html.cut

@@ -0,0 +1 @@
+right = ${ right }

data/test/fixtures/partial.rss.cut

@@ -0,0 +1 @@
+${ right } = rss

data/test/fixtures/render.html.cut

@@ -0,0 +1,6 @@
+%{
+	require 'ostruct'
+	target = OpenStruct.new
+  target.name = "John"
+-}
+%{ render target, "target" -}

data/test/fixtures/statements.html.cut

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

data/test/fixtures/target.html.cut

@@ -0,0 +1 @@
+${ name }

data/test/fixtures/whitespace.html.cut

@@ -0,0 +1,6 @@
+%{ extends "a" -}
+%{ block :b -}
+%{ 3.times do |n| -}
+here ${ n }
+%{ end -}
+%{ endblock :b -}

data/test/helper.rb

@@ -0,0 +1,18 @@
+$:.push File.expand_path("../../lib", __FILE__)
+
+require 'minitest/spec'
+require 'minitest/autorun'
+
+require 'cutaneous'
+
+class TestContext < Cutaneous::Context
+  def escape(value)
+    value.gsub(/</, "&lt;").gsub(/>/, "&gt;")
+  end
+end
+
+class MiniTest::Spec
+  def ContextHash(params = {})
+    TestContext.new(Object.new, params)
+  end
+end

data/test/test_blocks.rb

@@ -0,0 +1,19 @@
+require File.expand_path('../helper', __FILE__)
+
+describe Cutaneous do
+  let(:template_root) { File.expand_path("../fixtures", __FILE__)                     }
+  let(:engine)        { Cutaneous::Engine.new(template_root, Cutaneous::FirstPassSyntax, "html") }
+
+  it "Will parse & execute a simple template with expressions" do
+    context = ContextHash(right: "right", code: "<tag/>")
+    result = engine.render("c", context)
+    expected = ["aa\n\n", "ab", "bb", "cb", "ac", "ad", "ae", "cf", "ag\n"].join("\n\n")
+    result.must_equal expected
+  end
+
+  it "Won't run code in inherited templates unless called" do
+    context = ContextHash(right: "right", code: "<tag/>")
+    result = engine.render("e", context)
+    result.must_equal ["da", "db", "dc", "ed\n\n"].join("\n\n")
+  end
+end

data/test/test_cache.rb

@@ -0,0 +1,104 @@
+require File.expand_path('../helper', __FILE__)
+
+require 'tmpdir'
+
+describe Cutaneous do
+  let(:source_template_root) { File.expand_path("../fixtures", __FILE__) }
+  let(:dest_template_root)   { Dir.mktmpdir }
+  let(:engine)               { cached_engine }
+
+  def cached_engine
+    Cutaneous::CachingEngine.new(dest_template_root, Cutaneous::FirstPassSyntax, "html")
+  end
+
+  def template(source, format = "html")
+    dest_path = template_path(source, format)
+    FileUtils.mkdir_p(File.dirname(dest_path))
+    FileUtils.cp(File.join(source_template_root, File.basename(dest_path)), dest_path)
+    source
+  end
+
+  def remove_template(source, format = "html")
+    FileUtils.rm(template_path(source, format))
+  end
+
+  def template_path(source, format = "html", extension = "cut")
+    filename =  "#{source}.#{format}.#{extension}"
+    File.join(dest_template_root, filename)
+  end
+
+  it "Reads templates from the cache if they have been used before" do
+    templates = %w(a b c)
+    context = ContextHash(right: "right")
+
+    templates.each do |t|
+      template(t)
+    end
+    result1 = engine.render("c", context)
+
+    templates.each do |t|
+      remove_template(t)
+    end
+
+    result2 = engine.render("c", context)
+    result2.must_equal result1
+  end
+
+  it "Saves the ruby script as a .rb file and uses it if present" do
+    templates = %w(a b c)
+    templates.each do |t|
+      template(t)
+    end
+
+    context = ContextHash(right: "right")
+    result1 = engine.render("c", context)
+
+    # Ensure that the cached script file is being used by overwriting its contents
+    path = template_path("c", "html", "rb")
+    assert ::File.exists?(path), "Template cache should have created '#{path}'"
+    File.open(path, "w") do |f|
+      f.write("__buf << 'right'")
+    end
+
+    engine = cached_engine
+    result2 = engine.render("c", context)
+    result2.must_equal "right"
+  end
+
+  it "Recompiles the cached script if the template is newer" do
+    templates = %w(a b c)
+    templates.each do |t|
+      template(t)
+    end
+    context = ContextHash(right: "right")
+
+    result1 = engine.render("c", context)
+
+    now = Time.now
+
+    template_path = template_path("c", "html")
+    script_path   = template_path("c", "html", "rb")
+    assert ::File.exists?(script_path), "Template cache should have created '#{script_path}'"
+
+    File.open(template_path, "w") { |f| f.write("template") }
+    File.utime(now, now, template_path)
+    File.utime(now - 100, now - 100, script_path)
+
+    engine = cached_engine
+    result1 = engine.render("c", context)
+    result1.must_equal "template"
+  end
+
+  it "Doesn't write a compiled script file if configured not to do so" do
+    engine.write_compiled_scripts = false
+    templates = %w(a b c)
+    templates.each do |t|
+      template(t)
+    end
+    context = ContextHash(right: "right")
+
+    result1 = engine.render("c", context)
+    script_path   = template_path("c", "html", "rb")
+    refute ::File.exists?(script_path), "Template cache should not have created '#{script_path}'"
+  end
+end