rabl 0.16.1 → 0.18.0

data/lib/rabl/helpers.rb

@@ -1,19 +1,25 @@
+# frozen_string_literal: true
+
 require 'active_support/inflector' # for the sake of pluralizing
+require 'erb' # ERB::Util.h for escape_all_output
 
 module Rabl
   module Helpers
     # data_object(data) => <AR Object>
     # data_object(@user => :person) => @user
-    # data_object(:user => :person) => @_object.send(:user)
+    # data_object(:user => :person) => @_object.public_send(:user)
     def data_object(data)
+      return data if data_item?(data)
+
       data = data.keys.first if data.is_a?(Hash) && data.keys.size == 1
-      data = @_object.__send__(data) if data.is_a?(Symbol) && defined?(@_object) && @_object && @_object.respond_to?(data)
+      data = @_object.public_send(data) if data.is_a?(Symbol) && defined?(@_object) && @_object && @_object.respond_to?(data)
       data
     end
 
-    # data_object_attribute(data) => @_object.send(data)
+    # data_object_attribute(data) => @_object.public_send(data)
+    # public_send, so a name like :format reaches method_missing (Hashie::Mash) instead of private Kernel#format
     def data_object_attribute(data)
-      attribute = @_object.__send__(data)
+      attribute = @_object.public_send(data)
       attribute = attribute.as_json if
         is_collection?(attribute, false) &&
         attribute.respond_to?(:as_json)
@@ -34,6 +40,7 @@ module Rabl
 
       if is_collection?(data) # data is a collection
         object_name = collection_root_name if collection_root_name
+        object_name ||= data_token if data_token.is_a?(Symbol) # child :units => "units", whatever the table (#394)
         object_name ||= data.table_name if data.respond_to?(:table_name)
 
         if object_name.nil? && data.respond_to?(:first)
@@ -41,7 +48,6 @@ module Rabl
           object_name = data_name(first).to_s.pluralize if first.present?
         end
 
-        object_name ||= data_token if data_token.is_a?(Symbol)
         object_name
       elsif is_object?(data) # data is an object
         object_name = object_root_name if object_root_name
@@ -82,6 +88,8 @@ module Rabl
     # is_collection?(@user) => false
     # is_collection?([]) => true
     def is_collection?(obj, follow_symbols = true)
+      return false if data_item?(obj)
+
       data_obj = follow_symbols ? data_object(obj) : obj
       data_obj &&
         data_obj.respond_to?(:map) && data_obj.respond_to?(:each) &&
@@ -89,6 +97,12 @@ module Rabl
           defined?(Hashie::Mash) && data_obj.is_a?(Hashie::Mash))
     end
 
+    # True for the Hash item that `extends` handed to this engine as its object (#396).
+    # It is data: never `@object => :name` alias syntax, and never a collection.
+    def data_item?(obj)
+      obj.is_a?(Hash) && defined?(@_data_item) && obj.equal?(@_data_item)
+    end
+
     # Returns the context_scope wrapping this engine, used for retrieving data, invoking methods, etc
     # In Rails, this is the controller and in Padrino this is the request context
     def context_scope
@@ -128,10 +142,14 @@ module Rabl
       return if object.nil?
 
       options.reverse_merge!({
-        :format     => "hash".freeze,
+        :format     => "hash",
         :view_path  => view_path,
+        :nested     => true,
         :root       => (options[:root] || false)
       })
+      options[:parent_engine] = rabl_template_engine
+      # a nested template renders as a hash, but looks its templates up in the format being rendered
+      options[:source_format] ||= manual_source_format if respond_to?(:manual_source_format, true)
 
       Engine.new(options[:source], options).apply(context_scope, :object => object, :locals => options[:locals], &block)
     end
@@ -139,12 +157,12 @@ module Rabl
     # Fetches a key from the cache and stores rabl template result otherwise
     # fetch_from_cache('some_key') { ...rabl template result... }
     def fetch_result_from_cache(cache_key, cache_options = {}, &block)
-      expanded_cache_key = ActiveSupport::Cache.expand_cache_key(cache_key, :rabl)
+      expanded_cache_key = TemplateCacheKey.expand(cache_key)
       Rabl.configuration.cache_engine.fetch(expanded_cache_key, cache_options, &block)
     end
 
     def write_result_to_cache(cache_key, cache_options = {}, &block)
