tilt 1.4.1 → 2.0.0

data/lib/tilt/template.rb

@@ -1,5 +1,11 @@
+require 'tilt'
+require 'thread'
+
 module Tilt
+  # @private
   TOPOBJECT = Object.superclass || Object
+  # @private
+  LOCK = Mutex.new
 
   # Base class for template implementations. Subclasses must implement
   # the #prepare method and one of the #evaluate or #precompiled_template
@@ -19,14 +25,22 @@ module Tilt
     # interface.
     attr_reader :options
 
-    # Used to determine if this class's initialize_engine method has
-    # been called yet.
-    @engine_initialized = false
     class << self
-      attr_accessor :engine_initialized
-      alias engine_initialized? engine_initialized
+      # An empty Hash that the template engine can populate with various
+      # metadata.
+      def metadata
+        @metadata ||= {}
+      end
 
-      attr_accessor :default_mime_type
+      # @deprecated Use `.metadata[:mime_type]` instead.
+      def default_mime_type
+        metadata[:mime_type]
+      end
+
+      # @deprecated Use `.metadata[:mime_type] = val` instead.
+      def default_mime_type=(value)
+        metadata[:mime_type] = value
+      end
     end
 
     # Create a new template with the file, line, and options specified. By
@@ -44,19 +58,14 @@ module Tilt
         when arg.respond_to?(:to_int)  ; @line = arg.to_int
         when arg.respond_to?(:to_hash) ; @options = arg.to_hash.dup
         when arg.respond_to?(:path)    ; @file = arg.path
-        else raise TypeError
+        when arg.respond_to?(:to_path) ; @file = arg.to_path
+        else raise TypeError, "Can't load the template file. Pass a string with a path " +
+          "or an object that responds to 'to_str', 'path' or 'to_path'"
         end
       end
 
       raise ArgumentError, "file or block required" if (@file || block).nil?
 
-      # call the initialize_engine method if this is the very first time
-      # an instance of this class has been created.
-      if !self.class.engine_initialized?
-        initialize_engine
-        self.class.engine_initialized = true
-      end
-
       # used to hold compiled template methods
       @compiled_method = {}
 
@@ -79,28 +88,15 @@ module Tilt
       prepare
     end
 
-    # The encoding of the source data. Defaults to the
-    # default_encoding-option if present. You may override this method
-    # in your template class if you have a better hint of the data's
-    # encoding.
-    def default_encoding
-      @default_encoding
-    end
-
-    def read_template_file
-      data = File.open(file, 'rb') { |io| io.read }
-      if data.respond_to?(:force_encoding)
-        # Set it to the default external (without verifying)
-        data.force_encoding(Encoding.default_external) if Encoding.default_external
-      end
-      data
-    end
-
     # Render the template in the given scope with the locals specified. If a
     # block is given, it is typically available within the template via
     # +yield+.
     def render(scope=Object.new, locals={}, &block)
-      evaluate scope, locals || {}, &block
+      current_template = Thread.current[:tilt_current_template]
+      Thread.current[:tilt_current_template] = self
+      evaluate(scope, locals || {}, &block)
+    ensure
+      Thread.current[:tilt_current_template] = current_template
     end
 
     # The basename of the template file.
@@ -118,30 +114,26 @@ module Tilt
       file || '(__TEMPLATE__)'
     end
 
-    # Whether or not this template engine allows executing Ruby script
-    # within the template. If this is false, +scope+ and +locals+ will
-    # generally not be used, nor will the provided block be avaiable 
-    # via +yield+.
-    # This should be overridden by template subclasses.
-    def allows_script?
-      true
+    # An empty Hash that the template engine can populate with various
+    # metadata.
+    def metadata
+      if respond_to?(:allows_script?)
+        self.class.metadata.merge(:allows_script => allows_script?)
+      else
+        self.class.metadata
+      end
     end
 
-  protected
-    # 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
+    protected
 
