mustache 0.3.2 → 0.4.0

data/HISTORY.md

@@ -1,3 +1,19 @@
+## 0.4.0 (2009-10-27)
+
+* Stopped raising context miss exceptions by default
+* Added `Mustache.raise_on_context_miss` setting (defaults to false)
+* Throw Mustache::ContextMiss when raise_on_context_miss is true and
+  we encounter a miss.
+* The default template extension is now "mustache" (instead of "html").
+* Added the `view_namespace` and `view_path` settings to `Mustache`
+* Added `Mustache.view_class` method which autoloads a class using the
+  new `view_namespace` and `view_path` settings. Should be used by
+  plugin developers.
+* Updated the Sinatra extension to use the new `view_class` method
+* Unclosed sections now throw a helpful error message
+* Report line numbers on unclosed section errors
+* Added Rack::Bug panel
+
 ## 0.3.2 (2009-10-19)
 
 * Bugfix: Partials in Sinatra were using the wrong path.

data/README.md

@@ -103,9 +103,11 @@ The most basic tag is the variable. A `{{name}}` tag in a basic
 template will try to call the `name` method on your view. If there is
 no `name` method, an exception will be raised.
 
-All variables are HTML escaped by default. If you want, for some
-reason, to return unescaped HTML you can use the triple mustache:
-`{{{name}}}`.
+All variables are HTML escaped by default. If you want to return
+unescaped HTML, use the triple mustache: `{{{name}}}`.
+
+By default a variable "miss" returns an empty string. You can
+configure this by setting `Mustache.raise_on_context_miss` to true.
 
 ### Boolean Sections
 
@@ -215,7 +217,7 @@ ctemplate and friends want you to hand a dictionary to the template
 processor. Mustache supports a similar concept. Feel free to mix the
 class-based and this more procedural style at your leisure.
 
-Given this template (winner.html):
+Given this template (winner.mustache):
 
     Hello {{name}}
     You have just won ${{value}}!
@@ -247,7 +249,7 @@ A word on templates. By default, a view will try to find its template
 on disk by searching for an HTML file in the current directory that
 follows the classic Ruby naming convention.
 
-    TemplatePartial => ./template_partial.html
+    TemplatePartial => ./template_partial.mustache
 
 You can set the search path using `Mustache.template_path`. It can be set on a
 class by class basis:
@@ -257,13 +259,13 @@ class by class basis:
       ... etc ...
     end
 
-Now `Simple` will look for `simple.html` in the directory it resides
+Now `Simple` will look for `simple.mustache` in the directory it resides
 in, no matter the cwd.
 
 If you want to just change what template is used you can set
 `Mustache.template_file` directly:
 
-    Simple.template_file = './blah.html'
+    Simple.template_file = './blah.mustache'
 
 Mustache also allows you to define the extension it'll use.
 
@@ -283,6 +285,15 @@ Or set a different template for a single instance:
 Whatever works.
 
 
+Views
+-----
+
+Mustache supports a bit of magic when it comes to views. If you're
+authoring a plugin or extension for a web framework (Sinatra, Rails,
+etc), check out the `view_namespace` and `view_path` settings on the
+`Mustache` class. They will surely provide needed assistance.
+
+
 Helpers
 -------
 
@@ -364,6 +375,23 @@ An example Sinatra application is also provided:
 <http://github.com/defunkt/mustache-sinatra-example>
 
 
