hanami-view 2.3.1 → 3.0.0

data/lib/hanami/view/rendering.rb

@@ -3,54 +3,64 @@
 module Hanami
   class View
     # @api private
-    # @since 2.1.0
     class Rendering
       # @api private
-      # @since 2.1.0
-      attr_reader :config, :format
+      attr_reader :format
 
-      # @api private
-      # @since 2.1.0
       attr_reader :inflector, :part_builder, :scope_builder
 
-      # @api private
-      # @since 2.1.0
+      attr_reader :part_class, :part_namespace, :scope_class, :scope_namespace
+
+      # Stable identity for the underlying config snapshot.
+      attr_reader :cache_key
+
       attr_reader :context, :renderer
 
-      # @api private
-      # @since 2.1.0
-      def initialize(config:, format:, context:)
-        @config = config
+      def initialize(config_data:, format:, context:)
         @format = format
 
-        @inflector = config.inflector
-        @part_builder = config.part_builder
-        @scope_builder = config.scope_builder
+        @inflector = config_data.inflector
+        @part_builder = config_data.part_builder
+        @scope_builder = config_data.scope_builder
+
+        @part_class = config_data.part_class
+        @part_namespace = config_data.part_namespace
+        @scope_class = config_data.scope_class
+        @scope_namespace = config_data.scope_namespace
+        @cache_key = config_data.object_id
 
         @context = context.dup_for_rendering(self)
-        @renderer = Renderer.new(config)
+        @renderer = Renderer.new(config_data)
+      end
+
+      # Returns the resolved name of the template or partial currently being rendered, or nil if
+      # no render is in progress.
+      #
+      # @return [String, nil]
+      def current_template_name
+        renderer.current_template_name
+      end
+
+      # Returns the stack of resolved names for the templates and partials currently being
+      # rendered.
+      #
+      # @return [Array<String>]
+      def current_template_names
+        renderer.current_template_names
       end
 
-      # @api private
-      # @since 2.1.0
       def template(name, scope, &block)
         renderer.template(name, format, scope, &block)
       end
 
-      # @api private
-      # @since 2.1.0
       def partial(name, scope, &block)
         renderer.partial(name, format, scope, &block)
       end
 
-      # @api private
-      # @since 2.1.0
       def part(name, value, as: nil)
         part_builder.(name, value, as: as, rendering: self)
       end
 
-      # @api private
-      # @since 2.1.0
       def scope(name = nil, locals) # rubocop:disable Style/OptionalArguments
         scope_builder.(name, locals: locals, rendering: self)
       end

data/lib/hanami/view/rendering_missing.rb

@@ -8,47 +8,44 @@ module Hanami
     # @api private
     # @since 2.1.0
     class RenderingMissing
-      # @api private
-      # @since 2.1.0
       def format
         raise RenderingMissingError
       end
 
-      # @api private
-      # @since 2.1.0
       def context
         raise RenderingMissingError
       end
 
-      # @api private
-      # @since 2.1.0
       def part(_name, _value, **_options)
         raise RenderingMissingError
       end
 
-      # @api private
-      # @since 2.1.0
       def scope(_name = nil, _locals) # rubocop:disable Style/OptionalArguments
         raise RenderingMissingError
       end
 
-      # @api private
-      # @since 2.1.0
       def template(_name, _scope)
         raise RenderingMissingError
       end
 
-      # @api private
-      # @since 2.1.0
       def partial(_name, _scope)
         raise RenderingMissingError
       end
 
-      # @api private
-      # @since 2.1.0
       def inflector
         @inflector ||= Dry::Inflector.new
       end
+
+      def current_template_name
+        nil
+      end
+
+      def current_template_names
+        EMPTY_TEMPLATE_NAMES
+      end
+
+      EMPTY_TEMPLATE_NAMES = [].freeze
+      private_constant :EMPTY_TEMPLATE_NAMES
     end
   end
 end

