rabl 0.17.0 → 0.18.0

data/lib/rabl/engine.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rabl
   class Engine
     include Helpers
@@ -8,6 +10,66 @@ module Rabl
     FORMATS = [:json, :xml, :plist, :bson, :msgpack]
     SAFE_FORMATS = FORMATS + [:mpac, :dumpable, :hash]
 
+    # JSONP callback names that are accepted: identifiers, optionally dotted (e.g. "jQuery_1.cb")
+    RABL_JSON_CALLBACK_NAME = /\A[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*\z/
+    RABL_JSON_CALLBACK_MAX_LENGTH = 128
+
+    # Array#to_xml names its items after the singular of the dasherized root, which misses
+    # inflections that match only the underscored name: rules written in underscored form
+    # (inflect.irregular 'lesson_progress', 'lessons_progresses', #559), underscored uncountable
+    # words (inflect.uncountable 'user_settings') and rules using \w (/^(\w+)ves$/). An XmlArray
+    # names them after the singular of the root as given, as rabl does for JSON item roots
+    # (to_xml then dasherizes it like any other key), when that singular comes from a newer rule
+    # than the one ActiveSupport applies to the dasherized root. Otherwise the name is left to
+    # Array#to_xml, so built-in inflections, inflections written with dashes (the workaround in
+    # #559) and uncountable words at the end of a name ("animal-species") are named as before.
+    # The arrays of one rendering share children_names, so each root's name is worked out once.
+    class XmlArray < Array
+      def initialize(items, children_names)
+        super(items)
+        @children_names = children_names
+      end
+
+      def to_xml(options = {}, &block)
+        root = options[:root].to_s
+        unless options[:children] || !options[:root] || root.empty?
+          renamed = ActiveSupport::XmlMini.rename_key(root, options)
+          children = @children_names.fetch([root, renamed]) do |key|
+            @children_names[key] = children_name(root, renamed, options)
+          end
+          options = options.merge(:children => children)
+        end
+        super(options, &block)
+      end
+
+      private
+
+      # The singular of root when it comes from a newer rule than the one ActiveSupport applies
+      # to the renamed root, or else the singular of the renamed root, as Array#to_xml names items
+      def children_name(root, renamed, options)
+        singular = root.singularize
+        renamed_singular = renamed.singularize
+        xml_mini = ActiveSupport::XmlMini
+        return renamed_singular if xml_mini.rename_key(singular, options) == xml_mini.rename_key(renamed_singular, options)
+
+        singular_rule_rank(root) < singular_rule_rank(renamed) ? singular : renamed_singular
+      end
+
+      # The position of the singular rule ActiveSupport applies to word. The rules are newest
+      # first, so a lower rank is a rule defined later; -1 for an uncountable word, and the rule
+      # count when no rule matches.
+      def singular_rule_rank(word)
+        inflections = ActiveSupport::Inflector.inflections
+        uncountables = inflections.uncountables
+        # ActiveSupport < 5 keeps them in a plain Array, checked by the last word
+        return -1 if uncountables.respond_to?(:uncountable?) ? uncountables.uncountable?(word) : uncountables.include?(word.downcase[/\b\w+\Z/])
+
+        rules = inflections.singulars
+        rules.index { |(rule, _)| rule.is_a?(Regexp) ? rule.match?(word) : word.include?(rule) } || rules.size
+      end
+    end
+    private_constant :XmlArray
+
     # Constructs a new ejs engine based on given vars, handler and declarations
     # Rabl::Engine.new("...source...", { :format => "xml", :root => true, :view_path => "/path/to/views" })
     def initialize(source, options = {})
@@ -17,8 +79,11 @@ module Rabl
 
       @_view_path     = options[:view_path]
       @_context_scope = options[:scope]
+      @_data_item     = options[:data_item]
 
       @_cache_read_on_render = true
+      @_skip_json_callback   = false
+      @_rendering = false
     end
 
     def source=(source)
@@ -35,6 +100,17 @@ module Rabl
       reset_settings!
       reset_options!
 
+      # A block (child, glue, or extends/partial with a block) is identified by its
+      # location and the engine of the template that defined it
+      @_block_identity    = block && [block, @_options[:parent_engine]]
+      @_template_identity = nil
+      @_identity_memo     = nil
+
+      # A cache key belongs to one render; the template sets it again
+      remove_instance_variable(:@_cache_key) if defined?(@_cache_key)
+      remove_instance_variable(:@_replaced_data) if defined?(@_replaced_data)
+      @_full_cache_key = nil
+
       eval_source(locals, &block)
 
       instance_exec(root_object, &block) if block_given?
@@ -47,16 +123,28 @@ module Rabl
     def render(context_scope = nil, locals = nil, &block)
       apply(context_scope, locals, &block) if context_scope || locals || block
 
-      cache_results do
-        send("to_#{@_options[:format]}")
+      return cache_results { send("to_#{@_options[:format]}") } unless @_options[:format].to_s == "json"
+
+      # The JSONP callback comes from the request, so it is added after the cache.
+      result = cache_results do
+        begin
+          @_skip_json_callback = true
+          to_json
+        ensure
+          @_skip_json_callback = false
+        end
       end
+
+      rabl_wrap_json_callback(result)
     end
 
     def cache_key
       return unless defined?(@_cache_key)
 
       @_full_cache_key ||= begin
-        cache_key = Array(@_cache_key) + [@_options[:root_name], @_options[:format]]
+        cache_key = rabl_cache_key_parts + [@_options[:root_name], @_options[:format]]
+        # a nested engine caches its output before it is escaped, so it gets its own key
+        cache_key << 'nested' if @_options[:nested]
 
         if digestor_available? && respond_to?(:lookup_context) && lookup_context
           template = @_options[:template] || @virtual_path
@@ -71,8 +159,19 @@ module Rabl
             end
 
           cache_key << digest
+          # The digest covers the template source, but not the block that defines this engine
+          if @_block_identity
+            block, parent = @_block_identity
+            key = [:block, block, parent && parent.rabl_template_identity]
+            cache_key << rabl_memoized_digest(key) { TemplateCacheKey.digest(rabl_block_identity) }
+          end
+        else
+          cache_key << rabl_template_identity
         end
 
+        cache_key << "collection" if is_collection?(root_object)
+        cache_key.concat(TemplateCacheKey.shape(@_options, source_lookup_format))
+
         cache_key
       end
     end
@@ -80,12 +179,15 @@ module Rabl
     # Returns a hash representation of the data object
     # to_hash(:root => true, :child_root => true)
     def to_hash(options = {})
-      options.reverse_merge!(@_options)
+      # options given to the engine (e.g. Rabl::Renderer's :root) win over the format defaults
+      options.merge!(@_options)
 
       data = root_object
 
       options[:root_name] = determine_object_root(data, root_name, options[:root])
+      options[:template_engine] = self
 
+      @_rendering = true
       result =
         if is_object?(data) || !data # object @user
           Builder.new(data, @_settings, options).to_hash
@@ -93,9 +195,12 @@ module Rabl
           MultiBuilder.new(data, @_settings, options).to_a
         end
 
-      result = escape_output(result) if Rabl.configuration.escape_all_output
+      # A nested engine (child, glue, extends, partial) is escaped with the engine it is part of
+      result = escape_output(result) if Rabl.configuration.escape_all_output && !@_options[:nested]
 
       result
+    ensure
+      @_rendering = false
     end
 
     def to_dumpable(options = {})
@@ -111,7 +216,7 @@ module Rabl
     def to_json(options = {})
       options.reverse_merge!({ :root => Rabl.configuration.include_json_root })
       result = to_dumpable(options)
-      format_json(result)
+      rabl_wrap_json_callback(format_json(result))
     end
 
     # Returns a msgpack representation of the data object
@@ -134,6 +239,8 @@ module Rabl
     # Returns an xml representation of the data object
     # to_xml(:root => true)
     def to_xml(options = {})
+      load_xml_support!
+
       options = {
         :root       => (include_root = Rabl.configuration.include_xml_root),
         :child_root => include_root && Rabl.configuration.include_child_root
@@ -143,7 +250,14 @@ module Rabl
 
       result = to_hash(options)
 
-      result.to_xml(xml_options)
+      # Name the items after the object root and unwrap them, or Array#to_xml wraps each
+      # { object_root => ... } item again in the singular collection root (#581)
+      if result.is_a?(Array) && is_name_value?(object_root_name)
+        xml_options[:children] = object_root_name.to_s
+        result = result.map { |item| item.is_a?(Hash) && item.key?(object_root_name) ? item[object_root_name] : item }
+      end
+
+      xml_arrays(result).to_xml(xml_options)
     end
 
     # Returns a bson representation of the data object
@@ -156,7 +270,14 @@ module Rabl
         result = { root_name => result }
       end
 
-      Rabl.configuration.bson_engine.serialize(result).to_s
+      bson_engine = Rabl.configuration.bson_engine
+      if bson_engine.respond_to?(:serialize)
+        # BSON < 2.0 API
+        bson_engine.serialize(result).to_s
+      else
+        # BSON >= 2.0 API
+        result.to_bson.to_s
+      end
     end
 
     # Sets the object to be used as the data source for this template
@@ -165,9 +286,20 @@ module Rabl
     # object @users
     def object(template_data)
       current_data  = (@_locals[:object].nil? || template_data == false) ? template_data : @_locals[:object]
+      # Rendered for an item (extends, partial, child), the template gets the item instead of
+      # the data it names, e.g. the outer @user; cache keys then add the item (see #rabl_cache_key_parts)
+      if !current_data.equal?(template_data)
+        alias_form = template_data.is_a?(Hash) && template_data.size == 1 && is_name_value?(template_data.values.first)
+        @_replaced_data = alias_form ? template_data.keys.first : template_data # object @user => :person names @user
+      end
       @_data_object = data_object(current_data)
       @_root_name_data = template_data.is_a?(Hash) && !current_data.is_a?(Hash) ? template_data : current_data
-      @_root_name_data = @_root_name_data.values.first if @_root_name_data.is_a?(Hash)
+      if @_root_name_data.is_a?(Hash)
+        alias_form = @_root_name_data.size == 1 # object @user => :person
+        @_root_name_data = @_root_name_data.values.first
+        # object @user => "person" names the root the same way
+        @_root_name_data = @_root_name_data.to_sym if alias_form && @_root_name_data.is_a?(String)
+      end
 
       # If we turn this around, `@_root_name_date ==` may trigger data to be loaded unnecessarily.
       # TODO: is nil a different semantic? otherwise don't use `false ==`, use !
@@ -201,13 +333,19 @@ module Rabl
     # collection @users => :people
     # collection @users, :root => :person
     # collection @users, :object_root => :person
+    # collection @users => :people, :object_root => false
     def collection(data, options = {})
+      data, options = split_folded_options(data, options, [:root, :object_root])
+
       @_collection_name = options[:root] if options[:root]
       @_collection_name ||= data.values.first if data.is_a?(Hash)
 
       @_object_root_name = options[:object_root] if options.has_key?(:object_root)
 
-      object(data_object(data) || [])
+      collection_data = data_object(data)
+      object(collection_data || [])
+      # a nil collection is given to object as [], but the template names nil (see #object)
+      @_replaced_data = collection_data if defined?(@_replaced_data)
     end
 
     # Sets the cache key to be used by ActiveSupport::Cache.expand_cache_key
@@ -236,6 +374,8 @@ module Rabl
           attribute(key, conditions.merge(:as => as))
         end
       else # array of attributes i.e :foo, :bar, :baz
+        warn_if_rendering(:attribute)
+
         options = args.extract_options!
         args.each do |name|
           @_settings[:attributes] << { :name => name, :options => options }
@@ -248,25 +388,42 @@ module Rabl
     # node(:foo) { "bar" }
     # node(:foo, :if => lambda { ... }) { "bar" }
     def node(name = nil, options = {}, &block)
+      warn_if_rendering(:node)
+
+      if name.is_a?(Hash) && name.present? && options.blank? && (name.keys - [:if, :unless]).empty?
+        name, options = nil, name # node(:if => lambda { ... }) { ... } has conditions but no name
+      end
+
       @_settings[:node] << { :name => name, :options => options, :block => block }
     end
     alias_method :code, :node
 
     # Creates a child node that is included in json output
     # child(@user) { attribute :full_name }
+    # child(:posts => :items, :if => lambda { ... }) { attribute :title }
     def child(data, options = {}, &block)
+      warn_if_rendering(:child)
+
+      data, options = split_folded_options(data, options, [:if, :unless, :root, :object_root])
+
       @_settings[:child] << { :data => data, :options => options, :block => block }
     end
 
     # Glues data from a child node to the json_output
     # glue(@user) { attribute :full_name => :user_full_name }
     def glue(data, options = {}, &block)
+      warn_if_rendering(:glue)
+
+      data, options = split_folded_options(data, options, [:if, :unless])
+
       @_settings[:glue] << { :data => data, :options => options, :block => block }
     end
 
     # Extends an existing rabl template with additional attributes in the block
     # extends("users/show", :object => @user) { attribute :full_name }
     def extends(file, options = {}, &block)
+      return if warn_if_rendering(:extends)
+
       options.reverse_merge!({ :view_path => options[:view_path] || view_path })
 
       @_settings[:extends] << { :file => file, :options => options, :block => block }
@@ -298,7 +455,81 @@ module Rabl
       @_cache_read_on_render
     end
 
+    # Returns the key given to `cache` in the template, if any. When the template is rendered
+    # for an item (see #object) and its key has the data the template names (`cache @user`, or
+    # the nil in `cache ['v1', @topic]`) but not the item, the item is added, so each item gets
+    # its own key; the other parts (such as the current user) are kept.
+    # ceiling: only the key's own parts are compared, not those of an array nested in it;
+    # walk nested arrays too if such keys turn up.
+    def rabl_cache_key_parts
+      return [] unless defined?(@_cache_key)
+
+      parts = Array(@_cache_key)
+      return parts unless defined?(@_replaced_data)
+
+      item = root_object
+      return parts if parts.any? { |part| part.equal?(item) } || parts.none? { |part| part.equal?(@_replaced_data) }
+
+      parts + [item]
+    end
+
+    # Identifies the template for cache keys: a digest of its location, the view path its
+    # partials resolve from, its source and its block
+    def rabl_template_identity
+      @_template_identity ||= begin
+        location = @_options[:source_location]
+
+        if @_options[:parent_engine] && (location || !@_source)
+          # Within one render, a template's location determines its source
+          # (nested lookups rather than an Array key, as this runs for every item)
+          memo = (rabl_identity_memo[location] ||= {})
+          memo = (memo[view_path] ||= {})
+
+          if @_block_identity
+            block, parent = @_block_identity
+            memo = (memo[block] ||= {})
+            memo[parent && parent.rabl_template_identity] ||= rabl_template_digest
+          else
+            memo[:template] ||= rabl_template_digest
+          end
+        else
+          rabl_template_digest
+        end
+      end
+    end
+
     protected
+      def rabl_template_digest
+        root = TemplateCacheKey.root
+        view_paths = Array(view_path).map { |path| TemplateCacheKey.path(path, root) }
+        TemplateCacheKey.digest([TemplateCacheKey.path(@_options[:source_location], root), view_paths, @_source, rabl_block_identity(root)])
+      end
+
+      # Returns the digest for key, computing it once per render: the memo is kept by the
+      # top-level engine, so the items of a collection share their sub-templates' digests
+      def rabl_memoized_digest(key)
+        rabl_identity_memo[key] ||= yield
+      end
+
+      def rabl_identity_memo
+        @_identity_memo ||= (parent = @_options[:parent_engine]) ? parent.rabl_identity_memo : {}
+      end
+
+      def rabl_template_engine
+        self
+      end
+
+      # Identifies the block that defines this engine, if any: its location and the
+      # template that defined it
+      def rabl_block_identity(root = TemplateCacheKey.root)
+        return unless @_block_identity
+
+        block, parent = @_block_identity
+        location = block.source_location
+        location &&= [TemplateCacheKey.path(location[0], root), location[1], location.size > 2 ? location[2] : TemplateCacheKey.column(block)]
+        [location, parent && parent.rabl_template_identity]
+      end
+
       # Returns a guess at the default object for this template
       # default_object => @user
       def default_object
@@ -331,25 +562,43 @@ module Rabl
         (context_scope.params if context_scope.respond_to?(:params)) || {}
       end
 
-      # Returns data as json embraced with callback when detected
-      # format_json({ :foo => "bar" }) => "test({ foo : 'bar' })"
-      # format_json("{ foo : "bar" }") => "test({ foo : 'bar' })"
+      # Returns data as json
+      # format_json({ :foo => "bar" }) => "{\"foo\":\"bar\"}"
       def format_json(json_output)
         unless json_output.is_a?(String)
           json_engine = Rabl.configuration.json_engine
-          json_output = if json_engine.respond_to?(:dump)
+          json_output = if defined?(::Oj) && json_engine.equal?(::Oj)
+            oj_options = Rabl.configuration.oj_dump_options
+            oj_options.empty? ? ::Oj.dump(json_output) : ::Oj.dump(json_output, oj_options)
+          elsif json_engine.respond_to?(:dump)
             json_engine.dump(json_output)
           else
             json_engine.encode(json_output)
           end
         end
 
-        use_callback = Rabl.configuration.enable_json_callbacks && request_params[:callback].present?
-        json_output = "#{request_params[:callback]}(#{json_output})" if use_callback
-
         json_output
       end
 
+      # Returns json embraced with the request's callback when callbacks are enabled
+      # and the callback name is valid, otherwise the json unchanged
+      # rabl_wrap_json_callback("{}") => "/**/test({})"
+      def rabl_wrap_json_callback(json)
+        callback = rabl_json_callback_name unless @_skip_json_callback
+        callback ? "/**/#{callback}(#{json})" : json
+      end
+
+      # Returns the request's callback parameter if callbacks are enabled and it is a valid name
+      def rabl_json_callback_name
+        return unless Rabl.configuration.enable_json_callbacks
+
+        callback = request_params[:callback]
+        return unless callback.is_a?(String) && callback.length <= RABL_JSON_CALLBACK_MAX_LENGTH
+        return unless callback.ascii_only? && callback =~ RABL_JSON_CALLBACK_NAME
+
+        callback
+      end
+
       # Augments respond to supporting context_scope methods
       def respond_to?(name, include_private = false)
         context_scope.respond_to?(name, include_private) || super
@@ -426,21 +675,88 @@ module Rabl
       end
 
       def eval_source(locals, &block)
-        return unless @_source.present?
+        source = @_source
+        # A UTF-8 byte order mark (as some editors save files) isn't part of the template. It is
+        # checked by its bytes first, as it is invalid in the encoding the source may be read in
+        # (US-ASCII under LANG=C), where reading the source as text raises.
+        source = source.byteslice(3..-1) if source.is_a?(String) && source.getbyte(0) == 0xEF && source.getbyte(1) == 0xBB && source.getbyte(2) == 0xBF
+        return unless source.present?
 
-        msg = "cached_source_#{@_source.hash.abs}"
+        # One method per source and location, so blocks report the file that defined them
+        line = @_options[:source_line] || 1
+        msg = "cached_source_#{[@_source, @_options[:source_location], line].hash.abs}"
 
         unless self.respond_to? msg then
-          src = "def #{msg} locals, &block\n#{@_source}\nend"
+          src = "def #{msg} locals, &block\n#{source}\nend"
 
-          if @_options[:source_location]
-            self.class.class_eval(src, @_options[:source_location])
-          else
-            self.class.class_eval(src)
-          end
+          # The def line comes before the template's first line, so errors report the
+          # template's own line numbers
+          self.class.class_eval(src, @_options[:source_location] || "(eval)", line - 1)
         end
 
         send msg, locals, &block
       end
+
+      # Hash#to_xml and Array#to_xml come from ActiveSupport (which uses the builder gem);
+      # Rails loads them, but other apps may not have.
+      def load_xml_support!
+        return if defined?(::Builder::XmlMarkup) && {}.respond_to?(:to_xml) && [].respond_to?(:to_xml)
+
+        require 'active_support/core_ext/array/conversions'
+        require 'active_support/core_ext/hash/conversions'
+
+        begin
+          require 'builder' unless defined?(::Builder::XmlMarkup)
+        rescue LoadError
+          raise LoadError, "rabl needs the builder gem to render XML; add `gem 'builder'` to your Gemfile"
+        end
+      end
+
+      # Returns a copy of the data with each Array in it, at any depth, as an XmlArray; arrays
+      # with a to_xml of their own are left as they are
+      def xml_arrays(data, children_names = {})
+        case data
+        when Hash
+          copy = data.dup
+          data.each { |key, value| copy[key] = xml_arrays(value, children_names) }
+          copy
+        when Array
+          return data unless data.method(:to_xml).owner == Array
+
+          XmlArray.new(data.map { |value| xml_arrays(value, children_names) }, children_names)
+        else
+          data
+        end
+      end
+
+      # attribute, node, child, glue and extends build the template's settings, which are read while
+      # it renders (#477). Called then (e.g. inside a node block), they warn; attribute, node, child
+      # and glue work as before, and extends is ignored, since its settings (view path included)
+      # would otherwise be the node's value. Returns true when the template is rendering.
+      # ceiling: warns on every call, so a misuse inside a large collection repeats the warning;
+      # dedupe by call site if that turns out to be noisy.
+      def warn_if_rendering(method_name)
+        return false unless @_rendering
+
+        effect = method_name == :extends ? "is ignored" : "changes the template for the rest of the render"
+        site = caller.find { |line| !line.start_with?(__FILE__) }.to_s.sub(/:in .*\z/m, '')
+        Kernel.warn "rabl: #{method_name} called while the template renders (e.g. inside a node block) at #{site} " \
+                    "#{effect}; to render another template there, use partial(\"template\", :object => object)"
+        true
+      end
+
+      # Ruby folds `child :posts => :items, :if => cond` into a single hash, so the options
+      # arrive inside the data. They are split out only when no options were given separately
+      # and what remains is a single alias (`data => name`); any other hash is left as data.
+      # split_folded_options({ :posts => :items, :if => true }, {}, [:if]) => [{ :posts => :items }, { :if => true }]
+      def split_folded_options(data, options, option_keys)
+        return [data, options] unless data.is_a?(Hash) && options.blank?
+
+        found = data.keys & option_keys
+        alias_data = data.except(*found)
+        return [data, options] unless found.any? && alias_data.size == 1 && is_name_value?(alias_data.values.first)
+
+        [alias_data, data.slice(*found)]
+      end
   end
 end

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