tilt 2.4.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9bb9bafc29e9442fed0bf862fb442ea6efaa97c2881b7b958361f0ef7095aaa
-  data.tar.gz: f25db1d4c05ef3b20c5fabefa4eb664e702f51f8d9821b0c44f5f5404ade4c3b
+  metadata.gz: 950d868674b6de4ce7773935b2b9fd07c16528089320eaf0b3ab49be456cdf71
+  data.tar.gz: 720b39e51f933872fca6d768bb161ab08b96afeeafce3af69cbf81fa44a6ff58
 SHA512:
-  metadata.gz: dc69e05565c5b007fbaaddc7636d6298fc9930c42d1e029834b752236309d97024132118bb723817c5c192cad1f1cef01e278ce4fc46629dac706d0ec4fdd6a2
-  data.tar.gz: 702e18b78c3e9b21e1abe86671bbe6f2427db44b05be4941c1693f30070f1de028af5324294d693bdeda130da603ecfd5c98dcefbce7ca21f7e7f6df5a249b97
+  metadata.gz: 85b22c88b5bc0f0b546336e80af4329760939d3cdf1777568774e09e894a4de92c3abce170f6f9e694997291782551ef3f285e732d2054680605bbb150e17adb
+  data.tar.gz: 86c570a4eb2c7e85169eea86be5607e8257aa8594dc50737f928e901ea9966634f452dc0c24b11baa836e86c201e55c20d6946df5a9c8ee40fe547feb573f4c0

data/lib/tilt/creole.rb

@@ -2,6 +2,8 @@
 require_relative 'template'
 require 'creole'
 
+warn 'tilt/creole is deprecated, as creole requires modifying string literals', uplevel: 1
+
 allowed_opts = [:allowed_schemes, :extensions, :no_escape].freeze
 
 # Creole implementation. See: http://www.wikicreole.org/

data/lib/tilt/liquid.rb

@@ -13,9 +13,6 @@ module Tilt
   # 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 prepare
       @options[:line_numbers] = true unless @options.has_key?(:line_numbers)

data/lib/tilt/mapping.rb

@@ -113,14 +113,14 @@ module Tilt
   # the exception of the first, since that was the most preferred one.
   #
   #     mapping = Tilt::Mapping.new
-  #     mapping.register_lazy('Maruku::Template', 'maruku/template', 'md')
+  #     mapping.register_lazy('Kramdown::Template', 'kramdown/template', 'md')
   #     mapping.register_lazy('RDiscount::Template', 'rdiscount/template', 'md')
   #     mapping['index.md']
   #     # => RDiscount::Template
   #
   # In the previous example we say that RDiscount has a *higher priority* than
-  # Maruku. Tilt will first try to `require "rdiscount/template"`, falling
-  # back to `require "maruku/template"`. If none of these are successful,
+  # Kramdown. Tilt will first try to `require "rdiscount/template"`, falling
+  # back to `require "kramdown/template"`. If none of these are successful,
   # the first error will be raised.
   class Mapping < BaseMapping
     LOCK = Mutex.new

data/lib/tilt/rdoc.rb

@@ -6,14 +6,6 @@ require 'rdoc/markup/to_html'
 require 'rdoc/options'
 
 # RDoc template. See: https://github.com/ruby/rdoc
-#
-# It's suggested that your program run the following at load time when
-# using this templae engine in a threaded environment:
-#
-#   require 'rdoc'
-#   require 'rdoc/markup'
-#   require 'rdoc/markup/to_html'
-#   require 'rdoc/options'
 Tilt::RDocTemplate = Tilt::StaticTemplate.subclass do
   RDoc::Markup::ToHtml.new(RDoc::Options.new, nil).convert(@data).to_s
 end

data/lib/tilt/template.rb

@@ -57,7 +57,28 @@ module Tilt
     # it should read template data and return as a String. When file is nil,
     # a block is required.
     #