data/lib/hanami/view/scope.rb

@@ -19,7 +19,7 @@ module Hanami
     # @since 2.1.0
     class Scope
       # @api private
-      CONVENIENCE_METHODS = %i[format context locals].freeze
+      CONVENIENCE_METHODS = %i[format context locals template_name].freeze
 
       include Dry::Equalizer(:_name, :_locals, :_rendering)
 
@@ -35,10 +35,10 @@ module Hanami
       #
       # @overload _locals
       #   Returns the locals.
+      #   @return [Hash{Symbol => Object}]
       # @overload locals
       #   A convenience alias for `#_locals.` Is available unless there is a local named `locals`
-      #
-      # @return [Hash[<Symbol, Object>]
+      #   @return [Hash{Symbol => Object}]
       #
       # @api public
       # @since 2.1.0
@@ -76,16 +76,16 @@ module Hanami
       #   Renders a partial using the scope.
       #
       #   @param partial_name [Symbol, String] partial name
-      #   @param locals [Hash<Symbol, Object>] partial locals
+      #   @param locals [Hash{Symbol => Object}] partial locals
       #   @yieldreturn [String] string content to include where the partial calls `yield`
+      #   @return [String] the rendered partial output
       #
       # @overload render(**locals, &block)
       #   Renders a partial (named after the scope's own name) using the scope.
       #
-      #   @param locals[Hash<Symbol, Object>] partial locals
+      #   @param locals [Hash{Symbol => Object}] partial locals
       #   @yieldreturn [String] string content to include where the partial calls `yield`
-      #
-      # @return [String] the rendered partial output
+      #   @return [String] the rendered partial output
       #
       # @api public
       # @since 2.1.0
@@ -120,11 +120,10 @@ module Hanami
       #
       # @overload _format
       #   Returns the format.
+      #   @return [Symbol] format
       # @overload format
-      #   A convenience alias for `#_format.` Is available unless there is a
-      #   local named `format`
-      #
-      # @return [Symbol] format
+      #   A convenience alias for `#_format.` Is available unless there is a local named `format`.
+      #   @return [Symbol] format
       #
       # @api public
       # @since 2.1.0
@@ -136,11 +135,10 @@ module Hanami
       #
       # @overload _context
       #   Returns the context.
+      #   @return [Context] context
       # @overload context
-      #   A convenience alias for `#_context`. Is available unless there is a
-      #   local named `context`.
-      #
-      # @return [Context] context
+      #   A convenience alias for `#_context`. Is available unless there is a local named `context`.
+      #   @return [Context] context
       #
       # @api public
       # @since 2.1.0
@@ -148,6 +146,22 @@ module Hanami
         _rendering.context
       end
 
+      # Returns the name of the template or partial currently being rendered.
+      #
+      # @overload _template_name
+      #   Returns the current template name.
+      #   @return [String, nil]
+      # @overload template_name
+      #   A convenience alias for `#_template_name`. Is available unless there is a local named
+      #   `template_name`.
+      #   @return [String, nil]
+      #
+      # @api public
+      # @since 3.0.0
+      def _template_name
+        _rendering.current_template_name
+      end
+
       private
 
       # Handles missing methods, according to the following rules:

data/lib/hanami/view/scope_builder.rb

@@ -17,7 +17,7 @@ module Hanami
         #
         # @api public
         # @since 2.1.0
-        def call(name = nil, locals:, rendering:) # rubocop:disable Style/OptionalArguments
+        def call(name = nil, locals:, rendering:)
           klass = scope_class(name, rendering: rendering)
 
           klass.new(name: name, locals: locals, rendering: rendering)
@@ -27,11 +27,11 @@ module Hanami
 
         def scope_class(name = nil, rendering:)
           if name.nil?
-            rendering.config.scope_class
+            rendering.scope_class
           elsif name.is_a?(Class)
             name
           else