-      expanded_cache_key = ActiveSupport::Cache.expand_cache_key(cache_key, :rabl)
+      expanded_cache_key = TemplateCacheKey.expand(cache_key)
       result = yield
       Rabl.configuration.cache_engine.write(expanded_cache_key, result, cache_options)
       result
@@ -159,13 +177,22 @@ module Rabl
       end
     end
 
+    protected
+      # Returns the engine of the template being rendered, if any (see Engine#rabl_template_identity)
+      def rabl_template_engine
+        nil
+      end
+
     module Escaper
+      # Returns escaped copies; the response may be shared with the cache, so it is never changed in place.
       def escape_output(response)
         case response
         when Hash
-          response.each{|k,v| response[k] = escape_value(v) }
+          escaped = response.dup
+          response.each { |k, v| escaped[k] = escape_value(v) }
+          escaped
         when Array
-          response.map!{|v| escape_value(v) }
+          response.dup.map! { |v| escape_value(v) }
         else
           response
         end

data/lib/rabl/multi_builder.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rabl
   class MultiBuilder
     include Helpers
@@ -53,7 +55,7 @@ module Rabl
     # Maps a cache key to an engine
     def map_cache_key_to_engine(engine)
       if cache_key = cache_key_for(engine)
-        result_cache_key = ActiveSupport::Cache.expand_cache_key(cache_key, :rabl)
+        result_cache_key = TemplateCacheKey.expand(cache_key)
         @cache_key_to_engine[result_cache_key] = engine
         disable_cache_read_on_render(engine)
       end
@@ -94,7 +96,11 @@ module Rabl
       @cache_results.each do |key, value|
         engine = @cache_key_to_engine[key]
         builder = @engine_to_builder[engine]
-        builder.replace_engine(engine, value) if value
+        next unless value && engine && builder
+
+        # a child is stored as { name => #<Engine> }; the cache holds only its rendered body
+        value = { engine.keys.first => value } if engine.is_a?(Hash)
+        builder.replace_engine(engine, value)
       end
     end
   end

data/lib/rabl/partials.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rabl
   module Partials
     include Helpers

data/lib/rabl/railtie.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rabl
   class Railtie < Rails::Railtie
     initializer "rabl.initialize" do |app|
@@ -22,7 +24,7 @@ module Rabl
         Rabl.register!
 
         # Inject dependency tracker for :rabl
-        if Rails.version =~ /^[4567]/
+        if Rails.version =~ /^[45678]/
           require 'action_view/dependency_tracker'
           ActionView::DependencyTracker.register_tracker :rabl, Rabl::Tracker
         end

data/lib/rabl/renderer.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rabl
   class Renderer
     # Defines class method rendering in supported formats
@@ -42,7 +44,7 @@ module Rabl
     # - context_scope:
     #     Override the render context_scope to the 'context_scope' object. Defaults to self.
     #
-    # Returns: And object representing the tranformed object in the requested format.
+    # Returns: And object representing the transformed object in the requested format.
     #   e.g. json, xml, bson, plist
     def render(context_scope = nil)
       context_scope ||= options[:scope] || self
@@ -63,7 +65,8 @@ module Rabl
       def process_source(source)
         return source if source.is_a?(String) && source =~ /\n/
 
-        source, _ = engine.fetch_source(source, { :view_path => options[:view_path] })
+        source, location = engine.fetch_source(source, { :view_path => options[:view_path] })
+        options[:source_location] ||= location
         source
       end
 

data/lib/rabl/sources.rb

@@ -1,20 +1,55 @@
+# frozen_string_literal: true
+
 module Rabl
   module Sources
     include Helpers
 