-    # All arguments are optional.
+    # All arguments are optional. The following options are respected and
+    # are used by Tilt::Template itself and not the underlying template
+    # libraries:
+    #
+    # :default_encoding :: Force the encoding of the template to the given
+    #                      encoding.
+    # :skip_compiled_encoding_detection :: Do not scan template code for
+    #                                      an encoding magic comment.
+    # :fixed_locals :: Force a specific method parameter signature, and call
+    #                  the method with a splat of locals, instead of passing
+    #                  the locals hash as a positional argument, and
+    #                  extracting locals from that. Should be a string
+    #                  containing the parameters for the compiled method,
+    #                  surrounded by parentheses.  Can be set to false to
+    #                  disable the scan for embedded fixed locals.
+    # :extract_fixed_locals :: Whether embedded fixed locals should be scanned for
+    #                          and extracted from the template code.
+    # :default_fixed_locals :: Similar to fixed_locals, but lowest priority,
+    #                          only used if :fixed_locals is not provided
+    #                          and no embedded locals are found (or scanned for).
+    # :scope_class :: Force the scope class used for the method.  By default,
+    #                 uses the class of the scope provided to render.
     def initialize(file=nil, line=nil, options=nil)
       @file, @line, @options = nil, 1, nil
 
@@ -69,7 +90,9 @@ module Tilt
 
       @options ||= {}
 
-      set_compiled_method_cache
+      # Force a specific scope class, instead of using the class of the provided
+      # scope as the scope class.
+      @scope_class = @options.delete :scope_class
 
       # Force the encoding of the input data
       @default_encoding = @options.delete :default_encoding
@@ -78,12 +101,19 @@ module Tilt
       # for compiled templates
       @skip_compiled_encoding_detection = @options.delete :skip_compiled_encoding_detection
 
+      # Compiled path to use.  This must be specified as an option if
+      # providing the :scope_class option and using fixed locals,
+      # since template compilation occurs during initialization in that case.
+      if compiled_path = @options.delete(:compiled_path)
+        self.compiled_path = compiled_path
+      end
+
       # load template data and prepare (uses binread to avoid encoding issues)
       @data = block_given? ? yield(self) : read_template_file
 
       if @data.respond_to?(:force_encoding)
         if default_encoding
-          @data = @data.dup if @data.frozen?
+          @data = _dup_string_if_frozen(@data)
           @data.force_encoding(default_encoding)
         end
 
@@ -92,7 +122,9 @@ module Tilt
         end
       end
 
+      set_fixed_locals
       prepare
+      set_compiled_method_cache
     end
 
     # Render the template in the given scope with the locals specified. If a
@@ -119,6 +151,11 @@ module Tilt
       @file || '(__TEMPLATE__)'
     end
 
+    # Whether the template uses fixed locals.
+    def fixed_locals?
+      @fixed_locals ? true : false
+    end
+
     # An empty Hash that the template engine can populate with various
     # metadata.
     def metadata
@@ -129,7 +166,14 @@ module Tilt
       end
     end
 
-    # Set the prefix to use for compiled paths.
+    # Set the prefix to use for compiled paths, similar to using the
+    # :compiled_path template option. Note that this only
+    # has affect for future template compilations.  When using the
+    # :scope_class template option, and using fixed_locals, calling
+    # this after the template is created has no effect, since the
+    # template is compiled during initialization in that case. It
+    # is recommended to use the :compiled_path template option
+    # instead of this method in new code.
     def compiled_path=(path)
       if path
         # Use expanded paths when loading, since that is helpful
@@ -145,7 +189,18 @@ module Tilt
     # directly on the scope class, which are much faster to call than
     # Tilt's normal rendering.
     def compiled_method(locals_keys, scope_class=nil)
-      key = [scope_class, locals_keys].freeze
+      if @fixed_locals
+        if @scope_class
+          return @compiled_method
+        else
+          key = scope_class
+        end
+      elsif @scope_class
+        key = locals_keys.dup.freeze
+      else
+        key = [scope_class, locals_keys].freeze
+      end
+
       LOCK.synchronize do
         if meth = @compiled_method[key]
           return meth
