tilt 1.4.1 → 2.0.0.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 61afe68e016ac0b7857c8dab1c753683f432cbc1
+  data.tar.gz: f530866bbe789257559be15b56224a0f568acc03
+SHA512:
+  metadata.gz: aaa94daebb4a6407c68a1487ffdb51b575bf732d4971dcbcae5efdf38e6f906a86947af15059a6480ed9d06885248f30d3f5bcda061e48f8313b90e69c7a0df6
+  data.tar.gz: ae9c268c9c14dc3187714374f8008a8f8b982f5075dcf709aede679fef26de0702e9d48f242d196aa9d194b3a2513f439f1719503a76c4761c78d7e1e0f24df1

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## master
 
+* 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'
+  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'
+    gem 'rdiscount' if RUBY_VERSION != '1.9.2'
+    gem 'RedCloth'
+  end
+
+  platform :mri do
+    gem 'therubyracer'
+    gem 'bluecloth'
+  end
 end
+

data/README.md

@@ -1,6 +1,9 @@
 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
 frameworks, static site generators, and other systems that support multiple
@@ -62,7 +65,7 @@ These template engines ship with their own Tilt integration:
 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 +85,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 +99,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 +129,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 +150,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 +167,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 +186,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/)

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.rb

@@ -1,121 +1,81 @@
+require 'tilt/mapping'
+require 'tilt/template'
+
+# Namespace for Tilt. This module is not intended to be included anywhere.
 module Tilt
-  VERSION = '1.4.1'
+  # Current version.
+  VERSION = '2.0.0.beta1'
 
-  @preferred_mappings = Hash.new
-  @template_mappings = Hash.new { |h, k| h[k] = [] }
+  @default_mapping = Mapping.new
 
-  # Hash of template path pattern => template implementation class mappings.
-  def self.mappings
-    @template_mappings
+  # @return [Tilt::Mapping] the main mapping object
+  def self.default_mapping
+    @default_mapping
   end
 
-  def self.normalize(ext)
-    ext.to_s.downcase.sub(/^\./, '')
+  # @private
+  def self.lazy_map
+    default_mapping.lazy_map
   end
 
-  # Register a template implementation by file extension.
+  # @see Tilt::Mapping#register
   def self.register(template_class, *extensions)
-    if template_class.respond_to?(:to_str)
-      # Support register(ext, template_class) too
-      extensions, template_class = [template_class], extensions[0]
-    end
+    default_mapping.register(template_class, *extensions)
+  end
 
-    extensions.each do |ext|
-      ext = normalize(ext)
-      mappings[ext].unshift(template_class).uniq!
-    end
+  # @see Tilt::Mapping#register_lazy
+  def self.register_lazy(class_name, file, *extensions)
+    default_mapping.register_lazy(class_name, file, *extensions)
   end
 
-  # Makes a template class preferred for the given file extensions. If you
-  # don't provide any extensions, it will be preferred for all its already
-  # registered extensions:
-  #
-  #   # Prefer RDiscount for its registered file extensions:
-  #   Tilt.prefer(Tilt::RDiscountTemplate)
-  #
-  #   # Prefer RDiscount only for the .md extensions:
-  #   Tilt.prefer(Tilt::RDiscountTemplate, '.md')
+  # @deprecated Use {register} instead.
   def self.prefer(template_class, *extensions)
-    if extensions.empty?
-      mappings.each do |ext, klasses|
-        @preferred_mappings[ext] = template_class if klasses.include? template_class
-      end
-    else
-      extensions.each do |ext|
-        ext = normalize(ext)
-        register(template_class, ext)
-        @preferred_mappings[ext] = template_class
-      end
-    end
+    register(template_class, *extensions)
   end
 
-  # Returns true when a template exists on an exact match of the provided file extension
+  # @see Tilt::Mapping#registered?
   def self.registered?(ext)
-    mappings.key?(ext.downcase) && !mappings[ext.downcase].empty?
+    default_mapping.registered?(ext)
   end
 