+    # Each distinct view path list or set of lookup details => the number standing for it in
+    # source cache keys, so a key is quick to compare however many view paths there are.
+    # The numbers come from its size, so it must never be cleared without LOOKUP_IDS_BY_OBJECT.
+    LOOKUP_IDS = {}
+    LOOKUP_IDS_LOCK = Mutex.new
+    # Rails' frozen view path lists and details keys => their numbers, worked out once per object.
+    # ceiling: CRuby 3.2 and higher only (JRuby's WeakMap holds its keys strongly, and before 3.2
+    # CRuby's slows its GC down with many dead keys); elsewhere the numbers are worked out on
+    # each lookup. Upgrade path: enable it on an engine once its WeakMap holds keys weakly
+    # without that cost.
+    LOOKUP_IDS_BY_OBJECT = (ObjectSpace::WeakMap.new if RUBY_ENGINE == "ruby" && RUBY_VERSION >= "3.2")
+    # I18n's fallbacks (by identity) => locale => default locale => format => the number standing
+    # for the manual lookup's format and locale chain in source cache keys, worked out once for each.
+    # ceiling: the fallbacks are read once per locale, so fallbacks changed in place later
+    # (I18n.fallbacks.map) aren't seen by the cache until they are assigned anew
+    # (I18n.fallbacks = ...); and an I18n.default_locale reassigned by another thread while an entry
+    # is made can store it under the old default. Upgrade path: key by the fallbacks' contents.
+    MANUAL_LOOKUP_IDS = [nil]
+    MANUAL_LOOKUP_IDS_LOCK = Mutex.new
+
     # Returns source for a given relative file
     # fetch_source("show", :view_path => "...") => "...contents..."
     def fetch_source(file, options = {})
-      view_paths = Array(options[:view_path]) + Array(Rabl.configuration.view_paths)
+      resolver = source_resolver
+      lookup = source_lookup(resolver) if Rabl.configuration.cache_sources
+      # a lookup that can't be told apart from others (see source_lookup) isn't cached
+      return resolve_source(file, options, resolver) if lookup == false
+
+      Rabl.source_cache(file, Array(options[:view_path]), lookup) do
+        resolve_source(file, options, resolver)
+      end
+    end
+
+    private
+      # Looks the file up with the given resolver and returns its source and path
+      def resolve_source(file, options, resolver)
+        view_paths = Array(options[:view_path]) + Array(Rabl.configuration.view_paths)
 
-      Rabl.source_cache(file, view_paths) do
         file_path = \
-          if defined?(Padrino) && context_scope.respond_to?(:settings) && context_scope.respond_to?(:resolve_template)
+          case resolver
+          when :padrino
             fetch_padrino_source(file, options)
-          elsif defined?(Rails) && context_scope.respond_to?(:view_paths)
+          when :rails
             _view_paths = view_paths + Array(context_scope.view_paths.to_a)
-            fetch_rails_source(file, options) || fetch_manual_template(_view_paths, file)
-          elsif defined?(Sinatra) && context_scope.respond_to?(:settings) && context_scope.settings.respond_to?(:views)
+            fetch_rails_source(file, options) || fetch_manual_template(_view_paths, file, rails_lookup_format, rails_lookup_locales)
+          when :sinatra
             fetch_sinatra_source(file, options)
           else # generic template resolution
             fetch_manual_template(view_paths, file)
@@ -26,9 +61,186 @@ module Rabl
 
         [File.read(file_path.to_s), file_path.to_s]
       end
-    end
 