@@ -181,7 +236,7 @@ module Tilt
     end
 
     CLASS_METHOD = Kernel.instance_method(:class)
-    USE_BIND_CALL = RUBY_VERSION >= '2.7'
+    USE_BIND_CALL = RUBY_VERSION >= '3'
 
     # Execute the compiled template and return the result string. Template
     # evaluation is guaranteed to be performed in the scope object with the
@@ -190,26 +245,25 @@ module Tilt
     # This method is only used by source generating templates. Subclasses that
     # override render() may not support all features.
     def evaluate(scope, locals, &block)
-      locals_keys = locals.keys
-      locals_keys.sort!{|x, y| x.to_s <=> y.to_s}
-
-      case scope
-      when Object
-        scope_class = Module === scope ? scope : scope.class
+      if @fixed_locals
+        locals_keys = EMPTY_ARRAY
       else
-        # :nocov:
-        scope_class = USE_BIND_CALL ? CLASS_METHOD.bind_call(scope) : CLASS_METHOD.bind(scope).call
-        # :nocov:
+        locals_keys = locals.keys
+        locals_keys.sort!{|x, y| x.to_s <=> y.to_s}
       end
-      method = compiled_method(locals_keys, scope_class)
 
-      if USE_BIND_CALL
-        method.bind_call(scope, locals, &block)
-      # :nocov:
-      else
-        method.bind(scope).call(locals, &block)
-      # :nocov:
+      unless scope_class = @scope_class
+        scope_class = case scope
+        when Object
+          Module === scope ? scope : scope.class
+        else
+          # :nocov:
+          USE_BIND_CALL ? CLASS_METHOD.bind_call(scope) : CLASS_METHOD.bind(scope).call
+          # :nocov:
+        end
       end
+
+      evaluate_method(compiled_method(locals_keys, scope_class), scope, locals, &block)
     end
 
     # Generates all template source by combining the preamble, template, and
@@ -267,6 +321,18 @@ module Tilt
 
     private
 
+    if RUBY_VERSION >= '2.3'
+      def _dup_string_if_frozen(string)
+        +string
+      end
+    # :nocov:
+    else
+      def _dup_string_if_frozen(string)
+        string.frozen? ? string.dup : string
+      end
+    end
+    # :nocov:
+
     def process_arg(arg)
       if arg
         case
@@ -291,7 +357,12 @@ module Tilt
     end
 
     def set_compiled_method_cache
-      @compiled_method = {}
+      @compiled_method = if @fixed_locals && @scope_class
+        # No hash needed, only a single compiled method per template.
+        compile_template_method(EMPTY_ARRAY, @scope_class)
+      else
+        {}
+      end
     end
 
     def local_extraction(local_keys)
@@ -315,9 +386,39 @@ module Tilt
       assignments.join("\n")
     end
 
+    if USE_BIND_CALL
+      def evaluate_method(method, scope, locals, &block)
+        if @fixed_locals
+          method.bind_call(scope, **locals, &block)
+        else
+          method.bind_call(scope, locals, &block)
+        end
+      end
+    # :nocov:
+    else
+      def evaluate_method(method, scope, locals, &block)
+        if @fixed_locals
+          if locals.empty?
+            # Empty keyword splat on Ruby 2.0-2.6 passes empty hash
+            method.bind(scope).call(&block)
+          else
+            method.bind(scope).call(**locals, &block)
+          end
+        else
+          method.bind(scope).call(locals, &block)
+        end
+      end
+    end
+    # :nocov:
+
     def compile_template_method(local_keys, scope_class=nil)
       source, offset = precompiled(local_keys)
-      local_code = local_extraction(local_keys)
+      if @fixed_locals
+        method_args = @fixed_locals
+      else
+        method_args = "(locals)"
+        local_code = local_extraction(local_keys)
+      end
 
       method_name = "__tilt_#{Thread.current.object_id.abs}"
       method_source = String.new
@@ -328,7 +429,7 @@ module Tilt
       end
 
       # Don't indent method source, to avoid indentation warnings when using compiled paths