-  # Create a new template for the given file using the file's extension
-  # to determine the the template mapping.
+  # @see Tilt::Mapping#new
   def self.new(file, line=nil, options={}, &block)
-    if template_class = self[file]
-      template_class.new(file, line, options, &block)
-    else
-      fail "No template engine registered for #{File.basename(file)}"
-    end
+    default_mapping.new(file, line, options, &block)
   end
 
-  # Lookup a template class for the given filename or file
-  # extension. Return nil when no implementation is found.
+  # @see Tilt::Mapping#[]
   def self.[](file)
-    pattern = file.to_s.downcase
-    until pattern.empty? || registered?(pattern)
-      pattern = File.basename(pattern)
-      pattern.sub!(/^[^.]*\.?/, '')
-    end
-
-    # Try to find a preferred engine.
-    preferred_klass = @preferred_mappings[pattern]
-    return preferred_klass if preferred_klass
-
-    # Fall back to the general list of mappings.
-    klasses = @template_mappings[pattern]
-
-    # Try to find an engine which is already loaded.
-    template = klasses.detect do |klass|
-      if klass.respond_to?(:engine_initialized?)
-        klass.engine_initialized?
-      end
-    end
+    default_mapping[file]
+  end
 
-    return template if template
-
-    # Try each of the classes until one succeeds. If all of them fails,
-    # we'll raise the error of the first class.
-    first_failure = nil
-
-    klasses.each do |klass|
-      begin
-        klass.new { '' }
-      rescue Exception => ex
-        first_failure ||= ex
-        next
-      else
-        return klass
-      end
-    end
+  # @see Tilt::Mapping#template_for
+  def self.template_for(file)
+    default_mapping.template_for(file)
+  end
 
-    raise first_failure if first_failure
+  # @see Tilt::Mapping#templates_for
+  def self.templates_for(file)
+    default_mapping.templates_for(file)
   end
 
-  # Deprecated module.
-  module CompileSite
+  # @return the template object that is currently rendering.
+  #
+  # @example
+  #   tmpl = Tilt['index.erb'].new { '<%= Tilt.current_template %>' }
+  #   tmpl.render == tmpl.to_s
+  #
+  # @note This is currently an experimental feature and might return nil
+  #   in the future.
+  def self.current_template
+    Thread.current[:tilt_current_template]
   end
 
   # 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) }
+  #
+  #     cache = Tilt::Cache.new
+  #     cache.fetch(path, line, options) { Tilt.new(path, line, options) }
   #
   # Subsequent invocations return the already loaded template object.
   class Cache
@@ -123,10 +83,12 @@ module Tilt
       @cache = {}
     end
 
+    # @see Cache
     def fetch(*key)
       @cache[key] ||= yield
     end
 
+    # Clears the cache.
     def clear
       @cache = {}
     end
@@ -135,70 +97,39 @@ module Tilt
 
   # Template Implementations ================================================
 