-    private
+      # Returns which framework's template lookup fetch_source uses in this context_scope
+      def source_resolver
+        if defined?(Padrino) && context_scope.respond_to?(:settings) && context_scope.respond_to?(:resolve_template)
+          :padrino
+        elsif defined?(Rails) && context_scope.respond_to?(:view_paths)
+          :rails
+        elsif defined?(Sinatra) && context_scope.respond_to?(:settings) && context_scope.settings.respond_to?(:views)
+          :sinatra
+        end
+      end
+
+      # Returns the format fetch_source looks templates up in: under Rails' lookup the
+      # request's (see rails_lookup_format), elsewhere the one being rendered (json for hash)
+      def source_lookup_format
+        (source_resolver == :rails ? rails_lookup_format : manual_source_format).to_s
+      end
+
+      # Returns what, besides the file and the :view_path option, the resolver's lookup
+      # depends on, so the source cache keeps each lookup's result apart: under Rails the
+      # format, the lookup details (formats, locale, variants, handlers, and registered
+      # details such as versioncake's versions) and the view paths; elsewhere the format
+      # and locales the manual lookup prefers, and under Sinatra the app's views. Returns
+      # false when a view path has no stable name, so the lookup isn't cached.
+      # ceiling: outside Rails the cache (and MANUAL_LOOKUP_IDS) keeps an entry per locale looked
+      # up in, as Rails' details keys do, so it is bounded by I18n.available_locales only while
+      # I18n.enforce_available_locales is on (the default).
+      def source_lookup(resolver)
+        case resolver
+        when :rails
+          view_paths = rails_view_paths_id or return false
+          details = rails_details_id
+          return false if details == false
+          [rails_lookup_format, details, view_paths]
+        when :sinatra
+          [context_scope.settings.views, manual_lookup_id]
+        else
+          manual_lookup_id
+        end
+      end
+
+      # Returns the number standing for the format and locales the manual lookup prefers.
+      # Nested Hashes of what the locales come from, as this runs on every source cache hit.
+      def manual_lookup_id
+        format = manual_source_format
+        return lookup_id([:manual, format, []]) unless defined?(::I18n) && ::I18n.respond_to?(:config)
+
+        config = ::I18n.config
+        locale, default_locale = config.locale, config.default_locale
+        fallbacks = ::I18n.fallbacks if ::I18n.respond_to?(:fallbacks)
+        table = MANUAL_LOOKUP_IDS[0]
+        ids = table[1] if table && table[0].equal?(fallbacks)
+        ids &&= ids[locale]
+        ids &&= ids[default_locale]
+        (ids && ids[format]) || MANUAL_LOOKUP_IDS_LOCK.synchronize do
+          table = MANUAL_LOOKUP_IDS[0]
+          # only the current fallbacks are kept, so assigning them per request doesn't grow it
+          table = MANUAL_LOOKUP_IDS[0] = [fallbacks, {}] unless table && table[0].equal?(fallbacks)
+          ids = (table[1][locale] ||= {})[default_locale] ||= {}
+          # lookup_id takes its own lock, never the other way round
+          ids[format] ||= lookup_id([:manual, format, manual_source_locales])
+        end
+      end
+
+      # Returns the number standing for the Rails view paths, the same for the same paths,
+      # or false when one of them has no stable name (a resolver without to_path)
+      def rails_view_paths_id
+        paths = context_scope.view_paths
+        paths = paths.respond_to?(:paths) ? paths.paths : Array(paths.to_a)
+        # Rails 7.1 and higher freeze a PathSet's paths
+        lookup_id_by_object(paths.frozen? && paths) do
+          names = paths.map do |path|
+            if path.is_a?(String)
+              path
+            elsif path.respond_to?(:to_path)
+              path.to_path.to_s
+            else
+              break
+            end
+          end
+          names ? lookup_id([:view_paths, names]) : false # false is remembered too
+        end
+      end
+
+      # Returns the number standing for the Rails lookup context's details
+      def rails_details_id
+        lookup_context = context_scope.lookup_context if context_scope.respond_to?(:lookup_context)
+        return unless lookup_context
+        # Rails reads the registered details from ActionView::LookupContext itself (7.0 and higher keep
+        # them there only, so a subclass's own are nil). Module#=== checks the object itself, not what
+        # a delegator forwards to.
+        names = ActionView::LookupContext.registered_details if defined?(ActionView::LookupContext) && ActionView::LookupContext === lookup_context
+        names ||= lookup_context.class.registered_details if lookup_context.class.respond_to?(:registered_details)
+        return false unless names # what the lookup depends on can't be told, so it isn't cached
+
+        # Rails' details_key is the same object for the same details until Rails clears them
+        # (in development, when templates change), and the details give the same number again then
+        details_key = lookup_context.details_key if lookup_context.respond_to?(:details_key)
+        lookup_id_by_object(details_key) do
+          # Rails' own accessors: LookupContext#locale returns the first locale, the lookup
+          # uses the whole chain (I18n.locale, its fallbacks and the default locale)
+          accessors = ActionView::LookupContext::Accessors if defined?(ActionView::LookupContext::Accessors)
+          details = names.map do |name|
+            if accessors && accessors === lookup_context && accessors.method_defined?(name)
+              accessors.instance_method(name).bind_call(lookup_context)
+            else
+              lookup_context.public_send(name)
+            end
+          end
+          lookup_id([:details, details])
+        end
+      end
+
+      # Returns the number for object, or the block's number, which it is then kept for
+      def lookup_id_by_object(object)
+        return yield unless object && LOOKUP_IDS_BY_OBJECT
+
+        id = LOOKUP_IDS_BY_OBJECT[object]
+        id.nil? ? (LOOKUP_IDS_BY_OBJECT[object] = yield) : id
+      end
+
+      # Returns the number standing for value, the same for an equal value
+      def lookup_id(value)
+        LOOKUP_IDS[value] || LOOKUP_IDS_LOCK.synchronize do
+          LOOKUP_IDS.fetch(value) { LOOKUP_IDS[Rabl.frozen_copy(value)] = LOOKUP_IDS.size }
+        end
+      end
+
+      # Returns the format Rails 3.2 and higher look templates up in:
+      # the request's format, or for HTML requests the format being rendered (json for
+      # the default handler and for hash), as a Symbol, the only form Rails 7.0 and higher match
+      def rails_source_format
+        format = context_scope.request.format.to_sym
+        format == :html ? manual_source_format.to_sym : format
+      end
+
+      # Returns the format Rails looks the template up in or, when there is none (a view
+      # without a request, or a request format Rails doesn't know, where that lookup fails
+      # and the manual lookup is used), the format being rendered
+      def rails_lookup_format
+        rails_source_format || manual_source_format
+      rescue StandardError
+        manual_source_format
+      end
+
+      # Returns the locale chain of the Rails lookup context, which the source cache key holds
+      # (it can differ from I18n's, e.g. in I18n.with_locale or outside a controller action),
+      # or I18n's chain when the lookup context isn't Rails' own
+      def rails_lookup_locales
+        lookup_context = context_scope.lookup_context if context_scope.respond_to?(:lookup_context)
+        accessors = ActionView::LookupContext::Accessors if defined?(ActionView::LookupContext::Accessors)
+        # Module#=== checks the object itself, not what a delegator forwards to (see rails_details_id)
+        return manual_source_locales unless lookup_context && accessors && accessors === lookup_context && accessors.method_defined?(:locale)
+
+        Array(accessors.instance_method(:locale).bind_call(lookup_context)).map(&:to_s)
+      end
+
+      # Returns the format the manual lookup prefers: the format being rendered (json for hash),
+      # which nested templates are given as :source_format
+      def manual_source_format
+        # Engine keeps its options in @_options, Builder in @options
+        options = (@_options if defined?(@_options)) || (@options if defined?(@options))
+        format = options[:source_format] || options[:format] if options
+        format ||= request_format if defined?(request_format)
+        format = format.to_s
+        format.empty? || format == "hash" ? "json" : format
+      end
+
+      # Returns the locales the manual lookup prefers, best first: like Rails' lookup,
+      # I18n's locale, its fallbacks and the default locale
+      def manual_source_locales
+        return [] unless defined?(::I18n) && ::I18n.respond_to?(:config)
+
+        config = ::I18n.config
+        locales = [config.locale]
+        locales.concat(::I18n.fallbacks[config.locale]) if ::I18n.respond_to?(:fallbacks)
+        locales << config.default_locale
+        locales.uniq.map(&:to_s)
+      end
+
       # Returns the rabl template path for padrino views using configured views
       def fetch_padrino_source(file, options = {})
         view_path = Array(options[:view_path] || context_scope.settings.views)