-    # Like Kernel#require but issues a warning urging a manual require when
-    # running under a threaded environment.
-    def require_template_library(name)
-      if Thread.list.size > 1
-        warn "WARN: tilt autoloading '#{name}' in a non thread-safe way; " +
-             "explicit require '#{name}' suggested."
-      end
-      require name
+    # @!group For template implementations
+
+    # The encoding of the source data. Defaults to the
+    # default_encoding-option if present. You may override this method
+    # in your template class if you have a better hint of the data's
+    # encoding.
+    def default_encoding
+      @default_encoding
     end
 
     # Do whatever preparation is necessary to setup the underlying template
@@ -150,13 +142,7 @@ module Tilt
     #
     # Subclasses must provide an implementation of this method.
     def prepare
-      if respond_to?(:compile!)
-        # backward compat with tilt < 0.6; just in case
-        warn 'Tilt::Template#compile! is deprecated; implement #prepare instead.'
-        compile!
-      else
-        raise NotImplementedError
-      end
+      raise NotImplementedError
     end
 
     # Execute the compiled template and return the result string. Template
@@ -179,10 +165,10 @@ module Tilt
     # control over source generation or want to adjust the default line
     # offset. In most cases, overriding the #precompiled_template method is
     # easier and more appropriate.
-    def precompiled(locals)
-      preamble = precompiled_preamble(locals)
-      template = precompiled_template(locals)
-      postamble = precompiled_postamble(locals)
+    def precompiled(local_keys)
+      preamble = precompiled_preamble(local_keys)
+      template = precompiled_template(local_keys)
+      postamble = precompiled_postamble(local_keys)
       source = ''
 
       # Ensure that our generated source code has the same encoding as the
@@ -194,10 +180,7 @@ module Tilt
         template.force_encoding(template_encoding)
       end
 
-      # https://github.com/rtomayko/tilt/issues/193
-      warn "precompiled_preamble should return String (not Array)" if preamble.is_a?(Array)
-      warn "precompiled_postamble should return String (not Array)" if postamble.is_a?(Array)
-      source << [preamble, template, postamble].join("\n")
+      source << preamble << "\n" << template << "\n" << postamble
 
       [source, preamble.count("\n")+1]
     end
@@ -208,41 +191,52 @@ module Tilt
     # the base Template guarantees correct file/line handling, locals
     # support, custom scopes, proper encoding, and support for template
     # compilation.
-    def precompiled_template(locals)
+    def precompiled_template(local_keys)
       raise NotImplementedError
     end
 
-    # Generates preamble code for initializing template state, and performing
-    # locals assignment. The default implementation performs locals
-    # assignment only. Lines included in the preamble are subtracted from the
-    # source line offset, so adding code to the preamble does not effect line
-    # reporting in Kernel::caller and backtraces.
-    def precompiled_preamble(locals)
-      locals.map do |k,v|
-        if k.to_s =~ /\A[a-z_][a-zA-Z_0-9]*\z/
-          "#{k} = locals[#{k.inspect}]"
-        else
-          raise "invalid locals key: #{k.inspect} (keys must be variable names)"
-        end
-      end.join("\n")
+    def precompiled_preamble(local_keys)
+      ''
     end
 
-    # Generates postamble code for the precompiled template source. The
-    # string returned from this method is appended to the precompiled
-    # template source.
-    def precompiled_postamble(locals)
+    def precompiled_postamble(local_keys)
       ''
     end
 
+    # !@endgroup
+
+    private
+
+    def read_template_file
+      data = File.open(file, 'rb') { |io| io.read }
+      if data.respond_to?(:force_encoding)
+        # Set it to the default external (without verifying)
+        data.force_encoding(Encoding.default_external) if Encoding.default_external
+      end
+      data
+    end
+
     # The compiled method for the locals keys provided.
     def compiled_method(locals_keys)