-            View.cache.fetch_or_store(name, rendering.config) do
+            View.cache.fetch_or_store(name, rendering.cache_key) do
               resolve_scope_class(name: name, rendering: rendering)
             end
           end
@@ -40,12 +40,12 @@ module Hanami
         def resolve_scope_class(name:, rendering:)
           name = rendering.inflector.camelize(name.to_s)
 
-          namespace = rendering.config.scope_namespace
+          namespace = rendering.scope_namespace
 
           # Give autoloaders a chance to act
           begin
             klass = namespace.const_get(name)
-          rescue NameError # rubocop:disable Lint/HandleExceptions
+          rescue NameError # rubocop:disable Lint/SuppressedException
           end
 
           if !klass && namespace.const_defined?(name, false)
@@ -55,7 +55,7 @@ module Hanami
           if klass && klass < Scope
             klass
           else
-            rendering.config.scope_class
+            rendering.scope_class
           end
         end
       end

data/lib/hanami/view/tilt/haml_adapter.rb

@@ -34,7 +34,7 @@ module Hanami
         Template = Temple::Templates::Tilt(
           ::Haml::Engine,
           use_html_safe: true,
-          capture_generator: HTMLSafeStringBuffer,
+          capture_generator: HTMLSafeStringBuffer
         )
       end
     end

data/lib/hanami/view/tilt/slim_adapter.rb

@@ -34,7 +34,7 @@ module Hanami
         Template = Temple::Templates::Tilt(
           ::Slim::Engine,
           use_html_safe: true,
-          capture_generator: HTMLSafeStringBuffer,
+          capture_generator: HTMLSafeStringBuffer
         )
       end
     end

data/lib/hanami/view/tilt.rb

@@ -10,14 +10,24 @@ module Hanami
       # @api private
       # @since 2.1.0
       Mapping = ::Tilt.default_mapping.dup.tap { |mapping|
-        # If "slim" has been required before "hanami/view", unregister Slim's non-lazy registered
-        # template, so our own template adapter (using register_lazy below) can take precedence.
-        mapping.unregister "slim"
+        # Unregister any existing mappings for the extensions we provide our own engines for.
+        #
+        # Tilt preferences non-lazy registrations over lazy ones (see `Tilt::Mapping#lookup`). So if
+        # "haml" or "slim" has been required before this mapping is built (each of which registers
+        # its own non-lazy mapping with Tilt), our own lazy-registered adapters below would be
+        # shadowed and never picked up, and templates would render without our specific required
+        # behavior.
+        #
+        # Unregistering first ensures our engines are always used, regardless of load order.
+        mapping.unregister "erb", "rhtml", "haml", "slim"
 
         # Register our own ERB template.
         mapping.register_lazy "Hanami::View::ERB::Template", "hanami/view/erb/template", "erb", "rhtml"
 
-        # Register ERB templates for Haml and Slim that set the `use_html_safe: true` option.
+        # Register templates for Haml and Slim that set the `use_html_safe: true` option.
+        #
+        # We register these lazily so that the optional "haml" and "slim" gems only need to be
+        # installed when their templates are actually used.
         #
         # Our template namespaces below have the "Adapter" suffix to work around a bug in Tilt's
         # `Mapping#const_defined?`, which (if slim was already required) would receive

data/lib/hanami/view/version.rb

@@ -3,7 +3,6 @@
 module Hanami
   class View
     # @api public
-    # @since 0.1.0
-    VERSION = "2.3.1"
+    VERSION = "3.0.0"
   end
 end

data/lib/hanami/view.rb

@@ -22,7 +22,6 @@ module Hanami
   # @since 2.1.0
   class View
     # @api private
-    # @since 2.1.0
     def self.gem_loader
       @gem_loader ||= Zeitwerk::Loader.new.tap do |loader|
         root = File.expand_path("..", __dir__)
@@ -32,12 +31,17 @@ module Hanami
           "#{root}/hanami-view.rb",
           "#{root}/hanami/view/version.rb",
           "#{root}/hanami/view/errors.rb",
+          # These adapters require the optional "haml" and "slim" gems. They are loaded lazily by
+          # Tilt (see Hanami::View::Tilt) only when their respective template engines are used;
+          # ignore them here to allow eager loading without those gems installed.
+          "#{root}/hanami/view/tilt/haml_adapter.rb",
+          "#{root}/hanami/view/tilt/slim_adapter.rb"
         )
         loader.inflector = Zeitwerk::GemInflector.new("#{root}/hanami-view.rb")
         loader.inflector.inflect(
           "erb" => "ERB",
           "html" => "HTML",
-          "html_safe_string_buffer" => "HTMLSafeStringBuffer",
+          "html_safe_string_buffer" => "HTMLSafeStringBuffer"
         )
       end
     end