+[Rack::Bug][4]
+---------
+
+Mustache also ships with a `Rack::Bug` panel. In your `config.ru` add
+the following code:
+
+    require 'rack/bug/panels/mustache_panel'
+    use Rack::Bug::MustachePanel
+
+Using Rails? Add this to your initializer or environment file:
+
+    require 'rack/bug/panels/mustache_panel'
+    config.middleware.use "Rack::Bug::MustachePanel"
+
+[![Rack::Bug](http://img.skitch.com/20091027-xyf4h1yxnefpp7usyddrcmc7dn.png)][5]
+
+
 Vim
 ---
 
@@ -405,3 +433,5 @@ Meta
 [1]: http://code.google.com/p/google-ctemplate/
 [2]: http://www.ivan.fomichev.name/2008/05/erlang-template-engine-prototype.html
 [3]: http://google-ctemplate.googlecode.com/svn/trunk/doc/howto.html
+[4]: http://github.com/brynary/rack-bug/
+[5]: http://img.skitch.com/20091027-n8pxwwx8r61tc318a15q1n6m14.png

data/examples/namespaced.mustache

@@ -0,0 +1 @@
+<h1>{{title}}</h1>

data/examples/namespaced.rb

@@ -0,0 +1,17 @@
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'mustache'
+
+module TestViews
+  class Namespaced < Mustache
+    self.path = File.dirname(__FILE__)
+
+    def title
+      "Dragon < Tiger"
+    end
+  end
+end
+
+
+if $0 == __FILE__
+  puts TestViews::Namespaced.to_html
+end

data/lib/mustache.rb

@@ -7,7 +7,7 @@ require 'mustache/context'
 # The typical Mustache workflow is as follows:
 #
 # * Create a Mustache subclass: class Stats < Mustache
-# * Create a template: stats.html
+# * Create a template: stats.mustache
 # * Instantiate an instance: view = Stats.new
 # * Render that instance: view.render
 #
@@ -30,12 +30,12 @@ require 'mustache/context'
 # looking for a template. By default it is "."
 # Setting it to /usr/local/templates, for example, means (given all
 # other settings are default) a Mustache subclass `Stats` will try to
-# load /usr/local/templates/stats.html
+# load /usr/local/templates/stats.mustache
 #
 # * template_extension
 #
 # The `template_extension` is the extension Mustache uses when looking
-# for template files. By default it is "html"
+# for template files. By default it is "mustache"
 #
 # * template_file
 #
@@ -56,6 +56,19 @@ require 'mustache/context'
 #   view.template = "Hi, {{person}}!"
 #   view[:person] = 'Mom'
 #   view.render # => Hi, mom!
+#
+# * view_namespace
+#
+# To make life easy on those developing Mustache plugins for web frameworks or
+# other libraries, Mustache will attempt to load view classes (i.e. Mustache
+# subclasses) using the `view_class` class method. The `view_namespace` tells
+# Mustache under which constant view classes live. By default it is `Object`.
+#
+# * view_path
+#
+# Similar to `template_path`, the `view_path` option tells Mustache where to look
+# for files containing view classes when using the `view_class` method.
+#
 class Mustache
   # Helper method for quickly instantiating and rendering a view.
   def self.render(*args)
@@ -93,9 +106,9 @@ class Mustache
     self.template_path = path
   end
 
-  # A Mustache template's default extension is 'html'
+  # A Mustache template's default extension is 'mustache'
   def self.template_extension
-    @template_extension ||= 'html'
+    @template_extension ||= 'mustache'
   end
 
   def self.template_extension=(template_extension)
@@ -104,7 +117,7 @@ class Mustache
   end
 
   # The template file is the absolute path of the file Mustache will
-  # use as its template. By default it's ./class_name.html
+  # use as its template. By default it's ./class_name.mustache
   def self.template_file
     @template_file || "#{path}/#{underscore}.#{template_extension}"
   end
@@ -126,6 +139,75 @@ class Mustache
     @template = templateify(template)
   end
 
+  # The constant under which Mustache will look for views. By default it's
+  # `Object`, but it might be nice to set it to something like `Hurl::Views` if
+  # your app's main namespace is `Hurl`.
+  def self.view_namespace
+    @view_namespace || Object
+  end
+
+  def self.view_namespace=(namespace)
+    @view_namespace = namespace
+  end
+
+  # Mustache searches the view path for .rb files to require when asked to find a
+  # view class. Defaults to "."
+  def self.view_path
+    @view_path ||= '.'
+  end
+
+  def self.view_path=(path)
+    @view_path = path
+  end
+
+  # When given a symbol or string representing a class, will try to produce an
+  # appropriate view class.
+  # e.g.
+  #   Mustache.view_namespace = Hurl::Views
+  #   Mustache.view_class(:Partial) # => Hurl::Views::Partial
+  def self.view_class(name)
+    if name != classify(name.to_s)
+      name = classify(name.to_s)
+    end
+
+    # Emptiness begets emptiness.
+    if name.to_s == ''
+      return Mustache
+    end
+
+    file_name = underscore(name)
+    namespace = view_namespace
+
+    if namespace.const_defined?(:Views) && namespace::Views.const_defined?(name)
+      namespace::Views.const_get(name)
+    elsif namespace.const_defined?(name)
+      namespace.const_get(name)
+    elsif File.exists?(file = "#{view_path}/#{file_name}.rb")
+      require "#{file}".chomp('.rb')
+      if namespace.const_defined?(:Views)
+        namespace::Views.const_get(name)
+      else
+        namespace.const_get(name)
+      end
+    else
+      Mustache
+    end
+  end
+
+  # Should an exception be raised when we cannot find a corresponding method
+  # or key in the current context? By default this is false to emulate ctemplate's
+  # behavior, but it may be useful to enable when debugging or developing.
+  #
+  # If set to true and there is a context miss, `Mustache::ContextMiss` will
+  # be raised.
+  def self.raise_on_context_miss?
+    @raise_on_context_miss
+  end
+
+  def self.raise_on_context_miss=(boolean)
+    @raise_on_context_miss = boolean
+  end
+
   # Has this template already been compiled? Compilation is somewhat
   # expensive so it may be useful to check this before attempting it.
   def self.compiled?
@@ -178,6 +260,12 @@ class Mustache
     @template = templateify(template)
   end
 
+  # Instance level version of `Mustache.raise_on_context_miss?`
+  def raise_on_context_miss?
+    self.class.raise_on_context_miss? || @raise_on_context_miss
+  end
+  attr_writer :raise_on_context_miss
+
   # A helper method which gives access to the context at a given time.
   # Kind of a hack for now, but useful when you're in an iterating section
   # and want access to the hash currently being iterated over.

data/lib/mustache/context.rb

@@ -1,4 +1,14 @@
 class Mustache
+  # A ContextMiss is raised whenever a tag's target can not be found
+  # in the current context if `Mustache#raise_on_context_miss?` is
+  # set to true.
+  #
+  # For example, if your View class does not respond to `music` but
+  # your template contains a `{{template}}` tag this exception will be raised.
+  #
+  # By default it is not raised. See Mustache.raise_on_context_miss.
+  class ContextMiss < RuntimeError;  end
+
   # A Context represents the context which a Mustache template is
   # executed within. All Mustache tags reference keys in the Context.
   class Context < Hash
@@ -14,8 +24,10 @@ class Mustache
         super(name.to_s)
       elsif @mustache.respond_to?(name)
         @mustache.send(name)
+      elsif @mustache.raise_on_context_miss?
+        raise ContextMiss.new("Can't find #{name} in #{@mustache.inspect}")
       else
-        raise "Can't find #{name} in #{@mustache.inspect}"
+        ''
       end
     end
   end

data/lib/mustache/sinatra.rb

@@ -49,38 +49,18 @@ class Mustache
       # This is called by Sinatra's `render` with the proper paths
       # and, potentially, a block containing a sub-view
       def render_mustache(template, data, opts, locals, &block)
-        name = Mustache.classify(template.to_s)
+        # If you have Hurl::App::Views, namespace should be set to Hurl::App.
+        Mustache.view_namespace = options.namespace
 
-        # This is a horrible hack but we need it to know under which namespace
-        # Views is located. If you have Hurl::App::Views, namespace should be
-        # set to Hurl:App.
-        namespace = options.namespace
+        # This is probably the same as options.views, but we'll set it anyway.
+        # It's used to tell Mustache where to look for view classes.
+        Mustache.view_path = options.mustaches
 
-        if namespace.const_defined?(:Views) && namespace::Views.const_defined?(name)
-          # First try to find the existing view,
-          # e.g. Hurl::Views::Index
-          klass = namespace::Views.const_get(name)
+        # Grab the class!
+        klass = Mustache.view_class(template)
 
-        elsif File.exists?(file = "#{options.mustaches}/#{template}.rb")
-          # Couldn't find it - try to require the file if it exists, then
-          # load in the view.
-          require "#{file}".chomp('.rb')
-          klass = namespace::Views.const_get(name)
-
-          # compile and cache the template
-          klass.template = data
-
-        else
-          # Still nothing. Use the stache.
-          klass = Mustache
-
-        end
-
-        # Tell the view class its extension and path so finding partials
-        # works as expected.
-        if klass.template_extension != 'mustache'
-          klass.template_extension = 'mustache'
-        end
+        # Only cache the data if this isn't the generic base class.
+        klass.template = data unless klass == Mustache
 
         # Confusingly Sinatra's `views` setting tells Mustache where the
         # templates are found. It's fine, blame Chris.

data/lib/mustache/template.rb

@@ -9,9 +9,30 @@ class Mustache
   #
   # You shouldn't use this class directly.
   class Template
+    # An UnclosedSection error is thrown when a {{# section }} is not
+    # closed.
+    #
+    # For example:
+    #   {{# open }} blah {{/ close }}
+    class UnclosedSection < RuntimeError
+      attr_reader :message
+
+      # Report the line number of the offending unclosed section.
+      def initialize(source, matching_line, unclosed_section)
+        num = 0
+
+        source.split("\n").each_with_index do |line, i|
+          num = i + 1
+          break if line.strip == matching_line.strip
+        end
+
+        @message = "line #{num}: ##{unclosed_section.strip} is not closed"
+      end
+    end
+
     # Expects a Mustache template as a string along with a template
     # path, which it uses to find partials.
-    def initialize(source, template_path = '.', template_extension = 'html')
+    def initialize(source, template_path = '.', template_extension = 'mustache')
       @source = source
       @template_path = template_path
       @template_extension = template_extension
@@ -85,9 +106,13 @@ class Mustache
     # 4. Partial tags - {{< partial_name }}
     def compile_tags(src)
       res = ""
-      while src =~ /#{otag}(=|!|<|\{)?(.+?)\1?#{ctag}+/
+      while src =~ /#{otag}(#|=|!|<|\{)?(.+?)\1?#{ctag}+/
         res << str($`)
         case $1
+        when '#'
+          # Unclosed section - raise an error and
+          # report the line number
+          raise UnclosedSection.new(@source, $&, $2)
         when '!'
           # ignore comments
         when '='

data/lib/mustache/version.rb

@@ -1,3 +1,3 @@
 class Mustache
-  Version = '0.3.2'
+  Version = '0.4.0'
 end

data/lib/rack/bug/panels/mustache_panel.rb

@@ -0,0 +1,81 @@
+module Rack
+  module Bug
+    # MustachePanel is a Rack::Bug panel which tracks the time spent rendering
+    # Mustache views as well as all the variables accessed during view
+    # rendering.
+    #
+    # It can be used to track down slow partials and ensure you're only
+    # generating data you need.
+    #
+    # Also, it's fun.
+    class MustachePanel < Panel
+      require "rack/bug/panels/mustache_panel/mustache_extension"
+
+      # The view is responsible for rendering our panel. While Rack::Bug
+      # takes care of the nav, the content rendered by View is used for
+      # the panel itself.
+      class View < Mustache
+        self.path = ::File.dirname(__FILE__) + '/mustache_panel'
+
+        # We track the render times of all the Mustache views on this
+        # page load.
+        def times
+          MustachePanel.times.map do |key, value|
+            { :key => key, :value => value }
+          end
+        end
+
+        # Any variables used in this page load are collected and displayed.
+        def variables
+          vars = MustachePanel.variables.sort_by { |key, _| key.to_s }
+          vars.map do |key, value|
+            # Arrays can get too huge. Just show the first 10 to give you
+            # some idea.
+            if value.is_a?(Array) && value.size > 10
+              size = value.size
+              value = value.first(10)
+              value << "...and #{size - 10} more"
+            end
+
+            { :key => key, :value => value.inspect }
+          end
+        end
+      end
+
+      # Clear out our page load-specific variables.
+      def self.reset
+        Thread.current["rack.bug.mustache.times"] = {}
+        Thread.current["rack.bug.mustache.vars"] = {}
+      end
+
+      # The view render times for this page load
+      def self.times
+        Thread.current["rack.bug.mustache.times"] ||= {}
+      end
+
+      # The variables used on this page load
+      def self.variables
+        Thread.current["rack.bug.mustache.vars"] ||= {}
+      end
+
+      # The name of this Rack::Bug panel
+      def name
+        "mustache"
+      end
+
+      # The string used for our tab in Rack::Bug's navigation bar
+      def heading
+        "{{%.2fms}}" % self.class.times.values.inject(0.0) do |sum, obj|
+          sum + obj
+        end
+      end
+
+      # The content of our Rack::Bug panel
+      def content
+        View.render
+      ensure
+        self.class.reset
+      end
+    end
+  end
+end

data/lib/rack/bug/panels/mustache_panel/mustache_extension.rb

@@ -0,0 +1,25 @@
+if defined? Mustache
+  Mustache.class_eval do
+    alias_method :real_render, :render
+
+    def render(*args, &block)
+      out = ''
+      Rack::Bug::MustachePanel.times[self.class.name] = Benchmark.realtime do
+        out = real_render(*args, &block)
+      end
+      out
+    end
+
+    alias_method :to_html, :render
+    alias_method :to_text, :render
+  end
+
+  Mustache::Context.class_eval do
+    alias_method :real_get, :[]
+
+    def [](name)
+      return real_get(name) if name == :yield || !@mustache.respond_to?(name)
+      Rack::Bug::MustachePanel.variables[name] = real_get(name)
+    end
+  end
+end

data/lib/rack/bug/panels/mustache_panel/view.mustache

@@ -0,0 +1,32 @@
+<h3>Render Times</h3>
+
+<table>
+  <tr>
+    <th>View</th>
+    <th>Render Time</th>
+  </tr>
+
+  {{# times }}
+    <tr>
+      <td>{{ key }}</td>
+      <td>{{ value }}</td>
+    </tr>
+  {{/ times }}
+</table>
+
+<h3>Variables</h3>
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>Value</th>
+  </tr>
+
+  {{# variables }}
+    <tr>
+      <td>{{ key }}</td>
+      <td>{{ value }}</td>
+    </tr>
+  {{/ variables }}
+</table>
+

data/test/autoloading_test.rb

@@ -0,0 +1,38 @@
+require 'test/unit'
+
+module TestViews; end
+
+class AutoloadingTest < Test::Unit::TestCase
+  def setup
+    Mustache.view_path = File.dirname(__FILE__) + '/../examples'
+  end
+
+  def test_autoload
+    klass = Mustache.view_class(:Comments)
+    assert_equal Comments, klass
+  end
+
+  def test_autoload_lowercase
+    klass = Mustache.view_class(:comments)
+    assert_equal Comments, klass
+  end
+
+  def test_autoload_nil
+    klass = Mustache.view_class(nil)
+    assert_equal Mustache, klass
+  end
+
+  def test_autoload_empty_string
+    klass = Mustache.view_class('')
+    assert_equal Mustache, klass
+  end
+
+  def test_namespaced_autoload
+    Mustache.view_namespace = TestViews
+    klass = Mustache.view_class('Namespaced')
+    assert_equal TestViews::Namespaced, klass
+    assert_equal <<-end_render.strip, klass.render
+<h1>Dragon &lt; Tiger</h1>
+end_render
+  end
+end

data/test/mustache_test.rb

@@ -224,6 +224,29 @@ data
     end
   end
 
+  def test_reports_unclosed_sections
+    instance = Mustache.new
+    instance[:list] = [ :item => 1234 ]
+    instance.template = '{{#list}} <li>{{item}}</li> {{/gist}}'
+
+    assert_raise Mustache::Template::UnclosedSection do
+      instance.render
+    end
+  end
+
+  def test_unclosed_sections_reports_the_line_number
+    instance = Mustache.new
+    instance[:list] = [ :item => 1234 ]
+    instance.template = "hi\nmom\n{{#list}} <li>{{item}}</li> {{/gist}}"
+
+    begin
+      instance.render
+    rescue => e
+    end
+
+    assert e.message.include?('line 3')
+  end
+
   def test_enumerable_sections_accept_a_hash_as_a_context
     instance = Mustache.new
     instance[:list] = { :item => 1234 }
@@ -240,6 +263,31 @@ data
     assert_equal '<li>1234</li>', instance.render.strip
   end
 
+  def test_not_found_in_context_renders_empty_string
+    instance = Mustache.new
+    instance.template = '{{#list}} <li>{{item}}</li> {{/list}}'
+
+    assert_equal '', instance.render.strip
+  end
+
+  def test_not_found_in_nested_context_renders_empty_string
+    instance = Mustache.new
+    instance[:list] = { :item => 1234 }
+    instance.template = '{{#list}} <li>{{prefix}}{{item}}</li> {{/list}}'
+
+    assert_equal '<li>1234</li>', instance.render.strip
+  end
+
+  def test_not_found_in_context_raises_when_asked_to
+    instance = Mustache.new
+    instance.raise_on_context_miss = true
+    instance.template = '{{#list}} <li>{{item}}</li> {{/list}}'
+
+    assert_raises Mustache::ContextMiss do
+      instance.render.strip
+    end
+  end
+
   def test_knows_when_its_been_compiled_when_set_with_string
     klass = Class.new(Mustache)
 
@@ -250,7 +298,7 @@ data
 
   def test_knows_when_its_been_compiled_when_using_a_file_template
     klass = Class.new(Simple)
-    klass.template_file = File.dirname(__FILE__) + '/../examples/simple.html'
+    klass.template_file = File.dirname(__FILE__) + '/../examples/simple.mustache'
 
     assert ! klass.compiled?
     klass.render

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mustache
 version: !ruby/object:Gem::Version 
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors: 
 - Chris Wanstrath
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-19 00:00:00 -07:00
+date: 2009-10-27 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -36,34 +36,40 @@ files:
 - benchmarks/simple.erb
 - benchmarks/speed.rb
 - contrib/mustache.vim
-- examples/comments.html
+- examples/comments.mustache
 - examples/comments.rb
-- examples/complex_view.html
+- examples/complex_view.mustache
 - examples/complex_view.rb
-- examples/delimiters.html
+- examples/delimiters.mustache
 - examples/delimiters.rb
-- examples/double_section.html
+- examples/double_section.mustache
 - examples/double_section.rb
-- examples/escaped.html
+- examples/escaped.mustache
 - examples/escaped.rb
-- examples/inner_partial.html
+- examples/inner_partial.mustache
 - examples/inner_partial.txt
+- examples/namespaced.mustache
+- examples/namespaced.rb
 - examples/passenger.conf
 - examples/passenger.rb
-- examples/simple.html
+- examples/simple.mustache
 - examples/simple.rb
-- examples/template_partial.html
+- examples/template_partial.mustache
 - examples/template_partial.rb
 - examples/template_partial.txt
-- examples/unescaped.html
+- examples/unescaped.mustache
 - examples/unescaped.rb
-- examples/view_partial.html
+- examples/view_partial.mustache
 - examples/view_partial.rb
 - lib/mustache.rb
 - lib/mustache/context.rb
 - lib/mustache/sinatra.rb
 - lib/mustache/template.rb
 - lib/mustache/version.rb
+- lib/rack/bug/panels/mustache_panel.rb
+- lib/rack/bug/panels/mustache_panel/mustache_extension.rb
+- lib/rack/bug/panels/mustache_panel/view.mustache
+- test/autoloading_test.rb
 - test/mustache_test.rb
 has_rdoc: true
 homepage: http://github.com/defunkt/mustache
@@ -94,12 +100,14 @@ signing_key:
 specification_version: 3
 summary: Mustache is a framework-agnostic way to render logic-free views.
 test_files: 
+- test/autoloading_test.rb
 - test/mustache_test.rb
 - examples/comments.rb
 - examples/complex_view.rb
 - examples/delimiters.rb
 - examples/double_section.rb
 - examples/escaped.rb
+- examples/namespaced.rb
 - examples/passenger.rb
 - examples/simple.rb
 - examples/template_partial.rb