-      @compiled_method[locals_keys] ||=
-        compile_template_method(locals_keys)
+      LOCK.synchronize do
+        @compiled_method[locals_keys] ||= compile_template_method(locals_keys)
+      end
+    end
+
+    def local_extraction(local_keys)
+      local_keys.map do |k|
+        if k.to_s =~ /\A[a-z_][a-zA-Z_0-9]*\z/
+          "#{k} = locals[#{k.inspect}]"
+        else
+          raise "invalid locals key: #{k.inspect} (keys must be variable names)"
+        end
+      end.join("\n")
     end
 
-  private
-    def compile_template_method(locals)
-      source, offset = precompiled(locals)
+    def compile_template_method(local_keys)
+      source, offset = precompiled(local_keys)
+      local_code = local_extraction(local_keys)
+
       method_name = "__tilt_#{Thread.current.object_id.abs}"
       method_source = ""
 
@@ -257,11 +251,12 @@ module Tilt
             class << self
               this, locals = Thread.current[:tilt_vars]
               this.instance_eval do
+                #{local_code}
       RUBY
       offset += method_source.count("\n")
       method_source << source
       method_source << "\nend;end;end;end"
-      Object.class_eval method_source, eval_file, line - offset
+      Object.class_eval(method_source, eval_file, line - offset)
       unbind_compiled_method(method_name)
     end
 
@@ -276,7 +271,7 @@ module Tilt
     end
 
     def extract_magic_comment(script)
-      binary script do
+      binary(script) do
         script[/\A[ \t]*\#.*coding\s*[=:]\s*([[:alnum:]\-_]+).*$/n, 1]
       end
     end

data/lib/tilt/wikicloth.rb

@@ -0,0 +1,22 @@
+require 'tilt/template'
+require 'wikicloth'
+
+module Tilt
+  # WikiCloth implementation. See:
+  # http://redcloth.org/
+  class WikiClothTemplate < Template
+    def prepare
+      @parser = options.delete(:parser) || WikiCloth::Parser
+      @engine = @parser.new options.merge(:data => data)
+      @output = nil
+    end
+
+    def evaluate(scope, locals, &block)
+      @output ||= @engine.to_html
+    end
+
+    def allows_script?
+      false
+    end
+  end
+end

data/lib/tilt/yajl.rb

@@ -1,4 +1,5 @@
 require 'tilt/template'
+require 'yajl'
 
 module Tilt
 
@@ -42,14 +43,6 @@ module Tilt
 
     self.default_mime_type = 'application/json'
 
-    def self.engine_initialized?
-      defined? ::Yajl
-    end
-
-    def initialize_engine
-      require_template_library 'yajl'
-    end
-
     def prepare
     end
 

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'
 
-  @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,41 @@ 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'
+  register_lazy 'Tilt::HandlebarsTemplate',  'tilt/handlebars', 'handlebars', 'hbs'
+  register_lazy 'Tilt::OrgTemplate',         'org-ruby',        'org'
 end

data/test/{contest.rb → test_helper.rb}

@@ -1,21 +1,17 @@
-require "test/unit"
+$LOAD_PATH << File.expand_path('../../lib', __FILE__)
 
-# Test::Unit loads a default test if the suite is empty, whose purpose is to
-# fail. Since having empty contexts is a common practice, we decided to
-# overwrite TestSuite#empty? in order to allow them. Having a failure when no
-# tests have been defined seems counter-intuitive.
-class Test::Unit::TestSuite
-  def empty?
-    false
-  end
-end
+require 'bundler'
+Bundler.setup
+
+require 'minitest/autorun'
+require 'minitest/mock'
 
 # Contest adds +teardown+, +test+ and +context+ as class methods, and the
 # instance methods +setup+ and +teardown+ now iterate on the corresponding
 # blocks. Note that all setup and teardown blocks must be defined with the
 # block syntax. Adding setup or teardown instance methods defeats the purpose
 # of this library.
-class Test::Unit::TestCase
+class Minitest::Test
   def self.setup(&block)
     define_method :setup do
       super(&block)