@@ -45,7 +49,6 @@ module Hanami
     gem_loader.setup
 
     # @api private
-    # @since 2.1.0
     DEFAULT_RENDERER_OPTIONS = {default_encoding: "utf-8"}.freeze
 
     include Dry::Equalizer(:config, :exposures)
@@ -235,6 +238,23 @@ module Hanami
     # @!scope class
     setting :inflector, default: Dry::Inflector.new
 
+    # @overload config.decorate_exposures=(value)
+    #   Controls whether exposures are decorated by default.
+    #
+    #   When set to `true`, all exposures will be decorated with matching Parts unless explicitly
+    #   marked with `decorate: false`.
+    #
+    #   When set to `false` (the default), exposures will not be decorated unless explicitly marked
+    #   with `decorate: true`, or declared with `decorate`.
+    #
+    #   Defaults to `false`.
+    #
+    #   @param value [Boolean] whether to decorate exposures by default
+    #   @api public
+    #   @since 3.0.0
+    # @!scope class
+    setting :decorate_exposures, default: false
+
     # @overload config.renderer_options=(options)
     #   A hash of options to pass to the template engine. Template engines are
     #   provided by Tilt; see Tilt's documentation for what options your
@@ -273,7 +293,6 @@ module Hanami
     # @!endgroup
 
     # @api private
-    # @since 2.1.0
     def self.inherited(klass)
       super
 
@@ -288,13 +307,13 @@ module Hanami
     #   @param options [Hash] the exposure's options
     #   @option options [Boolean] :layout expose this value to the layout (defaults to false)
     #   @option options [Boolean] :decorate decorate this value in a matching Part (defaults to
-    #     true)
+    #     false, or the value of `config.decorate_exposures`)
     #   @option options [Symbol, Class] :as an alternative name or class to use when finding a
     #     matching Part
 
     # @overload expose(name, **options, &block)
     #   Define a value to be passed to the template. The return value of the
-    #   block will be decorated by a matching Part and passed to the template.
+    #   block will be passed to the template.
     #
     #   The block will be evaluated with the view instance as its `self`. The
     #   block's parameters will determine what it is given:
@@ -329,8 +348,8 @@ module Hanami
     #
     # @overload expose(name, **options)
     #   Define a value to be passed to the template, provided by an instance
-    #   method matching the name. The method's return value will be decorated by
-    #   a matching Part and passed to the template.
+    #   method matching the name. The method's return value will be passed to
+    #   the template.
     #
     #   The method's parameters will determine what it is given:
     #
@@ -369,8 +388,8 @@ module Hanami
     #
     # @overload expose(name, **options)
     #   Define a single value to pass through from the input data (when there is
-    #   no instance method matching the `name`). This value will be decorated by
-    #   a matching Part and passed to the template.
+    #   no instance method matching the `name`). This value will be passed to
+    #   the template.
     #
     #   @param name [Symbol] name for the exposure
     #   @macro exposure_options
@@ -380,7 +399,7 @@ module Hanami
     # @overload expose(*names, **options)
     #   Define multiple values to pass through from the input data (when there
     #   is no instance methods matching their names). These values will be
