curly-templates 0.1.0

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/README.md

@@ -0,0 +1,125 @@
+Curly
+=======
+
+Free your views!
+
+Curly is a template language that completely separates structure and logic.
+Instead of interspersing your HTML with snippets of Ruby, all logic is moved
+to a presenter class, with only simple placeholders in the HTML.
+
+While the basic concepts are very similar to [Mustache](http://mustache.github.com/)
+or [Handlebars](http://handlebarsjs.com/), Curly is different in some key ways:
+
+- Instead of the template controlling the variable scope and looping through
+  data, all logic is left to the presenter object. This means that untrusted
+  templates can safely be executed, making Curly a possible alternative to
+  languages like [Liquid](http://liquidmarkup.org/).
+- Instead of implementing its own template resolution mechanism, Curly hooks
+  directly into Rails, leveraging the existing resolvers.
+- Because of the way it integrates with Rails, it is very easy to use partial
+  Curly templates to split out logic from a presenter. With Mustache, at least,
+  when integrating with Rails, it is common to return Hash objects from view
+  object methods that are in turn used by the template.
+
+
+Examples
+--------
+
+Here is a simple Curly template -- it will be looked up by Rails automatically.
+
+```html
+<!-- app/views/posts/show.html.curly -->
+<h1>{{title}}<h1>
+<p class="author">{{author}}</p>
+<p>{{description}}</p>
+
+{{comment_form}}
+
+<div class="comments">
+  {{comments}}
+</div>
+```
+
+When rendering the template, a presenter is automatically instantiated with the
+variables assigned in the controller or the `render` call. The presenter declares
+the variables it expects with `presents`, which takes a list of variables names.
+
+```ruby
+# app/presenters/posts/show_presenter.rb
+class Posts::ShowPresenter < Curly::Presenter
+  presents :post
+
+  def title
+    @post.title
+  end
+
+  def author
+    link_to(@post.author.name, @post.author, rel: "author")
+  end
+
+  def description
+    Markdown.new(@post.description).to_html.html_safe
+  end
+
+  def comments
+    render 'comment', collection: @post.comments
+  end
+
+  def comment_form
+    if @post.comments_allowed?
+      render 'comment_form', post: @post
+    else
+      content_tag(:p, "Comments are disabled for this post")
+    end
+  end
+end
+```
+
+
+Caching
+-------
+
+Because of the way logic is contained in presenters, caching entire views or partials
+becomes exceedingly straightforward. Simply define a `#cache_key` method that returns
+a non-nil object, and the return value will be used to cache the template.
+
+Whereas in ERB your would include the `cache` call in the template itself:
+
+```erb
+<% cache([@post, signed_in?]) do %>
+  ...
+<% end %>
+```
+
+In Curly you would instead declare it in the presenter:
+
+```ruby
+class Posts::ShowPresenter < Curly::Presenter
+  presents :post
+
+  def cache_key
+    [@post, signed_in?]
+  end
+end
+```
+
+Likewise, you can add a `#cache_duration` method if you wish to automatically expire
+the fragment cache:
+
+```ruby
+class Posts::ShowPresenter < Curly::Presenter
+  ...
+
+  def cache_duration
+    30.minutes
+  end
+end
+```
+
+
+Copyright and License
+---------------------
+
+Copyright (c) 2013 Daniel Schierbeck (@dasch), Zendesk Inc.
+
+Licensed under the [Apache License Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).

data/Rakefile

@@ -0,0 +1,132 @@
+require 'rubygems'
+require 'bundler'
+require 'rake'
+require 'date'
+
+Bundler.setup
+
+#############################################################################
+#
+# Helper functions
+#
+#############################################################################
+
+def name
+  "curly"
+end
+
+def gem_name
+  "#{name}-templates"
+end
+
+def version
+  line = File.read("lib/#{name}.rb")[/^\s*VERSION\s*=\s*.*/]
+  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+end
+
+def date
+  Date.today.to_s
+end
+
+def gemspec_file
+  "#{gem_name}.gemspec"
+end
+
+def gem_file
+  "#{gem_name}-#{version}.gem"
+end
+
+def replace_header(head, header_name, value = nil)
+  value ||= send(header_name)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{value}'"}
+end
+
+#############################################################################
+#
+# Standard tasks
+#
+#############################################################################
+
+task :default => :spec
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "#{name} #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -r ./lib/#{name}.rb"
+end
+
+#############################################################################
+#
+# Packaging tasks
+#
+#############################################################################
+
+desc "Create tag v#{version} and build and push #{gem_file} to Rubygems"
+task :release => :build do
+  unless `git branch` =~ /^\* master$/
+    puts "You must be on the master branch to release!"
+    exit!
+  end
+  sh "git commit --allow-empty -a -m 'Release #{version}'"
+  sh "git tag v#{version}"
+  sh "git push origin master"
+  sh "git push origin v#{version}"
+  sh "gem push pkg/#{gem_name}-#{version}.gem"
+end
+
+desc "Build #{gem_file} into the pkg directory"
+task :build => :gemspec do
+  sh "mkdir -p pkg"
+  sh "gem build #{gemspec_file}"
+  sh "mv #{gem_file} pkg"
+end
+
+desc "Generate #{gemspec_file}"
+task :gemspec => :validate do
+  # read spec file and split out manifest section
+  spec = File.read(gemspec_file)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+
+  # replace name version and date
+  replace_header(head, :name, gem_name)
+  replace_header(head, :version)
+  replace_header(head, :date)
+
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(rdoc|pkg)/ }.
+    map { |file| "    #{file}" }.
+    join("\n")
+
+  # piece file back together and write
+  manifest = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+  puts "Updated #{gemspec_file}"
+end
+
+desc "Validate #{gemspec_file}"
+task :validate do
+  libfiles = Dir['lib/*'] - ["lib/#{name}.rb", "lib/#{name}"]
+  unless libfiles.empty?
+    puts "Directory `lib` should only contain a `#{name}.rb` file and `#{name}` dir."
+    exit!
+  end
+  unless Dir['VERSION*'].empty?
+    puts "A `VERSION` file at root level violates Gem best practices."
+    exit!
+  end
+end

data/curly-templates.gemspec

@@ -0,0 +1,44 @@
+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.name              = 'curly-templates'
+  s.version           = '0.1.0'
+  s.date              = '2013-01-21'
+
+  s.summary     = "Free your views!"
+  s.description = "A view layer for your Rails apps that separates structure and logic."
+
+  s.authors  = ["Daniel Schierbeck"]
+  s.email    = 'dasch@zendesk.com'
+  s.homepage = 'http://github.com/zendesk/curly-templates'
+
+  s.require_paths = %w[lib]
+
+  s.rdoc_options = ["--charset=UTF-8"]
+
+  s.add_dependency("actionpack", "~> 3.2.11")
+
+  s.add_development_dependency("rake")
+  s.add_development_dependency("rspec", "~> 2.12.0")
+
+  # = MANIFEST =
+  s.files = %w[
+    Gemfile
+    README.md
+    Rakefile
+    curly-templates.gemspec
+    lib/curly.rb
+    lib/curly/presenter.rb
+    lib/curly/railtie.rb
+    lib/curly/template_handler.rb
+    spec/curly_spec.rb
+    spec/presenter_spec.rb
+    spec/spec_helper.rb
+    spec/template_handler_spec.rb
+  ]
+  # = MANIFEST =
+
+  s.test_files = s.files.select { |path| path =~ /^spec\/.*_spec\.rb/ }
+end

data/lib/curly.rb

@@ -0,0 +1,67 @@
+# Curly is a simple view system. Each view consists of two parts, a
+# template and a presenter. The template is a simple string that can contain
+# references in the format `{{refname}}`, e.g.
+#
+#   Hello {{recipient}},
+#   you owe us ${{amount}}.
+#
+# The references will be converted into messages that are sent to the
+# presenter, which is any Ruby object. Only public methods can be referenced.
+# To continue the earlier example, here's the matching presenter:
+#
+#   class BankPresenter
+#     def initialize(recipient, amount)
+#       @recipient, @amount = recipient, amount
+#     end
+#
+#     def recipient
+#       @recipient.full_name
+#     end
+#
+#     def amount
+#       "%.2f" % @amount
+#     end
+#   end
+#
+# See Curly::Presenter for more information on presenters.
+#
+module Curly
+  VERSION = "0.1.0"
+
+  REFERENCE_REGEX = %r(\{\{(\w+)\}\})
+
+  class InvalidReference < StandardError
+  end
+
+  def self.compile(template)
+    source = template.inspect
+    source.gsub!(REFERENCE_REGEX) { compile_reference($1) }
+
+    source
+  end
+
+  def self.valid?(template, presenter_class)
+    references = extract_references(template)
+    methods = presenter_class.available_methods.map(&:to_s)
+    references & methods == references
+  end
+
+  private
+
+  def self.compile_reference(reference)
+    %(\#{
+      if presenter.method_available?(:#{reference})
+        result = presenter.#{reference} {|*args| yield(*args) }
+        ERB::Util.html_escape(result)
+      else
+        raise Curly::InvalidReference, "invalid reference `{{#{reference}}}'"
+      end
+    })
+  end
+
+  def self.extract_references(template)
+    template.scan(REFERENCE_REGEX).flatten
+  end
+end
+
+require 'curly/railtie' if defined?(Rails)

data/lib/curly/presenter.rb

@@ -0,0 +1,80 @@
+module Curly
+
+  # A base class that can be subclassed by concrete presenters.
+  #
+  # A Curly presenter is responsible for delivering data to templates, in the
+  # form of simple strings. Each public instance method on the presenter class
+  # can be referenced in a template. When a template is evaluated with a
+  # presenter, the referenced methods will be called with no arguments, and
+  # the returned strings inserted in place of the references in the template.
+  #
+  # Note that strings that are not HTML safe will be escaped.
+  #
+  # A presenter is always instantiated with a context to which it delegates
+  # unknown messages, usually an instance of ActionView::Base provided by
+  # Rails. See Curly::Handler for a typical use.
+  #
+  # Examples
+  #
+  #   class BlogPresenter < Curly::Presenter
+  #     presents :post
+  #
+  #     def title
+  #       @post.title
+  #     end
+  #
+  #     def body
+  #       markdown(@post.body)
+  #     end
+  #
+  #     def author
+  #       @post.author.full_name
+  #     end
+  #   end
+  #
+  #   presenter = BlogPresenter.new(context, post: post)
+  #   presenter.author #=> "Jackie Chan"
+  #
+  class Presenter
+    # Initializes the presenter with the given context and options.
+    #
+    # context - An ActionView::Base context.
+    # options - A Hash of options given to the presenter.
+    #
+    def initialize(context, options = {})
+      @_context = context
+      self.class.presented_names.each do |name|
+        instance_variable_set("@#{name}", options.fetch(name))
+      end
+    end
+
+    def cache_key
+      nil
+    end
+
+    def cache_duration
+      nil
+    end
+
+    def method_available?(method)
+      self.class.available_methods.include?(method)
+    end
+
+    def self.available_methods
+      public_instance_methods - Curly::Presenter.public_instance_methods
+    end
+
+    private
+
+    class_attribute :presented_names
+    self.presented_names = [].freeze
+
+    def self.presents(*args)
+      self.presented_names += args
+    end
+
+    def method_missing(method, *args, &block)
+      @_context.public_send(method, *args, &block)
+    end
+  end
+end

data/lib/curly/railtie.rb

@@ -0,0 +1,8 @@
+module Curly
+  class Railtie < Rails::Railtie
+    initializer 'curly.initialize_template_handler' do
+      require 'curly/template_handler'
+      ActionView::Template.register_template_handler :curly, Curly::TemplateHandler
+    end
+  end
+end

data/lib/curly/template_handler.rb

@@ -0,0 +1,51 @@
+require 'active_support'
+require 'action_view'
+require 'curly'
+
+class Curly::TemplateHandler
+  def self.presenter_name_for_path(path)
+    "#{path}_presenter".camelize
+  end
+
+  def self.call(template)
+    presenter_class = presenter_name_for_path(template.virtual_path)
+
+    source = Curly.compile(template.source)
+    template_digest = Digest::MD5.hexdigest(template.source)
+
+    # Template is empty, so there's no need to initialize a presenter.
+    return %("") if template.source.empty?
+
+    <<-RUBY
+    if local_assigns.empty?
+      options = assigns
+    else
+      options = local_assigns
+    end
+
+    presenter = #{presenter_class}.new(self, options.with_indifferent_access)
+
+    view_function = lambda do
+      #{source}
+    end
+
+    if key = presenter.cache_key
+      @output_buffer = ActiveSupport::SafeBuffer.new
+
+      template_digest = #{template_digest.inspect}
+
+      options = {
+        expires_in: presenter.cache_duration
+      }
+
+      cache([template_digest, key], options) do
+        safe_concat(view_function.call)
+      end
+
+      @output_buffer
+    else
+      view_function.call.html_safe
+    end
+    RUBY
+  end
+end

data/spec/curly_spec.rb

@@ -0,0 +1,92 @@
+require 'spec_helper'
+require 'active_support/core_ext/string/output_safety'
+require 'curly'
+
+describe Curly do
+  let :presenter_class do
+    Class.new do
+      def foo
+        "FOO"
+      end
+
+      def high_yield
+        "#{yield}, motherfucker!"
+      end
+
+      def yield_value
+        "#{yield :foo}, please?"
+      end
+
+      def unicorns
+        "UNICORN"
+      end
+
+      def method_available?(method)
+        [:foo, :high_yield, :yield_value, :dirty].include?(method)
+      end
+
+      def self.available_methods
+        public_instance_methods
+      end
+
+      private
+
+      def method_missing(*args)
+        "BAR"
+      end
+    end
+  end
+
+  let(:presenter) { presenter_class.new }
+  let(:context) { double("context", presenter: presenter) }
+
+  it "compiles Curly templates to Ruby code" do
+    evaluate("{{foo}}").should == "FOO"
+  end
+
+  it "makes sure only public methods are called on the presenter object" do
+    expect { evaluate("{{bar}}") }.to raise_exception(Curly::InvalidReference)
+  end
+
+  it "propagates yields to the caller" do
+    evaluate("{{high_yield}}") { "$$$" }.should == "$$$, motherfucker!"
+  end
+
+  it "sends along arguments passed to yield" do
+    evaluate("{{yield_value}}") {|v| v.upcase }.should == "FOO, please?"
+  end
+
+  it "escapes non HTML safe strings returned from the presenter" do
+    presenter.stub(:dirty) { "<p>dirty</p>" }
+    evaluate("{{dirty}}").should == "&lt;p&gt;dirty&lt;/p&gt;"
+  end
+
+  it "does not escape HTML safe strings returned from the presenter" do
+    presenter.stub(:dirty) { "<p>dirty</p>".html_safe }
+    evaluate("{{dirty}}").should == "<p>dirty</p>"
+  end
+
+  describe ".valid?" do
+    it "returns true if only available methods are referenced" do
+      validate("Hello, {{foo}}!").should == true
+    end
+
+    it "returns false if a missing method is referenced" do
+      validate("Hello, {{i_am_missing}}").should == false
+    end
+
+    it "returns false if an unavailable method is referenced" do
+      presenter_class.stub(:available_methods) { [:foo] }
+      validate("Hello, {{inspect}}").should == false
+    end
+
+    def validate(template)
+      Curly.valid?(template, presenter_class)
+    end
+  end
+
+  def evaluate(template)
+    code = Curly.compile(template)
+    context.instance_eval(code)
+  end
+end

data/spec/presenter_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+require 'active_support/all'
+require 'curly/presenter'
+
+describe Curly::Presenter do
+  class CircusPresenter < Curly::Presenter
+    module MonkeyComponents
+      def monkey
+      end
+    end
+
+    include MonkeyComponents
+
+    presents :midget, :clown
+    attr_reader :midget, :clown
+  end
+
+  it "sets the presented parameters as instance variables" do
+    context = double("context")
+
+    presenter = CircusPresenter.new(context,
+      midget: "Meek Harolson",
+      clown: "Bubbles"
+    )
+
+    presenter.midget.should == "Meek Harolson"
+    presenter.clown.should == "Bubbles"
+  end
+end

data/spec/template_handler_spec.rb

@@ -0,0 +1,161 @@
+require 'spec_helper'
+require 'active_support/core_ext/string/output_safety'
+require 'active_support/core_ext/hash'
+require 'curly/template_handler'
+
+describe Curly::TemplateHandler do
+  let :presenter_class do
+    Class.new do
+      def initialize(context, options = {})
+        @context = context
+        @cache_key = options.fetch(:cache_key, nil)
+        @cache_duration = options.fetch(:cache_duration, nil)
+      end
+
+      def foo
+        "FOO"
+      end
+
+      def bar
+        @context.bar
+      end
+
+      def cache_key
+        @cache_key
+      end
+
+      def cache_duration
+        @cache_duration
+      end
+
+      def method_available?(method)
+        true
+      end
+    end
+  end
+
+  let :context_class do
+    Class.new do
+      attr_reader :output_buffer
+      attr_reader :local_assigns, :assigns
+
+      def initialize
+        @cache = Hash.new
+        @local_assigns = Hash.new
+        @assigns = Hash.new
+        @clock = 0
+      end
+
+      def advance_clock(duration)
+        @clock += duration
+      end
+
+      def cache(key, options = {})
+        fragment, expired_at = @cache[key]
+
+        if fragment.nil? || @clock >= expired_at
+          old_buffer = @output_buffer
+          @output_buffer = ActiveSupport::SafeBuffer.new
+
+          yield
+
+          fragment = @output_buffer.to_s
+          duration = options[:expires_in] || Float::INFINITY
+
+          @cache[key] = [fragment, @clock + duration]
+
+          @output_buffer = old_buffer
+        end
+
+        safe_concat(fragment)
+
+        nil
+      end
+
+      def safe_concat(str)
+        @output_buffer.safe_concat(str)
+      end
+    end
+  end
+
+  let(:template) { double("template", virtual_path: "test") }
+  let(:context) { context_class.new }
+
+  before do
+    stub_const("TestPresenter", presenter_class)
+  end
+
+  it "passes in the presenter context to the presenter class" do
+    context.stub(:bar) { "BAR" }
+    template.stub(:source) { "{{bar}}" }
+    output.should == "BAR"
+  end
+
+  it "allows calling public methods on the presenter" do
+    template.stub(:source) { "{{foo}}" }
+    output.should == "FOO"
+  end
+
+  it "marks its output as HTML safe" do
+    template.stub(:source) { "{{foo}}" }
+    output.should be_html_safe
+  end
+
+  context "caching" do
+    before do
+      template.stub(:source) { "{{bar}}" }
+      context.stub(:bar) { "BAR" }
+    end
+
+    it "caches the result with the #cache_key from the presenter" do
+      context.assigns[:cache_key] = "x"
+      output.should == "BAR"
+
+      context.stub(:bar) { "BAZ" }
+      output.should == "BAR"
+
+      context.assigns[:cache_key] = "y"
+      output.should == "BAZ"
+    end
+
+    it "doesn't cache when the cache key is nil" do
+      context.assigns[:cache_key] = nil
+      output.should == "BAR"
+
+      context.stub(:bar) { "BAZ" }
+      output.should == "BAZ"
+    end
+
+    it "adds a digest of the template source to the cache key" do
+      context.assigns[:cache_key] = "x"
+
+      template.stub(:source) { "{{bar}}" }
+      output.should == "BAR"
+
+      template.stub(:source) { "FOO{{bar}}" }
+      output.should == "FOOBAR"
+    end
+
+    it "expires the cache keys after #cache_duration" do
+      context.assigns[:cache_key] = "x"
+      context.assigns[:cache_duration] = 42
+
+      output.should == "BAR"
+
+      context.stub(:bar) { "FOO" }
+
+      # Cached fragment has not yet expired.
+      context.advance_clock(41)
+      output.should == "BAR"
+
+      # Now it has! Huzzah!
+      context.advance_clock(1)
+      output.should == "FOO"
+    end
+  end
+
+  def output
+    code = Curly::TemplateHandler.call(template)
+    context.instance_eval(code)
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: curly-templates
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Daniel Schierbeck
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.11
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.11
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.12.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.12.0
+description: A view layer for your Rails apps that separates structure and logic.
+email: dasch@zendesk.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- Rakefile
+- curly-templates.gemspec
+- lib/curly.rb
+- lib/curly/presenter.rb
+- lib/curly/railtie.rb
+- lib/curly/template_handler.rb
+- spec/curly_spec.rb
+- spec/presenter_spec.rb
+- spec/spec_helper.rb
+- spec/template_handler_spec.rb
+homepage: http://github.com/zendesk/curly-templates
+licenses: []
+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: '0'
+      segments:
+      - 0
+      hash: 924326065759708152
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 2
+summary: Free your views!
+test_files:
+- spec/curly_spec.rb
+- spec/presenter_spec.rb
+- spec/template_handler_spec.rb