-  require 'tilt/string'
-  register StringTemplate, 'str'
-
-  require 'tilt/erb'
-  register ERBTemplate,    'erb', 'rhtml'
-  register ErubisTemplate, 'erb', 'rhtml', 'erubis'
-
-  require 'tilt/etanni'
-  register EtanniTemplate, 'etn', 'etanni'
-
-  require 'tilt/haml'
-  register HamlTemplate,   'haml'
-
-  require 'tilt/css'
-  register SassTemplate, 'sass'
-  register ScssTemplate, 'scss'
-  register LessTemplate, 'less'
-
-  require 'tilt/csv'
-  register CSVTemplate, 'rcsv'
-
-  require 'tilt/coffee'
-  register CoffeeScriptTemplate, 'coffee'
-
-  require 'tilt/nokogiri'
-  register NokogiriTemplate, 'nokogiri'
-
-  require 'tilt/builder'
-  register BuilderTemplate,  'builder'
-
-  require 'tilt/markaby'
-  register MarkabyTemplate,  'mab'
-
-  require 'tilt/liquid'
-  register LiquidTemplate, 'liquid'
-
-  require 'tilt/radius'
-  register RadiusTemplate, 'radius'
-
-  require 'tilt/markdown'
-  register MarukuTemplate,    'markdown', 'mkd', 'md'
-  register KramdownTemplate,  'markdown', 'mkd', 'md'
-  register BlueClothTemplate, 'markdown', 'mkd', 'md'
-  register RDiscountTemplate, 'markdown', 'mkd', 'md'
-  register RedcarpetTemplate::Redcarpet1, 'markdown', 'mkd', 'md'
-  register RedcarpetTemplate::Redcarpet2, 'markdown', 'mkd', 'md'
-  register RedcarpetTemplate, 'markdown', 'mkd', 'md'
-
-  require 'tilt/textile'
-  register RedClothTemplate, 'textile'
-
-  require 'tilt/rdoc'
-  register RDocTemplate, 'rdoc'
-
-  require 'tilt/wiki'
-  register CreoleTemplate,    'wiki', 'creole'
-  register WikiClothTemplate, 'wiki', 'mediawiki', 'mw'
-
-  require 'tilt/yajl'
-  register YajlTemplate, 'yajl'
-
-  require 'tilt/asciidoc'
-  register AsciidoctorTemplate, 'ad', 'adoc', 'asciidoc'
-
-  require 'tilt/plain'
-  register PlainTemplate, 'html'
+  # ERB
+  register_lazy :ERBTemplate,    'tilt/erb',    'erb', 'rhtml'
+  register_lazy :ErubisTemplate, 'tilt/erubis', 'erb', 'rhtml', 'erubis'
+
+  # Markdown
+  register_lazy :BlueClothTemplate,  'tilt/bluecloth', 'markdown', 'mkd', 'md'
+  register_lazy :MarukuTemplate,     'tilt/maruku',    'markdown', 'mkd', 'md'
+  register_lazy :KramdownTemplate,   'tilt/kramdown',  'markdown', 'mkd', 'md'
+  register_lazy :RDiscountTemplate,  'tilt/rdiscount', 'markdown', 'mkd', 'md'
+  register_lazy :RedcarpetTemplate,  'tilt/redcarpet', 'markdown', 'mkd', 'md'
+
+  # Rest (sorted by name)
+  register_lazy :AsciidoctorTemplate,  'tilt/asciidoc',  'ad', 'adoc', 'asciidoc'
+  register_lazy :BuilderTemplate,      'tilt/builder',   'builder'
+  register_lazy :CSVTemplate,          'tilt/csv',       'rcsv'
+  register_lazy :CoffeeScriptTemplate, 'tilt/coffee',    'coffee'
+  register_lazy :CreoleTemplate,       'tilt/creole',    'wiki', 'creole'
+  register_lazy :EtanniTemplate,       'tilt/etanni',    'etn', 'etanni'
+  register_lazy :HamlTemplate,         'tilt/haml',      'haml'
+  register_lazy :LessTemplate,         'tilt/less',      'less'
+  register_lazy :LiquidTemplate,       'tilt/liquid',    'liquid'
+  register_lazy :MarkabyTemplate,      'tilt/markaby',   'mab'
+  register_lazy :NokogiriTemplate,     'tilt/nokogiri',  'nokogiri'
+  register_lazy :PlainTemplate,        'tilt/plain',     'html'
+  register_lazy :RDocTemplate,         'tilt/rdoc',      'rdoc'
+  register_lazy :RadiusTemplate,       'tilt/radius',    'radius'
+  register_lazy :RedClothTemplate,     'tilt/redcloth',  'textile'
+  register_lazy :SassTemplate,         'tilt/sass',      'sass'
+  register_lazy :ScssTemplate,         'tilt/sass',      'scss'
+  register_lazy :StringTemplate,       'tilt/string',    'str'
+  register_lazy :WikiClothTemplate,    'tilt/wikicloth', 'wiki', 'mediawiki', 'mw'
+  register_lazy :YajlTemplate,         'tilt/yajl',      'yajl'
+
+  # External template engines
+  register_lazy 'Slim::Template',      'slim',           'slim'
 end