-    #   decorated by matching Parts and passed through to the template.
+    #   passed through to the template.
     #
     #   The provided options will be applied to all the exposures.
     #
@@ -411,12 +430,23 @@ module Hanami
       expose(*names, **options, private: true, &block)
     end
 
+    # Defines an exposure that will be decorated with a matching Part.
+    #
+    # This is a shorthand for `expose(..., decorate: true)`.
+    #
+    # @see expose
+    #
+    # @api public
+    # @since 2.1.0
+    def self.decorate(*names, **options, &block)
+      expose(*names, **options, decorate: true, &block)
+    end
+
     # Returns the defined exposures. These are unbound, since bound exposures
     # are only created when initializing a View instance.
     #
     # @return [Exposures]
     # @api private
-    # @since 2.1.0
     def self.exposures
       @exposures ||= Exposures.new
     end
@@ -512,13 +542,6 @@ module Hanami
     # @!endgroup
 
     # @api private
-    # @since 2.1.0
-    def self.layout_path(layout)
-      File.join(*[config.layouts_dir, layout].compact)
-    end
-
-    # @api private
-    # @since 2.1.0
     def self.cache
       Cache
     end
@@ -534,6 +557,7 @@ module Hanami
       self.class.config.finalize!
       ensure_config
 
+      @config_data = config.to_data
       @exposures = self.class.exposures.bind(self)
     end
 
@@ -550,8 +574,7 @@ module Hanami
     # @return [Exposures]
     #
     # @api private
-    # @since 2.1.0
-    def exposures
+    def exposures # rubocop:disable Style/TrivialAccessors
       @exposures
     end
 
@@ -566,16 +589,20 @@ module Hanami
     #
     # @api public
     # @since 2.1.0
-    def call(format: config.default_format, context: config.default_context, layout: config.layout, **input)
+    def call(format: config_data.default_format,
+             context: config_data.default_context,
+             layout: config_data.layout,
+             **input)
       rendering = self.rendering(format: format, context: context)
+      scope_class = config_data.scope
 
       locals = locals(rendering, input)
-      output = rendering.template(config.template, rendering.scope(config.scope, locals))
+      output = rendering.template(config_data.template, rendering.scope(scope_class, locals))
 
       if layout
         output = rendering.template(
-          self.class.layout_path(layout),
-          rendering.scope(config.scope, layout_locals(locals))
+          layout_path(layout),
+          rendering.scope(scope_class, layout_locals(locals))
         ) { output }
       end
 
@@ -583,13 +610,18 @@ module Hanami
     end
 
     # @api private
-    # @since 2.1.0
-    def rendering(format: config.default_format, context: config.default_context)
-      Rendering.new(config: config, format: format, context: context)
+    def rendering(format: config_data.default_format, context: config_data.default_context)
+      Rendering.new(config_data:, format:, context:)
     end
 
     private
 
+    # Frozen Data snapshot of the view's resolved configuration values.
+    # Used for fast hot-path reads during rendering.
+    #
+    # @api private
+    attr_reader :config_data
+
     def ensure_config
       raise UndefinedConfigError, :paths unless Array(config.paths).any?
       raise UndefinedConfigError, :template unless config.template
@@ -597,7 +629,7 @@ module Hanami
 
     def locals(rendering, input)
       exposures.(context: rendering.context, **input) do |value, exposure|
-        if exposure.decorate? && value
+        if exposure.decorate?(default: config_data.decorate_exposures) && value
           rendering.part(exposure.name, value, as: exposure.options[:as])
         else
           value
@@ -605,6 +637,11 @@ module Hanami
       end
     end
 
+    # @api private
+    def layout_path(layout)
+      File.join(*[config_data.layouts_dir, layout].compact)
+    end
+
     def layout_locals(locals)
       locals.each_with_object({}) do |(key, value), layout_locals|
         layout_locals[key] = value if exposures[key].for_layout?