tilt 1.4.1 → 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f43cb3f1357b1eeb55d129fed314692c5c053322
+  data.tar.gz: 63ba1cd6367f652f75c968a479530ae6830dc663
+SHA512:
+  metadata.gz: 2a30fa65c04fe76bb58af64df4d1940272507d765b942eea1433ad070f0f924566f0c5b3569700dd50f947fc9c6bafe634a46c77279c42e4ac22ee8133e7adcf
+  data.tar.gz: eca0811f6a72525467c766996191feb3c0bc59b533dbe91831379e7ba3142b4010f37452b232d52145431e66391c3c0a858c0457a8dbe98bd857e1cbc7e0a015

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## master
 
+* Add Handlebars as external template engine (#204, judofyr, jimothyGator)
+* Add org-ruby as external template engine (#207, judofyr, minad)
+* Documentation typo (#208, elgalu)
+
+## 2.0.0.beta1 (2013-07-16)
+
+* Documentation typo (#202, chip)
+* Use YARD for documentation (#189, judofyr)
+* Add Slim as an external template engine (judofyr)
+* Add Tilt.templates_for (#121, judofyr)
+* Add Tilt.current_template (#151, judofyr)
+* Avoid loading all files in tilt.rb (#160, #187, judofyr)
+* Implement lazily required templates classes (#178, #187, judofyr)
+* Move #allows_script and default_mime_type to metadata (#187, judofyr)
+* Introduce Tilt::Mapping (#187, judofyr)
+* Make template compilation thread-safe (#191, judofyr)
+
 ## 1.4.1 (2013-05-08)
 
 * Support Arrays in pre/postambles (#193, jbwiv)

data/Gemfile

@@ -1,32 +1,39 @@
 source "http://rubygems.org"
 
+gem 'yard', '~> 0.8.6'
+gem 'minitest', '~> 5.0'
+
 gem 'rake'
-gem 'asciidoctor', '>= 0.1.0'
-gem 'builder'
-gem 'coffee-script'
-gem 'contest'
-gem 'creole'
-gem 'erubis'
-gem 'haml', '>= 2.2.11', '< 4'
-gem 'kramdown'
-gem 'less'
-gem 'liquid'
-gem 'markaby'
-gem 'maruku'
-gem 'nokogiri'
-gem 'radius'
-gem 'sass'
-gem 'wikicloth'
-gem 'rdoc', (ENV['RDOC_VERSION'] || '> 0')
 
-platform :ruby do
-  gem 'yajl-ruby'
-  gem 'redcarpet'
-  gem 'rdiscount' if RUBY_VERSION != '1.9.2'
-  gem 'RedCloth'
-end
+group :engines do
+  gem 'asciidoctor', '>= 0.1.0'
+  gem 'builder'
+  gem 'coffee-script'
+  gem 'contest'
+  gem 'creole'
+  gem 'erubis'
+  gem 'haml', '>= 2.2.11', '< 4'
+  gem 'kramdown'
+  gem 'less'
+  gem 'liquid'
+  gem 'markaby'
+  gem 'maruku'
+  gem 'nokogiri' if RUBY_VERSION > '1.9.2'
+  gem 'radius'
+  gem 'sass'
+  gem 'wikicloth'
+  gem 'rdoc', (ENV['RDOC_VERSION'] || '> 0')
 
-platform :mri do
-  gem 'therubyracer'
-  gem 'bluecloth'
+  platform :ruby do
+    gem 'yajl-ruby'
+    gem 'redcarpet' if RUBY_VERSION > '1.8.7'
+    gem 'rdiscount', '>= 2.1.6' if RUBY_VERSION != '1.9.2'
+    gem 'RedCloth'
+  end
+
+  platform :mri do
+    gem 'therubyracer'
+    gem 'bluecloth' if ENV['BLUECLOTH']
+  end
 end
+

data/README.md

@@ -1,8 +1,11 @@
 Tilt [![Build Status](https://secure.travis-ci.org/rtomayko/tilt.png)](http://travis-ci.org/rtomayko/tilt) [![Dependency Status](https://gemnasium.com/rtomayko/tilt.png)](https://gemnasium.com/rtomayko/tilt)
 ====
 
+**NOTE** The follow file documents the upcoming release of Tilt (2.0). See
+https://github.com/rtomayko/tilt/tree/tilt-1 for the current version.
+
 Tilt is a thin interface over a bunch of different Ruby template engines in
-an attempt to make their usage as generic possible. This is useful for web
+an attempt to make their usage as generic as possible. This is useful for web
 frameworks, static site generators, and other systems that support multiple
 template engines but don't want to code for each of them individually.
 
@@ -58,11 +61,12 @@ These template engines ship with their own Tilt integration:
     Embedded CoffeeScript                        sprockets
     JST                                          sprockets
     Org-mode                   .org              org-ruby (>= 0.6.2)
+    Handlebars                 .hbs, .handlebars tilt-handlebars
 
 See [TEMPLATES.md][t] for detailed information on template engine
 options and supported features.
 
-[t]: http://github.com/rtomayko/tilt/blob/master/TEMPLATES.md
+[t]: http://github.com/rtomayko/tilt/blob/master/docs/TEMPLATES.md
    "Tilt Template Engine Documentation"
 
 Basic Usage
@@ -82,12 +86,13 @@ libraries (like 'erb' above) at load time. Tilt attempts to lazy require the
 template engine library the first time a template is created but this is
 prone to error in threaded environments.
 
-The `Tilt` module contains generic implementation classes for all supported
+The {Tilt} module contains generic implementation classes for all supported
 template engines. Each template class adheres to the same interface for
 creation and rendering. In the instant gratification example, we let Tilt
 determine the template implementation class based on the filename, but
-`Tilt::Template` implementations can also be used directly:
+{Tilt::Template} implementations can also be used directly:
 
+    require 'tilt/haml'
     template = Tilt::HamlTemplate.new('templates/foo.haml')
     output = template.render
 
@@ -95,6 +100,7 @@ The `render` method takes an optional evaluation scope and locals hash
 arguments. Here, the template is evaluated within the context of the
 `Person` object with locals `x` and `y`:
 
+    require 'tilt/erb'
     template = Tilt::ERBTemplate.new('templates/foo.erb')
     joe = Person.find('joe')
     output = template.render(joe, :x => 35, :y => 42)
@@ -124,11 +130,14 @@ The block passed to `render` is called on `yield`:
 Template Mappings
 -----------------
 
-The `Tilt` module includes methods for associating template implementation
-classes with filename patterns and for locating/instantiating template
-classes based on those associations.
+The {Tilt::Mapping} class includes methods for associating template
+implementation classes with filename patterns and for locating/instantiating
+template classes based on those associations.
+
+The {Tilt} module has a global instance of `Mapping` that is populated with the
+table of template engines above.
 
-The `Tilt::register` method associates a filename pattern with a specific
+The {Tilt.register} method associates a filename pattern with a specific
 template implementation. To use ERB for files ending in a `.bar` extension:
 
      >> Tilt.register Tilt::ERBTemplate, 'bar'
@@ -142,15 +151,12 @@ Retrieving the template class for a file or file extension:
      >> Tilt['haml']
      => Tilt::HamlTemplate
 
-It's also possible to register template file mappings that are more specific
-than a file extension. To use Erubis for `bar.erb` but ERB for all other `.erb`
-files:
+Retrieving a list of template classes for a file:
 
-     >> Tilt.register Tilt::ErubisTemplate, 'bar.erb'
-     >> Tilt.new('views/foo.erb')
-     => Tilt::ERBTemplate
-     >> Tilt.new('views/bar.erb')
-     => Tilt::ErubisTemplate
+    >> Tilt.templates_for('foo.bar')
+    => [Tilt::ERBTemplate]
+    >> Tilt.templates_for('foo.haml.bar')
+    => [Tilt::ERBTemplate, Tilt::HamlTemplate]
 
 The template class is determined by searching for a series of decreasingly
 specific name patterns. When creating a new template with
@@ -162,38 +168,6 @@ mappings:
   3. `html.erb`
   4. `erb`
 
-### Fallback mode
-
-If there are more than one template class registered for a file extension, Tilt
-will automatically try to load the version that works on your machine:
-
-  1. If any of the template engines has been loaded already: Use that one.
-  2. If not, it will try to initialize each of the classes with an empty template.
-  3. Tilt will use the first that doesn't raise an exception.
-  4. If however *all* of them failed, Tilt will raise the exception of the first
-     template engine, since that was the most preferred one.
-
-Template classes that were registered *last* would be tried first. Because the
-Markdown extensions are registered like this:
-
-    Tilt.register Tilt::BlueClothTemplate, 'md'
-    Tilt.register Tilt::RDiscountTemplate, 'md'
-
-Tilt will first try RDiscount and then BlueCloth. You could say that RDiscount
-has a *higher priority* than BlueCloth.
-
-The fallback mode works nicely when you just need to render an ERB or Markdown
-template, but if you depend on a specific implementation, you should use #prefer:
-
-    # Prefer BlueCloth for all its registered extensions (markdown, mkd, md)
-    Tilt.prefer Tilt::BlueClothTemplate
-
-    # Prefer Erubis for .erb only:
-    Tilt.prefer Tilt::ErubisTemplate, 'erb'
-
-When a file extension has a preferred template class, Tilt will *always* use
-that class, even if it raises an exception.
-
 Encodings
 ---------
 
@@ -213,7 +187,7 @@ tmpl = Tilt.new('hello.erb', :default_encoding => 'Big5')
 
 Ultimately it's up to the template engine how to handle the encoding: It might
 respect `:default_encoding`, it might always assume it's UTF-8 (like
-CoffeScript), or it can do its own encoding detection.
+CoffeeScript), or it can do its own encoding detection.
 
 Template Compilation
 --------------------

data/Rakefile

@@ -1,43 +1,34 @@
-require 'rbconfig'
-require 'rake/testtask'
-task :default => [:setup, :test]
-
-# set GEM_HOME to use local ./vendor dir for tests
-vendor_dir = './vendor'
-ruby_version = RbConfig::CONFIG['ruby_version']
-ruby_engine = (defined?(RUBY_ENGINE) && RUBY_ENGINE) || 'ruby'
-gem_home = ENV['GEM_HOME'] = "#{vendor_dir}/#{ruby_engine}/#{ruby_version}"
-
-# Write the current version.
-task :version do
-  puts "#{ruby_engine} #{RUBY_VERSION} (#{gem_home})"
-end
+require 'bundler'
+Bundler.setup
 
-desc "Install gems to #{ENV['GEM_HOME']}"
-task :setup do
-  verbose false do
-    sh "
-      bundle check >/dev/null || {
-        echo 'Updating #{gem_home}' &&
-        bundle install --path='#{vendor_dir}'; }
-    "
-  end
-end
+require 'rake/testtask'
+task :default => [:test]
 
 # SPECS =====================================================================
 
-desc 'Generate test coverage report'
-task :rcov do
-  sh "rcov -Ilib:test test/*_test.rb"
-end
-
 desc 'Run tests (default)'
 Rake::TestTask.new(:test) do |t|
   t.test_files = FileList['test/*_test.rb']
   t.ruby_opts = ['-Itest']
   t.ruby_opts << '-rubygems' if defined? Gem
 end
-task :test => :version
+
+# DOCUMENTATION =============================================================
+
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files = [
+    'lib/tilt.rb', 'lib/tilt/mapping.rb', 'lib/tilt/template.rb',
+    '-',
+    '*.md', 'docs/*.md',
+  ]
+
+  t.options <<
+    '--no-private' <<
+    '--protected' <<
+    '-m' << 'markdown' <<
+    '--asset' << 'docs/common.css:css/common.css'
+end
 
 # PACKAGING =================================================================
 

data/{TEMPLATES.md → docs/TEMPLATES.md}

@@ -1,7 +1,7 @@
 Tilt Templates
 ==============
 
-(See <https://github.com/rtomayko/tilt/blob/master/TEMPLATES.md> for a rendered,
+(See <https://github.com/rtomayko/tilt/blob/master/docs/TEMPLATES.md> for a rendered,
 HTML-version of this file).
 
 While all Tilt templates use the same basic interface for template loading and
@@ -457,18 +457,24 @@ To wrap a Markdown formatted document with a layout:
 ### Options
 
 Every implementation of Markdown *should* support these options, but there are
-some known problems with the Kramdown and Maruku engines.
+some known problems with the Kramdown and Maruku engines. 
 
 #### `:smartypants => true|false`
 
-Set `true` to enable [Smarty Pants][smartypants]
-style punctuation replacement.
+Set `true` to enable [Smarty Pants][smartypants] style punctuation replacement.
+
+In Kramdown this option only applies to smart quotes. It will apply a
+subset of Smarty Pants (e.g. `...` to `…`) regardless of any option.
+
+Maruku ignores this option and always applies smart quotes (and nothing else).
 
 #### `:escape_html => true|false`
 
 Set `true` disallow raw HTML in Markdown contents. HTML is converted to
 literal text by escaping `<` characters.
 
+Kramdown and Maruku doesn't support this option.
+
 ### See also
 
  * [Markdown Syntax Documentation](http://daringfireball.net/projects/markdown/syntax/)
@@ -513,4 +519,5 @@ using this template engine within a threaded environment.
 [discount]: http://www.pell.portland.or.us/~orc/Code/discount/ "Discount"
 [rdiscount]: http://github.com/rtomayko/rdiscount/ "RDiscount"
 [smartypants]: http://daringfireball.net/projects/smartypants/ "Smarty Pants"
+[markdown]: http://en.wikipedia.org/wiki/Markdown "Markdown"
 

data/docs/common.css

@@ -0,0 +1,14 @@
+body {
+  line-height: 1.5;
+  font-size: 14px;
+}
+
+.frames #content {
+  margin: 0;
+}
+
+#content {
+  margin: 0 auto;
+  max-width: 720px;
+}
+

data/lib/tilt/asciidoc.rb

@@ -1,4 +1,5 @@
 require 'tilt/template'
+require 'asciidoctor'
 
 # AsciiDoc see: http://asciidoc.org/
 module Tilt
@@ -11,14 +12,6 @@ module Tilt
   class AsciidoctorTemplate < Template
     self.default_mime_type = 'text/html'
 
-    def self.engine_initialized?
-      defined? ::Asciidoctor::Document
-    end
-
-    def initialize_engine
-      require_template_library 'asciidoctor'
-    end
-
     def prepare
       options[:header_footer] = false if options[:header_footer].nil?
     end

data/lib/tilt/bluecloth.rb

@@ -0,0 +1,24 @@
+require 'tilt/template'
+require 'bluecloth'
+
+module Tilt
+  # BlueCloth Markdown implementation. See:
+  # http://deveiate.org/projects/BlueCloth/
+  class BlueClothTemplate < Template
+    self.default_mime_type = 'text/html'
+
+    def prepare
+      @engine = BlueCloth.new(data, options)
+      @output = nil
+    end
+
+    def evaluate(scope, locals, &block)
+      @output ||= @engine.to_html
+    end
+
+    def allows_script?
+      false
+    end
+  end
+end
+

data/lib/tilt/builder.rb

@@ -1,4 +1,5 @@
 require 'tilt/template'
+require 'builder'
 
 module Tilt
    # Builder template implementation. See:
@@ -6,14 +7,6 @@ module Tilt
   class BuilderTemplate < Template
     self.default_mime_type = 'text/xml'
 
-    def self.engine_initialized?
-      defined? ::Builder
-    end
-
-    def initialize_engine
-      require_template_library 'builder'
-    end
-
     def prepare; end
 
     def evaluate(scope, locals, &block)

data/lib/tilt/coffee.rb

@@ -1,4 +1,5 @@
 require 'tilt/template'
+require 'coffee_script'
 
 module Tilt
   # CoffeeScript template implementation. See:
@@ -28,14 +29,6 @@ module Tilt
       @@default_bare = value
     end
 
-    def self.engine_initialized?
-      defined? ::CoffeeScript
-    end
-
-    def initialize_engine
-      require_template_library 'coffee_script'
-    end
-
     def prepare
       if !options.key?(:bare) and !options.key?(:no_wrap)
         options[:bare] = self.class.default_bare

data/lib/tilt/creole.rb

@@ -0,0 +1,25 @@
+require 'tilt/template'
+require 'creole'
+
+module Tilt
+  # Creole implementation. See:
+  # http://www.wikicreole.org/
+  class CreoleTemplate < Template
+    def prepare
+      opts = {}
+      [:allowed_schemes, :extensions, :no_escape].each do |k|
+        opts[k] = options[k] if options[k]
+      end
+      @engine = Creole::Parser.new(data, opts)
+      @output = nil
+    end
+
+    def evaluate(scope, locals, &block)
+      @output ||= @engine.to_html
+    end
+
+    def allows_script?
+      false
+    end
+  end
+end

data/lib/tilt/csv.rb

@@ -1,5 +1,11 @@
 require 'tilt/template'
 
+if RUBY_VERSION >= '1.9.0'
+  require 'csv'
+else
+  require 'fastercsv'
+end
+
 module Tilt
 
   # CSV Template implementation. See:
@@ -30,10 +36,6 @@ module Tilt
   class CSVTemplate < Template
     self.default_mime_type = 'text/csv'
 
-    def self.engine_initialized?
-      engine
-    end
-
     def self.engine
       if RUBY_VERSION >= '1.9.0' && defined? ::CSV
         ::CSV
@@ -42,14 +44,6 @@ module Tilt
       end
     end
 
-    def initialize_engine
-      if RUBY_VERSION >= '1.9.0'
-        require_template_library 'csv'
-      else
-        require_template_library 'fastercsv'
-      end
-    end
-
     def prepare
       @code =<<-RUBY
         #{self.class.engine}.generate do |csv|
@@ -68,4 +62,4 @@ module Tilt
     end
 
   end
-end
+end

data/lib/tilt/erb.rb

@@ -1,4 +1,5 @@
 require 'tilt/template'
+require 'erb'
 
 module Tilt
   # ERB template implementation. See:
@@ -11,17 +12,10 @@ module Tilt
     end
 
     def self.default_output_variable=(name)
+      warn "#{self}.default_output_variable= has been replaced with the :outvar-option"
       @@default_output_variable = name
     end
 
-    def self.engine_initialized?
-      defined? ::ERB
-    end
-
-    def initialize_engine
-      require_template_library 'erb'
-    end
-
     def prepare
       @outvar = options[:outvar] || self.class.default_output_variable
       options[:trim] = '<>' if !(options[:trim] == false) && (options[:trim].nil? || options[:trim] == true)
@@ -59,52 +53,5 @@ module Tilt
       end
     end
   end
-
-  # Erubis template implementation. See:
-  # http://www.kuwata-lab.com/erubis/
-  #
-  # ErubisTemplate supports the following additional options, which are not
-  # passed down to the Erubis engine:
-  #
-  #   :engine_class   allows you to specify a custom engine class to use
-  #                   instead of the default (which is ::Erubis::Eruby).
-  #
-  #   :escape_html    when true, ::Erubis::EscapedEruby will be used as
-  #                   the engine class instead of the default. All content
-  #                   within <%= %> blocks will be automatically html escaped.
-  class ErubisTemplate < ERBTemplate
-    def self.engine_initialized?
-      defined? ::Erubis::Eruby
-    end
-
-    def initialize_engine
-      require_template_library 'erubis'
-    end
-
-    def prepare
-      @outvar = options.delete(:outvar) || self.class.default_output_variable
-      @options.merge!(:preamble => false, :postamble => false, :bufvar => @outvar)
-      engine_class = options.delete(:engine_class)
-      engine_class = ::Erubis::EscapedEruby if options.delete(:escape_html)
-      @engine = (engine_class || ::Erubis::Eruby).new(data, options)
-    end
-
-    def precompiled_preamble(locals)
-      [super, "#{@outvar} = _buf = ''"].join("\n")
-    end
-
-    def precompiled_postamble(locals)
-      [@outvar, super].join("\n")
-    end
-
-    # 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 precompiled(locals)
-        source, offset = super
-        [source, offset - 1]
-      end
-    end
-  end
 end
 

data/lib/tilt/erubis.rb

@@ -0,0 +1,43 @@
+require 'tilt/erb'
+require 'erubis'
+
+module Tilt
+  # Erubis template implementation. See:
+  # http://www.kuwata-lab.com/erubis/
+  #
+  # ErubisTemplate supports the following additional options, which are not
+  # passed down to the Erubis engine:
+  #
+  #   :engine_class   allows you to specify a custom engine class to use
+  #                   instead of the default (which is ::Erubis::Eruby).
+  #
+  #   :escape_html    when true, ::Erubis::EscapedEruby will be used as
+  #                   the engine class instead of the default. All content
+  #                   within <%= %> blocks will be automatically html escaped.
+  class ErubisTemplate < ERBTemplate
+    def prepare
+      @outvar = options.delete(:outvar) || self.class.default_output_variable
+      @options.merge!(:preamble => false, :postamble => false, :bufvar => @outvar)
+      engine_class = options.delete(:engine_class)
+      engine_class = ::Erubis::EscapedEruby if options.delete(:escape_html)
+      @engine = (engine_class || ::Erubis::Eruby).new(data, options)
+    end
+
+    def precompiled_preamble(locals)
+      [super, "#{@outvar} = _buf = ''"].join("\n")
+    end
+
+    def precompiled_postamble(locals)
+      [@outvar, super].join("\n")
+    end
+
+    # 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 precompiled(locals)
+        source, offset = super
+        [source, offset - 1]
+      end
+    end
+  end
+end

data/lib/tilt/haml.rb

@@ -1,4 +1,5 @@
 require 'tilt/template'
+require 'haml'
 
 module Tilt
   # Haml template implementation. See:
@@ -6,14 +7,6 @@ module Tilt
   class HamlTemplate < Template
     self.default_mime_type = 'text/html'
 
-    def self.engine_initialized?
-      defined? ::Haml::Engine
-    end
-
-    def initialize_engine
-      require_template_library 'haml'
-    end
-
     def prepare
       options = @options.merge(:filename => eval_file, :line => line)
       @engine = ::Haml::Engine.new(data, options)