@@ -51,9 +263,7 @@ module Rabl
               context_scope.lookup_context.find(file, [], partial)
             else # Rails 3.2 and higher
               # pull format directly from rails unless it is html
-              request_format = context_scope.request.format.to_sym
-              source_format = request_format unless request_format == :html
-              context_scope.lookup_context.find(file, [], partial, [], { :formats => [source_format] })
+              context_scope.lookup_context.find(file, [], partial, [], { :formats => [rails_source_format] })
             end
           end
           template = lookup_proc.call(false) rescue nil
@@ -71,9 +281,46 @@ module Rabl
         fetch_manual_template(view_path, file)
       end
 
-      # Returns the rabl template by looking up files within the view_path and specified file path
-      def fetch_manual_template(view_path, file)
-        Dir[File.join("{#{view_path.join(",")}}", "{#{file},#{partialized(file)}}" + ".{*.,}rabl")].first
+      # Returns the rabl template by looking up files within the view_path and specified file path.
+      # Like Rails' lookup, it takes a template named for the format and locales it is given
+      # ("show.json.rabl", "show.fr.json.rabl", "show.fr.rabl" or "show.rabl"), the best named
+      # in the first view path, and the file before the partial, that has one; otherwise the
+      # first file found ("show.xml.rabl" for json), as it always has.
+      # ceiling: other details in a name, such as variants ("show.json+mobile.rabl"), never match
+      # here; Rails' own lookup handles those where it is used.
+      def fetch_manual_template(view_path, file, format = nil, locales = nil)
+        found = Dir[File.join("{#{view_path.join(",")}}", "{#{file},#{partialized(file)}}" + ".{*.,}rabl")]
+        return found.first if found.size < 2 # nothing to choose between, as for most templates
+
+        format ||= manual_source_format
+        locales ||= manual_source_locales
+        format = format.to_s
+        prefixes = [file, partialized(file)].map { |name| "#{File.basename(name)}." }
+        best = best_rank = best_group = nil
+
+        # Dir returns the files of each view path and name together, in the order given
+        found.each do |path|
+          dir, base = File.split(path)
+          prefix = prefixes.find { |name| base.start_with?(name) } or next
+          group = [dir, prefix]
+          break if best && group != best_group
+
+          rank = manual_template_rank(base[prefix.size...-4].split("."), format, locales)
+          best, best_rank, best_group = path, rank, group if rank && (!best || (rank <=> best_rank) < 0)
+        end
+
+        best || found.first
+      end
+
+      # Ranks the details in a template's name ("fr.json" => ["fr", "json"]) the way Rails
+      # sorts them, the locale first: a smaller rank is better, nil means they don't match
+      def manual_template_rank(details, format, locales)
+        format_rank = details.last == format ? 1 : 2
+        details = details[0...-1] if format_rank == 1
+        return [locales.size, format_rank] if details.empty?
+
+        locale_rank = locales.index(details.first)
+        [locale_rank, format_rank] if locale_rank && details.size == 1
       end
 
       # Returns a partialized version of a file path

