tilt 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1386734fb6f20f9b1faf9e5edd4c83156e1d2e355141cd136ef949e956769e75
-  data.tar.gz: 52108af4de8efed7ade56f64e22d79fd3e5aaad4eb5ec36b2f0947242e102e57
+  metadata.gz: 950d868674b6de4ce7773935b2b9fd07c16528089320eaf0b3ab49be456cdf71
+  data.tar.gz: 720b39e51f933872fca6d768bb161ab08b96afeeafce3af69cbf81fa44a6ff58
 SHA512:
-  metadata.gz: 99a6e69ae4720ad5146c46b9b885fa4a4714b250d9db9168ae801d17f3146c90f25eab789401081100fdc065ae3ce3e804b79427e5ac835bd6bc576d3318a073
-  data.tar.gz: b0a44938aae6303bf03d174a942615e371669be99e4ec641a7a2b6ac0ee8d4f45f82869142f3e17b162efdd365883e909463763064b2b1b0417679652319c804
+  metadata.gz: 85b22c88b5bc0f0b546336e80af4329760939d3cdf1777568774e09e894a4de92c3abce170f6f9e694997291782551ef3f285e732d2054680605bbb150e17adb
+  data.tar.gz: 86c570a4eb2c7e85169eea86be5607e8257aa8594dc50737f928e901ea9966634f452dc0c24b11baa836e86c201e55c20d6946df5a9c8ee40fe547feb573f4c0

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,6 +101,13 @@ 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
 
@@ -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
@@ -303,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)
@@ -327,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
@@ -340,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
@@ -397,6 +486,40 @@ 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
@@ -475,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.5.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

metadata

@@ -1,16 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: tilt
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Ryan Tomayko
 - Magnus Holm
 - Jeremy Evans
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-20 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
@@ -68,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"
@@ -89,8 +87,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Generic interface to multiple Ruby template engines
 test_files: []