-      method_source << "::Tilt::TOPOBJECT.class_eval do\ndef #{method_name}(locals)\n#{local_code}\n"
+      method_source << "::Tilt::TOPOBJECT.class_eval do\ndef #{method_name}#{method_args}\n#{local_code}\n"
 
       offset += method_source.count("\n")
       method_source << source
@@ -385,13 +486,49 @@ module Tilt
       method
     end
 
+    # Set the fixed locals for the template, which may be nil if no fixed locals can
+    # be determined.
+    def set_fixed_locals
+      fixed_locals = @options.delete(:fixed_locals)
+      extract_fixed_locals = @options.delete(:extract_fixed_locals)
+      default_fixed_locals = @options.delete(:default_fixed_locals)
+
+      if fixed_locals.nil?
+        if extract_fixed_locals.nil?
+          extract_fixed_locals = Tilt.extract_fixed_locals
+        end
+
+        if extract_fixed_locals
+          fixed_locals = extract_fixed_locals()
+        end
+
+        if fixed_locals.nil?
+          fixed_locals = default_fixed_locals
+        end
+      end
+
+      @fixed_locals = fixed_locals
+    end
+
+    # Extract fixed locals from the template code string. Should return nil
+    # if there are no fixed locals specified, or a method argument string
+    # surrounded by parentheses if there are fixed locals.  The method
+    # argument string will be used when defining the template method if given.
+    def extract_fixed_locals
+      if @data.is_a?(String) && (match = /\#\s*locals:\s*(\(.*\))/.match(@data))
+        match[1]
+      end
+    end
+
     def extract_encoding(script, &block)
       extract_magic_comment(script, &block) || script.encoding
     end
 
     def extract_magic_comment(script)
-      if script.frozen?
-        script = script.dup
+      was_frozen = script.frozen?
+      script = _dup_string_if_frozen(script)
+
+      if was_frozen
         yield script
       end
 
@@ -413,6 +550,16 @@ module Tilt
     end
   end
 
+  # Static templates are templates that return the same output for every render
+  #
+  # Instead of inheriting from the StaticTemplate class, you will use the .subclass
+  # method with a block which processes @data and returns the transformed value.
+  #
+  # Basic example which transforms the template to uppercase:
+  #
+  #   UppercaseTemplate = Tilt::StaticTemplate.subclass do
+  #     @data.upcase
+  #   end
   class StaticTemplate < Template
     def self.subclass(mime_type: 'text/html', &block)
       Class.new(self) do
@@ -451,5 +598,9 @@ module Tilt
     # Do nothing, since compiled method cache is not used.
     def set_compiled_method_cache
     end
+
+    # Do nothing, since fixed locals are not used.
+    def set_fixed_locals
+    end
   end
 end

data/lib/tilt.rb

@@ -5,12 +5,16 @@ require_relative 'tilt/template'
 # Namespace for Tilt. This module is not intended to be included anywhere.
 module Tilt
   # Current version.
-  VERSION = '2.4.0'
+  VERSION = '2.6.0'
+
+  EMPTY_ARRAY = [].freeze
+  private_constant :EMPTY_ARRAY
 
   EMPTY_HASH = {}.freeze
   private_constant :EMPTY_HASH
 
   @default_mapping = Mapping.new
+  @extract_fixed_locals = false
 
   # Replace the default mapping with a finalized version of the default
   # mapping. This can be done to improve performance after the template
@@ -86,6 +90,10 @@ module Tilt
     # @return [Tilt::Mapping] the main mapping object
     attr_reader :default_mapping
 
+    # Whether to extract fixed locals from templates by scanning the
+    # template content.
+    attr_accessor :extract_fixed_locals
+
     # Alias register as prefer for Tilt 1.x compatibility.
     alias prefer register
   end
@@ -139,11 +147,9 @@ module Tilt
 
   # ERB
   register_lazy :ERBTemplate,    'tilt/erb',    'erb', 'rhtml'
-  register_lazy :ErubisTemplate, 'tilt/erubis', 'erb', 'rhtml', 'erubis'
   register_lazy :ErubiTemplate,  'tilt/erubi',  'erb', 'rhtml', 'erubi'
 
   # Markdown
-  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'
@@ -175,7 +181,6 @@ module Tilt
   register_lazy :SlimTemplate,         'tilt/slim',      'slim'
   register_lazy :StringTemplate,       'tilt/string',    'str'
   register_lazy :TypeScriptTemplate,   'tilt/typescript', 'ts', 'tsx'
-  register_lazy :WikiClothTemplate,    'tilt/wikicloth', 'wiki', 'mediawiki', 'mw'
   register_lazy :YajlTemplate,         'tilt/yajl',      'yajl'
 
   # TILT3: Remove

metadata

@@ -1,16 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: tilt
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Ryan Tomayko
 - Magnus Holm
 - Jeremy Evans
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-27 00:00:00.000000000 Z
+date: 2025-01-13 00:00:00.000000000 Z
 dependencies: []
 description: Generic interface to multiple Ruby template engines
 email: code@jeremyevans.net
@@ -36,7 +35,6 @@ files:
 - lib/tilt/csv.rb
 - lib/tilt/erb.rb
 - lib/tilt/erubi.rb
-- lib/tilt/erubis.rb
 - lib/tilt/etanni.rb
 - lib/tilt/haml.rb
 - lib/tilt/kramdown.rb
@@ -44,7 +42,6 @@ files:
 - lib/tilt/livescript.rb
 - lib/tilt/mapping.rb
 - lib/tilt/markaby.rb
-- lib/tilt/maruku.rb
 - lib/tilt/nokogiri.rb
 - lib/tilt/pandoc.rb
 - lib/tilt/pipeline.rb
@@ -61,7 +58,6 @@ files:
 - lib/tilt/string.rb
 - lib/tilt/template.rb
 - lib/tilt/typescript.rb
-- lib/tilt/wikicloth.rb
 - lib/tilt/yajl.rb
 homepage: https://github.com/jeremyevans/tilt
 licenses:
@@ -71,7 +67,6 @@ metadata:
   changelog_uri: https://github.com/jeremyevans/tilt/blob/master/CHANGELOG.md
   mailing_list_uri: https://github.com/jeremyevans/tilt/discussions
   source_code_uri: https://github.com/jeremyevans/tilt
-post_install_message:
 rdoc_options:
 - "--line-numbers"
 - "--inline-source"
@@ -92,8 +87,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Generic interface to multiple Ruby template engines
 test_files: []

data/lib/tilt/erubis.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-require_relative 'erb'
-require 'erubis'
-
-warn 'tilt/erubis is deprecated, as erubis requires modifying string literals', uplevel: 1
-
-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
-      @freeze_string_literals = !!@options.delete(:freeze)
-      @outvar = @options.delete(:outvar) || '_erbout'
-      @options[:preamble] = false
-      @options[:postamble] = false
-      @options[: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 = String.new"].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.
-    def precompiled(locals)
-      source, offset = super
-      [source, offset - 1]
-    end
-
-    def freeze_string_literals?
-      @freeze_string_literals
-    end
-  end
-end

data/lib/tilt/maruku.rb

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-require_relative 'template'
-require 'maruku'
-
-warn 'tilt/maruku is deprecated, as maruku requires modifying string literals', uplevel: 1
-
-# Maruku markdown implementation. See: https://github.com/bhollis/maruku
-Tilt::MarukuTemplate = Tilt::StaticTemplate.subclass do
-  Maruku.new(@data, @options).to_html
-end

data/lib/tilt/wikicloth.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-require_relative 'template'
-require 'wikicloth'
-
-warn 'tilt/wikicloth is deprecated, as wikicloth requires modifying string literals', uplevel: 1
-
-# WikiCloth implementation. See: https://github.com/nricciar/wikicloth
-Tilt::WikiClothTemplate = Tilt::StaticTemplate.subclass do
-  parser = @options.delete(:parser) || WikiCloth::Parser
-  @options[:data] = @data
-  parser.new(@options).to_html
-end