data/lib/rabl/template.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # TILT Template
 if defined?(Tilt)
   class RablTemplate < Tilt::Template
@@ -11,7 +13,8 @@ if defined?(Tilt)
     end
 
     def evaluate(context_scope, locals, &block)
-      options = @options.merge(:source_location => file)
+      # an inline template (Sinatra's __END__ section) starts at line, in its app's file
+      options = @options.merge(:source_location => file, :source_line => line)
       ::Rabl::Engine.new(data, options).apply(context_scope, locals, &block).render
     end
   end
@@ -51,7 +54,7 @@ if defined?(ActionView) && defined?(Rails) && Rails.respond_to?(:version) && Rai
         def self.call(template)
           source = template.source
 
-          %{ ::Rabl::Engine.new(#{source.inspect}).
+          %{ ::Rabl::Engine.new(#{source.inspect}, :source_location => #{template.identifier.inspect}).
               apply(self, assigns.merge(local_assigns)).
               render }
         end # call
@@ -62,8 +65,8 @@ if defined?(ActionView) && defined?(Rails) && Rails.respond_to?(:version) && Rai
   ActionView::Template.register_template_handler :rabl, ActionView::Template::Handlers::Rabl
 end
 
-# Rails 6.X / 7.X Template
-if defined?(ActionView) && defined?(Rails) && Rails.respond_to?(:version) && Rails.version.to_s =~ /^[67]/
+# Rails 6.X / 7.X / 8.X Template
+if defined?(ActionView) && defined?(Rails) && Rails.respond_to?(:version) && Rails.version.to_s =~ /^[678]/
   module ActionView
     module Template::Handlers
       class Rabl
@@ -71,7 +74,7 @@ if defined?(ActionView) && defined?(Rails) && Rails.respond_to?(:version) && Rai
         self.default_format = :json
 
         def self.call(template, source)
-          %{ ::Rabl::Engine.new(#{source.inspect}).
+          %{ ::Rabl::Engine.new(#{source.inspect}, :source_location => #{template.identifier.inspect}).
               apply(self, assigns.merge(local_assigns)).
               render }
         end # call

data/lib/rabl/template_cache_key.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'digest/sha1'
+
+module Rabl
+  # Marks every cache key rabl reads or writes. Bump it when a release changes rendered output so
+  # that entries cached by earlier versions would be wrong: the keys change once, so no entry
+  # cached by an earlier version, which lacks that release's output fixes, is served.
+  # Keys before 0.18.0 had no marker ("rabl/", and "rabl_build/" in old releases); 2 is 0.18.0.
+  # The README's caching example shows the resulting prefix: update it when this changes.
+  CACHE_KEY_VERSION = 2
+
+  # Builds the parts of template cache keys. These are module functions rather than
+  # Engine methods so that they never shadow helpers a template calls.
+  module TemplateCacheKey
+    module_function
+
+    # Returns the key rabl reads and writes in the cache engine for the given parts. Earlier
+    # versions put their keys under "rabl/", so no key built here can be one of theirs.
+    # TemplateCacheKey.expand([user, "json"]) => "rabl-v2/users/1/json"
+    def expand(parts)
+      ActiveSupport::Cache.expand_cache_key(parts, "rabl-v#{CACHE_KEY_VERSION}")
+    end
+
+    # Returns a digest of the given parts
+    # TemplateCacheKey.digest(["app/views/show.rabl", "object @user"]) => "4a1b..."
+    def digest(parts)
+      digest = Digest::SHA1.new
+      Array(parts).flatten.each { |part| digest << part.to_s << "\0" }
+      digest.hexdigest
+    end
+
+    # Returns a path that stays the same when the application moves: relative to the
+    # working directory when inside it, and nil for "(eval)" locations (the identity of
+    # the parent template tells evaluated sources apart).
+    # ceiling: paths outside the working directory stay absolute, so moving them changes
+    # the keys; a configurable root would let those move too.
+    # TemplateCacheKey.path("/app/views/show.rabl", "/app/") => "views/show.rabl"
+    def path(path, root = self.root)
+      path = path.to_s.dup.force_encoding(Encoding::BINARY) # paths may differ in encoding
+      return if path.empty? || path.start_with?("(eval")
+
+      root && path.start_with?(root) ? path.byteslice(root.bytesize..-1) : path
+    end
+
+    # Returns the column a block starts at, which tells apart blocks on one line, or nil when
+    # the runtime doesn't expose it.
+    # ceiling: without RubyVM::InstructionSequence (e.g. on JRuby), blocks that start on the
+    # same line of a template share an identity; put them on separate lines, or give them
+    # distinct cache keys.
+    def column(block)
+      return unless defined?(RubyVM::InstructionSequence)
+
+      iseq = RubyVM::InstructionSequence.of(block)
+      iseq && iseq.to_a[4][:code_location][1]
+    rescue StandardError
+      nil
+    end
+
+    # Returns the working directory with a trailing separator, as bytes, or nil if it is gone
+    def root
+      File.join(Dir.pwd, "").force_encoding(Encoding::BINARY)
+    rescue SystemCallError
+      nil
+    end
+
+    # Returns the options that change the shape of a rendering. A nested (hash format)
+    # rendering gets its root options from its parent; for other formats only root
+    # options given explicitly are added, so default keys have none. The format `extends`
+    # and `partial` look templates up in (lookup_format) is added when it isn't the one
+    # rendered, a hash counting as JSON: a nested rendering is a hash for every format.
+    # TemplateCacheKey.shape({ :format => "hash", :root => true }, "json") => ["root", "no_child_root"]
+    # TemplateCacheKey.shape({ :format => "hash", :child_root => true }, "xml") => ["lookup_format=xml"]
+    # TemplateCacheKey.shape({ :format => "json", :except => :b }, "json") => ["except=:b"]
+    def shape(options, lookup_format)
+      shape = []
+      format = options[:format].to_s
+
+      if format == "hash"
+        shape << "root" if options[:root]
+        shape << "no_child_root" unless options[:child_root]
+        shape << "object_root=#{options[:object_root_name].inspect}" if options[:object_root_name]
+      else
+        shape << "root=#{options[:root].inspect}" if options.key?(:root)
+        shape << "child_root=#{options[:child_root].inspect}" if options.key?(:child_root)
+      end
+
+      shape << "except=#{Array(options[:except]).map { |name| name.inspect }.join(',')}" if options[:except]
+      shape << "lookup_format=#{lookup_format}" unless lookup_format == (format == "hash" ? "json" : format)
+      shape
+    end
+  end
+end

data/lib/rabl/tracker.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rabl
   # DependencyTracker for ActionView to support cache digest
   class Tracker

data/lib/rabl/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rabl
-  VERSION = "0.16.1"
+  VERSION = "0.18.0"
 end