tilt 0.3 → 0.4

data/README.md

@@ -30,6 +30,7 @@ Support for these template engines is included with the package:
     Liquid                     .liquid           liquid
     Mustache                   .mustache         mustache
     RDiscount                  .markdown         rdiscount
+    RedCloth                   .textile          redcloth
 
 Basic Usage
 -----------

data/Rakefile

@@ -1,4 +1,5 @@
-task :default => :spec
+require 'rake/testtask'
+task :default => :test
 
 # SPECS =====================================================================
 
@@ -7,14 +8,10 @@ task :rcov do
   sh "rcov -Ilib:test test/*_test.rb"
 end
 
-desc 'Run specs with unit test style output'
-task :test do |t|
-  sh 'bacon -qa'
-end
-
-desc 'Run specs with story style output'
-task :spec do |t|
-  sh 'bacon -a'
+desc 'Run tests (default)'
+Rake::TestTask.new(:test) do |t|
+  t.test_files = FileList['test/*_test.rb']
+  t.ruby_opts = ['-rubygems'] if defined? Gem
 end
 
 # PACKAGING =================================================================

data/TEMPLATES.md

@@ -1,11 +1,28 @@
-Templates
-=========
+Tilt Templates
+==============
 
+While all Tilt templates use the same basic interface for template loading and
+evaluation, each varies in its capabilities and available options. Detailed
+documentation on each supported template engine is provided below.
+
+ * [ERB](#erb) - `Tilt::ERBTemplate`
+ * [Erubis](#erubis) - `Tilt::ErubisTemplate`
+ * [Haml](#haml) - `Tilt::HamlTemplate`
+ * [Liquid](#liquid) - `Tilt::LiquidTemplate`
+ * [Mustache](#mustache) - `Tilt::MustachTemplate`
+
+Tilt includes support for simple text formats in addition to
+programmable template languages. These typically do not support
+scope or locals but often support rendering options.
+
+ * [Markdown](#markdown) - `Tilt::RDiscountTemplate`
+ * [RDoc](#rdoc) - `Tilt::RDocTemplate`
+
+<a name='erb'></a>
 ERB (`erb`, `rhtml`)
 --------------------
 
-[Docs](http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html) |
-[Syntax](http://vision-media.ca/resources/ruby/ruby-rdoc-documentation-syntax)
+An easy to use but powerful templating system for Ruby.
 
 ### Example
 
@@ -28,9 +45,12 @@ Or, use the `Tilt::ERBTemplate` class directly to process strings:
     template = Tilt::ERBTemplate.new(nil, :trim => '<>') { "Hello <%= world %>!" }
     template.render(self, :world => 'World!')
 
+__NOTE:__ It's suggested that your program `require 'erb'` at load time when
+using this template engine within a threaded environment.
+
 ### Options
 
-`:trim => '-'`
+#### `:trim => '-'`
 
 The ERB trim mode flags. This is a string consisting
 of any combination of the following characters:
@@ -40,10 +60,351 @@ of any combination of the following characters:
   * `'-'`  omits newlines for lines ending in `-%>`.
   * `'%'`  enables processing of lines beginning with `%`
 
-`:safe => nil`
+#### `:safe => nil`
 
 The `$SAFE` level; when set, ERB code will be run in a
 separate thread with `$SAFE` set to the provided level.
 
-It's suggested that your program require 'erb' at load time when using this
-template engine.
+### See also
+
+  * [ERB documentation](http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html)
+
+
+<a name='erubis'></a>
+Erubis (`erubis`)
+-----------------
+
+Erubis is a fast, secure, and very extensible implementation of eRuby.
+
+### Usage
+
+To use Erubis instead of ERB for all `.erb` and `.rhtml` files, register
+the extensions as follows:
+
+    Tilt.register 'erb', Tilt::ErubisTemplate
+    Tilt.register 'rhtml', Tilt::ErubisTemplate
+
+### Options
+
+#### `:trim => true`
+
+Delete spaces around '<% %>'. (But, spaces around '<%= %>' are preserved.)
+
+#### `:pattern => '<% %>'`
+
+Set pattern for embedded Ruby code.
+
+See the [ERB](#erb) template documentation for examples, usage, and options.
+
+__NOTE:__ It's suggested that your program `require 'erubis'` at load time when
+using this template engine within a threaded environment.
+
+### See also
+
+  * [Erubis Home](http://www.kuwata-lab.com/erubis/)
+  * [Erubis User's Guide](http://www.kuwata-lab.com/erubis/users-guide.html)
+
+
+<a name='haml'></a>
+Haml (`haml`)
+-------------
+
+Haml is a markup language that’s used to cleanly and simply describe the HTML of
+any web document without the use of inline code. Haml functions as a replacement
+for inline page templating systems such as PHP, ASP, and ERB, the templating
+language used in most Ruby on Rails applications. However, Haml avoids the
+need for explicitly coding HTML into the template, because it itself is a
+description of the HTML, with some code to generate dynamic content.
+([more](http://haml-lang.com/about.html))
+
+
+### Example
+
+    %html
+      %head
+        %title= @title
+      %body
+        %h1
+          Hello
+          = world + '!'
+
+### Usage
+
+The `Tilt::HamlTemplate` class is registered for all files ending in `.haml`
+by default. Haml templates support custom evaluation scopes and locals:
+
+    >> require 'haml'
+    >> template = Tilt.new('hello.haml')
+    => #<Tilt::HamlTemplate @file='hello.haml'>
+    >> @title = "Hello Haml!"
+    >> template.render(self, :world => 'Haml!')
+    => "
+    <html>
+      <head>
+        <title>Hello Haml!</title>
+      </head>
+      <body>
+        <h1>Hello Haml!</h1>
+      </body>
+    </html>"
+
+Or, use the `Tilt::HamlTemplate` class directly to process strings:
+
+    >> require 'haml'
+    >> template = Tilt::HamlTemplate.new { "%h1= 'Hello Haml!'" }
+    => #<Tilt::HamlTemplate @file=nil ...>
+    >> template.render
+    => "<h1>Hello Haml!</h1>"
+
+__NOTE:__ It's suggested that your program `require 'haml'` at load time when
+using this template engine within a threaded environment.
+
+### Options
+
+#### `:format => :xhtml`
+
+Determines the output format. The default is `:xhtml`. Other options are
+`:html4` and `:html5`, which are identical to `:xhtml` except there are no
+self-closing tags, the XML prolog is ignored and correct DOCTYPEs are generated.
+
+#### `:escape_html => false`
+
+Sets whether or not to escape HTML-sensitive characters in script. If this is
+true, `=` behaves like `&=;` otherwise, it behaves like `!=`. Note that if this
+is set, `!=` should be used for yielding to subtemplates and rendering partials.
+Defaults to false.
+
+#### `:ugly => false`
+
+If set to true, Haml makes no attempt to properly indent or format the HTML
+output. This causes the rendering to be done much quicker than it would
+otherwise, but makes viewing the source unpleasant. Defaults to false.
+
+#### `:suppress_eval => false`
+
+Whether or not attribute hashes and Ruby scripts designated by `=` or `~` should
+be evaluated. If this is true, said scripts are rendered as empty strings.
+Defaults to false.
+
+#### `:attr_wrapper => "'"`
+
+The character that should wrap element attributes. This defaults to `'` (an
+apostrophe). Characters of this type within the attributes will be escaped (e.g.
+by replacing them with `&apos;`) if the character is an apostrophe or a
+quotation mark.
+
+#### `:autoclose => %w[meta img link br hr input area param col base]`
+
+A list of tag names that should be automatically self-closed if they have no
+content. Defaults to `['meta', 'img', 'link', 'br', 'hr', 'input', 'area',
+'param', 'col', 'base']`.
+
+#### `:preserve => %w[textarea pre]`
+
+A list of tag names that should automatically have their newlines preserved
+using the `Haml::Helpers#preserve` helper. This means that any content given on
+the same line as the tag will be preserved. For example, `%textarea= "Foo\nBar"`
+compiles to `<textarea>Foo&#x000A;Bar</textarea>`. Defaults to `['textarea',
+'pre']`.
+
+#### `:encoding => 'utf-8'`
+
+The encoding to use for the HTML output. Only available in Ruby 1.9 or higher.
+This can be a string or an Encoding Object. Note that Haml does not
+automatically re-encode Ruby values; any strings coming from outside the
+application should be converted before being passed into the Haml template.
+Defaults to `Encoding.default_internal` or, if that's not set, `"utf-8"`.
+
+### See also
+
+  * [#haml.docs](http://haml-lang.com/docs.html)
+  * [Haml Tutorial](http://haml-lang.com/tutorial.html)
+  * [Haml Reference](http://haml-lang.com/docs/yardoc/HAML_REFERENCE.md.html)
+  * [Whitespace Preservation](http://haml-lang.com/docs/yardoc/HAML_REFERENCE.md.html#whitespace_preservation)
+
+
+<a name='liquid'></a>
+Liquid (`liquid`)
+-----------------
+
+Liquid is for rendering safe templates which cannot affect the security
+of the server they are rendered on.
+
+### Example
+
+    <html>
+      <head>
+        <title>{{ title }}</title>
+      </head>
+      <body>
+        <h1>Hello {{ world }}!</h1>
+      </body>
+    </html>
+
+### Usage
+
+`Tilt::LiquidTemplate` is registered for all files ending in `.liquid` by
+default. Liquid templates support locals and objects that respond to
+`#to_h` as scopes:
+
+    >> require 'liquid'
+    >> require 'tilt'
+    >> template = Tilt.new('hello.liquid')
+    => #<Tilt::LiquidTemplate @file='hello.liquid'>
+    >> scope = { :title => "Hello Liquid Templates" }
+    >> template.render(nil, :world => "Liquid")
+    => "
+    <html>
+      <head>
+        <title>Hello Liquid Templates</title>
+      </head>
+      <body>
+        <h1>Hello Liquid!</h1>
+      </body>
+    </html>"
+
+Or, use `Tilt::LiquidTemplate` directly to process strings:
+
+    >> require 'haml'
+    >> template = Tilt::HamlTemplate.new { "<h1>Hello Liquid!</h1>" }
+    => #<Tilt::LiquidTemplate @file=nil ...>
+    >> template.render
+    => "<h1>Hello Liquid!</h1>"
+
+__NOTE:__ It's suggested that your program `require 'liquid'` at load
+time when using this template engine within a threaded environment.
+
+### See also
+
+  * [Liquid for Programmers](http://wiki.github.com/tobi/liquid/liquid-for-programmers)
+  * [Liquid Docs](http://liquid.rubyforge.org/)
+  * GitHub: [tobi/liquid](http://github.com/tobi/liquid/)
+
+<a name='mustache'></a>
+Mustache (`mustache`)
+---------------------
+
+Mustache is a framework-agnostic way to render logic-free views.
+
+__NOTE:__ It's suggested that your program `require 'mustache'` at load time
+when using this template engine in a threaded environment.
+
+### Options
+
+#### `:path => Dir.pwd`
+
+The base path where mustache templates (`.html` files) are located.  Defaults to
+the current working directory.
+
+#### `:template_extension => 'html'`
+
+The file extension used on mustache templates. Default is `'html'`.
+
+#### `:namespace => Object`
+
+The class or module where View classes are located. If you have
+`Hurl::App::Views`, namespace should be `Hurl:App`. This defaults to `Object`,
+causing `::Views` to be searched for classes.
+
+#### `:mustaches => nil`
+
+Where mustache views (.rb files) are located, or nil to disable auto-requiring
+of views based on template names. By default, the view file is assumed to be in
+the same directory as the template file.
+
+All other options are assumed to be attribute writer's on the Mustache
+class and are set when a template is compiled. They are:
+
+#### `:view => nil`
+
+The Mustache subclass that should be used a the view. When this option is
+specified, the template file will be determined from the view class, and the
+`:namespace` and `:mustaches` options are irrelevant.
+
+### See also
+
+  * [Mustache Docs](http://defunkt.github.com/mustache/)
+  * GitHub: [defunkt/mustache](http://github.com/defunkt/mustache)
+
+
+<a name='markdown'></a>
+Markdown (`markdown`, `md`, `mkd`)
+----------------------------------
+
+Markdown is a lightweight markup language, created by John Gruber and
+Aaron Swartz. For any markup that is not covered by Markdown’s syntax,
+HTML is used.  Marking up plain text with Markdown markup is easy and
+Markdown formatted texts are readable.
+
+Markdown formatted texts are converted to HTML with the [RDiscount][]
+engine, which is a Ruby extension over the fast [Discount][] C library.
+
+### Example
+
+    Hello Markdown Templates
+    ========================
+
+    Hello World. This is a paragraph.
+
+### Usage
+
+To wrap a Markdown formatted document with a layout:
+
+    require 'erubis'
+    require 'rdiscount'
+    layout = Tilt::ErubisTemplate.new(nil, :pattern => '\{% %\}') do
+        "<!doctype html><title></title>{%= yield %}"
+    end
+    data = Tilt::RDiscountTemplate.new { "# hello tilt" }
+    layout.render { data.render }
+    # => "<!doctype html><title></title><h1>hello tilt</h1>\n"
+
+__NOTE:__ It's suggested that your program `require 'mustache'` at load time
+when using this template engine in a threaded environment.
+
+### Options
+
+RDiscount supports a variety of flags that control its behavior:
+
+#### `:smart => true|false`
+
+Set `true` to enable [Smarty Pants](http://daringfireball.net/projects/smartypants/)
+style punctuation replacement.
+
+#### `:filter_html => true|false`
+
+Set `true` disallow raw HTML in Markdown contents. HTML is converted to
+literal text by escaping `<` characters.
+
+### See also
+
+ * [Markdown Syntax Documentation][markdown syntax]
+ * GitHub: [rtomayko/rdiscount][rdiscount]
+
+[discount]: http://www.pell.portland.or.us/~orc/Code/discount/ "Discount"
+[rdiscount]: http://github.com/rtomayko/rdiscount/ "RDiscount"
+[markdown syntax]: (http://daringfireball.net/projects/markdown/syntax/) "Markdown Syntax"
+
+
+<a name='rdoc'></a>
+RDoc (`rdoc`)
+-------------
+
+RDoc is the simple text markup system that comes with Ruby's standard
+library.
+
+### Usage
+
+__NOTE:__ It's suggested that your program `require 'rdoc/markup'` and
+`require 'rdoc/markup/to_html'` at load time when using this template
+engine in a threaded environment.
+
+### Example
+
+    = Hello RDoc Templates
+
+    Hello World. This is a paragraph.
+
+### See also
+
+ * [RDoc](http://rdoc.sourceforge.net/doc/index.html)

data/lib/tilt.rb

@@ -1,5 +1,5 @@
 module Tilt
-  VERSION = '0.3'
+  VERSION = '0.4'
 
   @template_mappings = {}
 
@@ -44,6 +44,7 @@ module Tilt
     end
   end
 
+
   # Base class for template implementations. Subclasses must implement
   # the #compile! method and one of the #evaluate or #template_source
   # methods.
@@ -66,6 +67,9 @@ module Tilt
     # default, template data is read from the file specified. When a block
     # is given, it should read template data and return as a String. When
     # file is nil, a block is required.
+    #
+    # The #initialize_engine method is called if this is the very first
+    # time this template subclass has been initialized.
     def initialize(file=nil, line=1, options={}, &block)
       raise ArgumentError, "file or block required" if file.nil? && block.nil?
       options, line = line, 1 if line.is_a?(Hash)
@@ -73,7 +77,21 @@ module Tilt
       @line = line || 1
       @options = options || {}
       @reader = block || lambda { |t| File.read(file) }
+
+      if !self.class.engine_initialized
+        initialize_engine
+        self.class.engine_initialized = true
+      end
+    end
+
+    # Called once and only once for each template subclass the first time
+    # the template class is initialized. This should be used to require the
+    # underlying template library and perform any initial setup.
+    def initialize_engine
     end
+    @engine_initialized = false
+    class << self ; attr_accessor :engine_initialized ; end
+
 
     # Load template source and compile the template. The template is
     # loaded and compiled the first time this method is called; subsequent
@@ -149,14 +167,19 @@ module Tilt
     end
   end
 
-  # Extremely simple template cache implementation.
+  # Extremely simple template cache implementation. Calling applications
+  # create a Tilt::Cache instance and use #fetch with any set of hashable
+  # arguments (such as those to Tilt.new):
+  #   cache = Tilt::Cache.new
+  #   cache.fetch(path, line, options) { Tilt.new(path, line, options) }
+  #
+  # Subsequent invocations return the already compiled template object.
   class Cache
     def initialize
       @cache = {}
     end
 
     def fetch(*key)
-      key = key.map { |part| part.to_s }.join(":")
       @cache[key] ||= yield
     end
 
@@ -165,8 +188,10 @@ module Tilt
     end
   end
 
+
   # Template Implementations ================================================
 
+
   # The template source is evaluated as a Ruby string. The #{} interpolation
   # syntax can be used to generated dynamic output.
   class StringTemplate < Template
@@ -180,14 +205,15 @@ module Tilt
   end
   register 'str', StringTemplate
 
+
   # ERB template implementation. See:
   # http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html
-  #
-  # It's suggested that your program require 'erb' at load
-  # time when using this template engine.
   class ERBTemplate < Template
+    def initialize_engine
+      require_template_library 'erb' unless defined? ::ERB
+    end
+
     def compile!
-      require_template_library 'erb' unless defined?(::ERB)
       @engine = ::ERB.new(data, options[:safe], options[:trim], '@_out_buf')
     end
 
@@ -224,28 +250,41 @@ module Tilt
   end
   %w[erb rhtml].each { |ext| register ext, ERBTemplate }
 
+
   # Erubis template implementation. See:
   # http://www.kuwata-lab.com/erubis/
-  #
-  # It's suggested that your program require 'erubis' at load
-  # time when using this template engine.
   class ErubisTemplate < ERBTemplate
+    def initialize_engine
+      require_template_library 'erubis' unless defined? ::Erubis
+    end
+
     def compile!
-      require_template_library 'erubis' unless defined?(::Erubis)
       Erubis::Eruby.class_eval(%Q{def add_preamble(src) src << "@_out_buf = _buf = '';" end})
-      @engine = ::Erubis::Eruby.new(data)
+      @engine = ::Erubis::Eruby.new(data, options)
+    end
+
+  private
+
+    # Erubis doesn't have ERB's line-off-by-one under 1.9 problem. Override
+    # and adjust back.
+    if RUBY_VERSION >= '1.9.0'
+      def local_assignment_code(locals)
+        source, offset = super
+        [source, offset - 1]
+      end
     end
   end
   register 'erubis', ErubisTemplate
 
+
   # Haml template implementation. See:
   # http://haml.hamptoncatlin.com/
-  #
-  # It's suggested that your program require 'haml' at load
-  # time when using this template engine.
   class HamlTemplate < Template
+    def initialize_engine
+      require_template_library 'haml' unless defined? ::Haml::Engine
+    end
+
     def compile!
-      require_template_library 'haml' unless defined?(::Haml::Engine)
       @engine = ::Haml::Engine.new(data, haml_options)
     end
 
@@ -260,16 +299,17 @@ module Tilt
   end
   register 'haml', HamlTemplate
 
+
   # Sass template implementation. See:
   # http://haml.hamptoncatlin.com/
   #
   # Sass templates do not support object scopes, locals, or yield.
-  #
-  # It's suggested that your program require 'sass' at load
-  # time when using this template engine.
   class SassTemplate < Template
+    def initialize_engine
+      require_template_library 'sass' unless defined? ::Sass::Engine
+    end
+
     def compile!
-      require_template_library 'sass' unless defined?(::Sass::Engine)
       @engine = ::Sass::Engine.new(data, sass_options)
     end
 
@@ -284,16 +324,17 @@ module Tilt
   end
   register 'sass', SassTemplate
 
+
   # Builder template implementation. See:
   # http://builder.rubyforge.org/
-  #
-  # It's suggested that your program require 'builder' at load
-  # time when using this template engine.
   class BuilderTemplate < Template
-    def compile!
+    def initialize_engine
       require_template_library 'builder' unless defined?(::Builder)
     end
 
+    def compile!
+    end
+
     def evaluate(scope, locals, &block)
       xml = ::Builder::XmlMarkup.new(:indent => 2)
       if data.respond_to?(:to_str)
@@ -311,31 +352,61 @@ module Tilt
   end
   register 'builder', BuilderTemplate
 
+
   # Liquid template implementation. See:
   # http://liquid.rubyforge.org/
   #
-  # LiquidTemplate does not support scopes or yield blocks.
+  # Liquid is designed to be a *safe* template system and threfore
+  # does not provide direct access to execuatable scopes. In order to
+  # support a +scope+, the +scope+ must be able to represent itself
+  # as a hash by responding to #to_h. If the +scope+ does not respond
+  # to #to_h it will be ignored.
+  #
+  # LiquidTemplate does not support yield blocks.
   #
   # It's suggested that your program require 'liquid' at load
   # time when using this template engine.
   class LiquidTemplate < Template
+    def initialize_engine
+      require_template_library 'liquid' unless defined? ::Liquid::Template
+    end
+
     def compile!
-      require_template_library 'liquid' unless defined?(::Liquid::Template)
       @engine = ::Liquid::Template.parse(data)
     end
 
     def evaluate(scope, locals, &block)
-      locals = locals.inject({}) { |hash,(k,v)| hash[k.to_s] = v ; hash }
+      locals = locals.inject({}){ |h,(k,v)| h[k.to_s] = v ; h }
+      if scope.respond_to?(:to_h)
+        scope  = scope.to_h.inject({}){ |h,(k,v)| h[k.to_s] = v ; h }
+        locals = scope.merge(locals)
+      end
+      # TODO: Is it possible to lazy yield ?
+      locals['yield'] = block.nil? ? '' : yield
+      locals['content'] = block.nil? ? '' : yield
       @engine.render(locals)
     end
   end
   register 'liquid', LiquidTemplate
 
-  # Discount Markdown implementation.
+
+  # Discount Markdown implementation. See:
+  # http://github.com/rtomayko/rdiscount
+  #
+  # RDiscount is a simple text filter. It does not support +scope+ or
+  # +locals+. The +:smart+ and +:filter_html+ options may be set true
+  # to enable those flags on the underlying RDiscount object.
   class RDiscountTemplate < Template
+    def flags
+      [:smart, :filter_html].select { |flag| options[flag] }
+    end
+
+    def initialize_engine
+      require_template_library 'rdiscount' unless defined? ::RDiscount
+    end
+
     def compile!
-      require_template_library 'rdiscount' unless defined?(::RDiscount)
-      @engine = RDiscount.new(data)
+      @engine = RDiscount.new(data, *flags)
     end
 
     def evaluate(scope, locals, &block)
@@ -343,66 +414,44 @@ module Tilt
     end
   end
   register 'markdown', RDiscountTemplate
+  register 'mkd', RDiscountTemplate
   register 'md', RDiscountTemplate
 
+
+# RedCloth implementation. See:
+# http://redcloth.org/
+class RedClothTemplate < Template
+  def initialize_engine
+    require_template_library 'redcloth' unless defined? ::RedCloth
+  end
+
+  def compile!
+    @engine = RedCloth.new(data)
+  end
+
+  def evaluate(scope, locals, &block)
+    @engine.to_html
+  end
+end
+register 'textile', RedClothTemplate
+
+
   # Mustache is written and maintained by Chris Wanstrath. See:
   # http://github.com/defunkt/mustache
   #
-  # It's suggested that your program require 'mustache' at load
-  # time when using this template engine.
-  #
-  # Mustache templates support the following options:
-  #
-  # * :view - The Mustache subclass that should be used a the view. When
-  #   this option is specified, the template file will be determined from
-  #   the view class, and the :namespace and :mustaches options are
-  #   irrelevant.
-  #
-  # * :namespace - The class or module where View classes are located.
-  #   If you have Hurl::App::Views, namespace should be Hurl:App. This
-  #   defaults to Object, causing ::Views to be searched for classes.
-  #
-  # * :mustaches - Where mustache views (.rb files) are located, or nil
-  #   disable auto-requiring of views based on template names. By default,
-  #   the view file is assumed to be in the same directory as the template
-  #   file.
-  #
-  # All other options are assumed to be attribute writer's on the Mustache
-  # class and are set when a template is compiled. They are:
-  #
-  # * :path - The base path where mustache templates (.html files) are
-  #   located. This defaults to the current working directory.
-  #
-  # * :template_extension - The file extension used on mustache templates.
-  #   The default is 'html'.
-  #
+  # When a scope argument is provided to MustacheTemplate#render, the
+  # instance variables are copied from the scope object to the Mustache
+  # view.
   class MustacheTemplate < Template
     attr_reader :engine
 
-    # Locates and compiles the Mustache object used to create new views. The
-    def compile!
-      require_template_library 'mustache' unless defined?(::Mustache)
-
-      @view_name = Mustache.classify(name.to_s)
-      @namespace = options[:namespace] || Object
-
-      # Figure out which Mustache class to use.
-      @engine =
-        if options[:view]
-          @view_name = options[:view].name
-          options[:view]
-        elsif @namespace.const_defined?(:Views) &&
-          @namespace::Views.const_defined?(@view_name)
-          @namespace::Views.const_get(@view_name)
-        elsif load_mustache_view
-          engine = @namespace::Views.const_get(@view_name)
-          engine.template = data
-          engine
-        else
-          Mustache
-        end
+    def initialize_engine
+      require_template_library 'mustache' unless defined? ::Mustache
+    end
 
-      # set options on the view class
+    def compile!
+      Mustache.view_namespace = options[:namespace]
+      @engine = options[:view] || Mustache.view_class(name)
       options.each do |key, value|
         next if %w[view namespace mustaches].include?(key.to_s)
         @engine.send("#{key}=", value) if @engine.respond_to? "#{key}="
@@ -410,20 +459,19 @@ module Tilt
     end
 
     def evaluate(scope=nil, locals={}, &block)
-      # Create a new instance for playing with
       instance = @engine.new
 
-      # Copy instance variables from scope to the view
+      # copy instance variables from scope to the view
       scope.instance_variables.each do |name|
         instance.instance_variable_set(name, scope.instance_variable_get(name))
       end
 
-      # Locals get added to the view's context
+      # locals get added to the view's context
       locals.each do |local, value|
         instance[local] = value
       end
 
-      # If we're passed a block it's a subview. Sticking it in yield
+      # if we're passed a block it's a subview. Sticking it in yield
       # lets us use {{yield}} in layout.html to render the actual page.
       instance[:yield] = block.call if block
 
@@ -431,19 +479,31 @@ module Tilt
 
       instance.to_html
     end
+  end
+  register 'mustache', MustacheTemplate
 
-    # Require the mustache view lib if it exists.
-    def load_mustache_view
-      return if name.nil?
-      path = "#{options[:mustaches]}/#{name}.rb"
-      if options[:mustaches] && File.exist?(path)
-        require path.chomp('.rb')
-        path
-      elsif File.exist?(path = file.sub(/\.[^\/]+$/, '.rb'))
-        require path.chomp('.rb')
-        path
+  # RDoc template. See:
+  # http://rdoc.rubyforge.org/
+  #
+  # It's suggested that your program require 'rdoc/markup' and
+  # 'rdoc/markup/to_html' at load time when using this template
+  # engine.
+  class RDocTemplate < Template
+    def initialize_engine
+      unless defined?(::RDoc::Markup)
+        require_template_library 'rdoc/markup'
+        require_template_library 'rdoc/markup/to_html'
       end
     end
+
+    def compile!
+      markup = RDoc::Markup::ToHtml.new
+      @engine = markup.convert(data)
+    end
+
+    def evaluate(scope, locals, &block)
+      @engine.to_s
+    end
   end
-  register 'mustache', MustacheTemplate
+  register 'rdoc', RDocTemplate
 end