dry-view 0.5.1 → 0.7.1

data/lib/dry/view/context.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "dry/core/equalizer"
+require_relative "decorated_attributes"
+
+module Dry
+  class View
+    # Provides a baseline environment across all the templates, parts and scopes
+    # in a given rendering.
+    #
+    # @abstract Subclass this and add your own methods (along with a custom
+    #   `#initialize` if you wish to inject dependencies)
+    #
+    # @api public
+    class Context
+      include Dry::Equalizer(:_options)
+      include DecoratedAttributes
+
+      attr_reader :_render_env, :_options
+
+      # Returns a new instance of Context
+      #
+      # In subclasses, you should include an `**options` parameter and pass _all
+      # arguments_ to `super`. This allows Context to make copies of itself
+      # while preserving your dependencies.
+      #
+      # @example
+      #   class MyContext < Dry::View::Context
+      #     # Injected dependency
+      #     attr_reader :assets
+      #
+      #     def initialize(assets:, **options)
+      #       @assets = assets
+      #       super
+      #     end
+      #   end
+      #
+      # @api public
+      def initialize(render_env: nil, **options)
+        @_render_env = render_env
+        @_options = options
+      end
+
+      # @api private
+      def for_render_env(render_env)
+        return self if render_env == _render_env
+
+        self.class.new(**_options.merge(render_env: render_env))
+      end
+
+      # Returns a copy of the Context with new options merged in.
+      #
+      # This may be useful to supply values for dependencies that are _optional_
+      # when initializing your custom Context subclass.
+      #
+      # @example
+      #   class MyContext < Dry::View::Context
+      #     # Injected dependencies (request is optional)
+      #     attr_reader :assets, :request
+      #
+      #     def initialize(assets:, request: nil, **options)
+      #       @assets = assets
+      #       @request = reuqest
+      #       super
+      #     end
+      #   end
+      #
+      #   my_context = MyContext.new(assets: assets)
+      #   my_context_with_request = my_context.with(request: request)
+      #
+      # @api public
+      def with(**new_options)
+        self.class.new(
+          render_env: _render_env,
+          **_options.merge(new_options)
+        )
+      end
+    end
+  end
+end

data/lib/dry/view/decorated_attributes.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Dry
+  class View
+    # Decorates attributes in Parts.
+    module DecoratedAttributes
+      # @api private
+      def self.included(klass)
+        klass.extend ClassInterface
+      end
+
+      # Decorated attributes class-level interface.
+      module ClassInterface
+        # @api private
+        MODULE_NAME = :DecoratedAttributes
+
+        # Decorates the provided attributes, wrapping them in Parts using the
+        # current render environment.
+        #
+        # @example
+        #   class Article < Dry::View::Part
+        #     decorate :feature_image
+        #     decorate :author as: :person
+        #   end
+        #
+        # @param names [Array<Symbol>] the attribute names
+        # @param options [Hash] the options to pass to the Part Builder
+        # @option options [Symbol, Class] :as an alternative name or class to use when finding a
+        #   matching Part
+        #
+        # @api public
+        def decorate(*names, **options)
+          decorated_attributes.decorate(*names, **options)
+        end
+
+        private
+
+        def decorated_attributes
+          if const_defined?(MODULE_NAME, false)
+            const_get(MODULE_NAME)
+          else
+            const_set(MODULE_NAME, Attributes.new).tap do |mod|
+              prepend mod
+            end
+          end
+        end
+      end
+
+      # @api private
+      class Attributes < Module
+        def initialize(*)
+          @names = Set.new
+          super
+        end
+
+        def decorate(*names, **options)
+          @names += names
+
+          class_eval do
+            names.each do |name|
+              define_method name do
+                attribute = super()
+
+                if _render_env && attribute
+                  _render_env.part(name, attribute, **options)
+                else
+                  attribute
+                end
+              end
+            end
+          end
+        end
+
+        def inspect
+          %(#<#{self.class.name}#{@names.to_a.sort.inspect}>)
+        end
+      end
+    end
+  end
+end

data/lib/dry/view/errors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Dry
+  class View
+    # Error raised when critical settings are not configured
+    #
+    # @api private
+    class UndefinedConfigError < StandardError
+      def initialize(key)
+        super("no +#{key}+ configured")
+      end
+    end
+
+    # Error raised when template could not be found within a view's configured
+    # paths
+    #
+    # @api private
+    class TemplateNotFoundError < StandardError
+      def initialize(template_name, lookup_paths)
+        msg = [
+          "Template +#{template_name}+ could not be found in paths:",
+          lookup_paths.map { |path| " - #{path}" }
+        ].join("\n\n")
+
+        super(msg)
+      end
+    end
+  end
+end

data/lib/dry/view/exposure.rb

@@ -1,12 +1,17 @@
-require 'dry-equalizer'
+# frozen_string_literal: true
+
+require "dry/core/equalizer"
 
 module Dry
-  module View
+  class View
+    # An exposure defined on a view
+    #
+    # @api private
     class Exposure
       include Dry::Equalizer(:name, :proc, :object, :options)
 
-      EXPOSURE_DEPENDENCY_PARAMETER_TYPES = [:req, :opt].freeze
-      INPUT_PARAMETER_TYPES = [:key, :keyreq, :keyrest].freeze
+      EXPOSURE_DEPENDENCY_PARAMETER_TYPES = %i[req opt].freeze
+      INPUT_PARAMETER_TYPES = %i[key keyreq keyrest].freeze
 
       attr_reader :name
       attr_reader :proc
@@ -21,7 +26,7 @@ module Dry
       end
 
       def bind(obj)
-        self.class.new(name, proc, obj, options)
+        self.class.new(name, proc, obj, **options)
       end
 
       def dependency_names
@@ -44,6 +49,14 @@ module Dry
         end
       end
 
+      def for_layout?
+        options.fetch(:layout) { false }
+      end
+
+      def decorate?
+        options.fetch(:decorate) { true }
+      end
+
       def private?
         options.fetch(:private) { false }
       end
@@ -63,23 +76,31 @@ module Dry
       private
 
       def call_proc(input, locals)
-        args = proc_args(input, locals)
-
-        if proc.is_a?(Method)
-          proc.(*args)
+        args, keywords = proc_args(input, locals)
+
+        if keywords.empty?
+          if proc.is_a?(Method)
+            proc.(*args)
+          else
+            object.instance_exec(*args, &proc)
+          end
         else
-          object.instance_exec(*args, &proc)
+          if proc.is_a?(Method)
+            proc.(*args, **keywords)
+          else
+            object.instance_exec(*args, **keywords, &proc)
+          end
         end
       end
 
       def proc_args(input, locals)
         dependency_args = proc_dependency_args(locals)
-        input_args = proc_input_args(input)
+        keywords = proc_input_args(input)
 
-        if input_args.any?
-          dependency_args << input_args
+        if keywords.empty?
+          [dependency_args, {}]
         else
-          dependency_args
+          [dependency_args, keywords]
         end
       end
 

data/lib/dry/view/exposures.rb

@@ -1,9 +1,14 @@
+# frozen_string_literal: true
+
 require "tsort"
+require "dry/core/equalizer"
 require "dry/view/exposure"
 
 module Dry
-  module View
+  class View
+    # @api private
     class Exposures
+      include Dry::Equalizer(:exposures)
       include TSort
 
       attr_reader :exposures
@@ -25,7 +30,7 @@ module Dry
       end
 
       def add(name, proc = nil, **options)
-        exposures[name] = Exposure.new(name, proc, options)
+        exposures[name] = Exposure.new(name, proc, **options)
       end
 
       def import(name, exposure)
@@ -40,12 +45,19 @@ module Dry
         self.class.new(bound_exposures)
       end
 
-      def locals(input)
+      def call(input)
+        # rubocop:disable Style/MultilineBlockChain
         tsort.each_with_object({}) { |name, memo|
-          memo[name] = self[name].(input, memo) if exposures.key?(name)
-        }.each_with_object({}) { |(name, val), memo|
-          memo[name] = val unless self[name].private?
+          next unless (exposure = self[name])
+
+          value = exposure.(input, memo)
+          value = yield(value, exposure) if block_given?
+
+          memo[name] = value
+        }.each_with_object({}) { |(name, value), memo|
+          memo[name] = value unless self[name].private?
         }
+        # rubocop:enable Style/MultilineBlockChain
       end
 
       private

data/lib/dry/view/part.rb

@@ -1,77 +1,205 @@
-require 'dry-equalizer'
-require 'dry/view/scope'
-require 'dry/view/missing_renderer'
+# frozen_string_literal: true
+
+require "dry/core/equalizer"
+require_relative "decorated_attributes"
+require_relative "render_environment_missing"
 
 module Dry
-  module View
+  class View
+    # Decorates an exposure value and provides a place to encapsulate
+    # view-specific behavior alongside your application's domain objects.
+    #
+    # @abstract Subclass this and provide your own methods adding view-specific
+    #   behavior. You should not override `#initialize`.
+    #
+    # @see https://dry-rb.org/gems/dry-view/parts/
+    #
+    # @api public
     class Part
+      # @api private
       CONVENIENCE_METHODS = %i[
+        format
         context
         render
+        scope
         value
       ].freeze
 
-      include Dry::Equalizer(:_name, :_value, :_decorator, :_context, :_renderer)
+      include Dry::Equalizer(:_name, :_value, :_render_env)
+      include DecoratedAttributes
 
+      # The part's name. This comes from the exposure supplying the value.
+      #
+      # @return [Symbol] name
+      #
+      # @api public
       attr_reader :_name
 
+      # The decorated value. This is the value returned from the exposure.
+      #
+      # @overload _value
+      #   Returns the value.
+      # @overload value
+      #   A convenience alias for `_value`. Is available unless the value itself
+      #   responds to `#value`.
+      #
+      # @return [Object] value
+      #
+      # @api public
       attr_reader :_value
 
-      attr_reader :_context
-
-      attr_reader :_renderer
-
-      attr_reader :_decorator
+      # The current render environment
+      #
+      # @return [RenderEnvironment] render environment
+      #
+      # @api private
+      attr_reader :_render_env
 
-      attr_reader :_decorated_attributes
+      # Determins a part name (when initialized without one). Intended for use
+      # only while unit testing Parts.
+      #
+      # @api private
+      def self.part_name(inflector)
+        name ? inflector.underscore(inflector.demodulize(name)) : "part"
+      end
 
+      # Returns a new Part instance
+      #
+      # @param name [Symbol] part name
+      # @param value [Object] the value to decorate
+      # @param render_env [RenderEnvironment] render environment
+      #
       # @api public
-      def self.decorate(*names, **options)
-        names.each do |name|
-          decorated_attributes[name] = options
-        end
+      def initialize(
+        render_env: RenderEnvironmentMissing.new,
+        name: self.class.part_name(render_env.inflector),
+        value:
+      )
+        @_name = name
+        @_value = value
+        @_render_env = render_env
       end
 
-      # @api private
-      def self.decorated_attributes
-        @decorated_attributes ||= {}
+      # The template format for the current render environment.
+      #
+      # @overload _format
+      #   Returns the format.
+      # @overload format
+      #   A convenience alias for `#_format.` Is available unless the value
+      #   itself responds to `#format`.
+      #
+      # @return [Symbol] format
+      #
+      # @api public
+      def _format
+        _render_env.format
       end
 
-      # FIXME: does MissingRenderer.new lead to needless allocations of MissingRenderer? We only need one globally.
-      def initialize(name:, value:, decorator: Dry::View::Decorator.new, renderer: MissingRenderer.new, context: nil)
-        @_name = name
-        @_value = value
-        @_context = context
-        @_renderer = renderer
-        @_decorator = decorator
-        @_decorated_attributes = {}
+      # The context object for the current render environment
+      #
+      # @overload _context
+      #   Returns the context.
+      # @overload context
+      #   A convenience alias for `#_context`. Is available unless the value
+      #   itself responds to `#context`.
+      #
+      # @return [Context] context
+      #
+      # @api public
+      def _context
+        _render_env.context
       end
 
+      # Renders a new partial with the part included in its locals.
+      #
+      # @overload _render(partial_name, as: _name, **locals, &block)
+      #   Renders the partial.
+      # @overload render(partial_name, as: _name, **locals, &block)
+      #   A convenience alias for `#_render`. Is available unless the value
+      #   itself responds to `#render`.
+      #
+      # @param partial_name [Symbol, String] partial name
+      # @param as [Symbol] the name for the Part to assume in the partial's locals. Defaults to
+      #   the Part's `_name`.
+      # @param locals [Hash<Symbol, Object>] other locals to provide the partial
+      #
+      # @return [String] rendered partial
+      #
+      # @api public
+      # rubocop:disable Naming/UncommunicativeMethodParamName
       def _render(partial_name, as: _name, **locals, &block)
-        _renderer.partial(partial_name, _render_scope(as, locals), &block)
+        _render_env.partial(partial_name, _render_env.scope({as => self}.merge(locals)), &block)
+      end
+      # rubocop:enable Naming/UncommunicativeMethodParamName
+
+      # Builds a new scope with the part included in its locals.
+      #
+      # @overload _scope(scope_name = nil, **locals)
+      #   Builds the scope.
+      # @overload scope(scope_name = nil, **locals)
+      #   A convenience alias for `#_scope`. Is available unless the value
+      #   itself responds to `#scope`.
+      #
+      # @param scope_name [Symbol, nil] scope name, used by the scope builder to determine the
+      #   scope class
+      # @param locals [Hash<Symbol, Object>] other locals to provide the partial
+      #
+      # @return [Dry::View::Scope] scope
+      #
+      # @api public
+      def _scope(scope_name = nil, **locals)
+        _render_env.scope(scope_name, {_name => self}.merge(locals))
       end
 
+      # Returns a string representation of the value
+      #
+      # @return [String]
+      #
+      # @api public
       def to_s
         _value.to_s
       end
 
-      def new(klass = (self.class), name: (_name), value: (_value), **options)
+      # Builds a new a part with the given parameters
+      #
+      # This is helpful for manually constructing a new part object that
+      # maintains the current render environment.
+      #
+      # However, using `.decorate` is preferred for declaring attributes that
+      # should also be decorated as parts.
+      #
+      # @see DecoratedAttributes::ClassInterface#decorate
+      #
+      # @param klass [Class] part class to use (defaults to the part's class)
+      # @param name [Symbol] part name (defaults to the part's name)
+      # @param value [Object] value to decorate (defaults to the part's value)
+      # @param options[Hash<Symbol, Object>] other options to provide when initializing the new part
+      #
+      # @api public
+      def new(klass = self.class, name: _name, value: _value, **options)
         klass.new(
           name: name,
           value: value,
-          context: _context,
-          renderer: _renderer,
-          decorator: _decorator,
-          **options,
+          render_env: _render_env,
+          **options
         )
       end
 
+      # Returns a string representation of the part
+      #
+      # @return [String]
+      #
+      # @api public
+      def inspect
+        %(#<#{self.class.name} name=#{_name.inspect} value=#{_value.inspect}>)
+      end
+
       private
 
+      # Handles missing methods. If the `_value` responds to the method, then
+      # the method will be sent to the value.
       def method_missing(name, *args, &block)
-        if self.class.decorated_attributes.key?(name)
-          _resolve_decorated_attribute(name)
-        elsif _value.respond_to?(name)
+        if _value.respond_to?(name)
           _value.public_send(name, *args, &block)
         elsif CONVENIENCE_METHODS.include?(name)
           __send__(:"_#{name}", *args, &block)
@@ -79,25 +207,10 @@ module Dry
           super
         end
       end
+      ruby2_keywords(:method_missing) if respond_to?(:ruby2_keywords, true)
 
-      def _render_scope(name, **locals)
-        Scope.new(
-          locals: locals.merge(name => self),
-          context: _context,
-          renderer: _renderer,
-        )
-      end
-
-      def _resolve_decorated_attribute(name)
-        _decorated_attributes.fetch(name) {
-          _decorated_attributes[name] = _decorator.(
-            name,
-            _value.__send__(name),
-            renderer: _renderer,
-            context: _context,
-            **self.class.decorated_attributes[name],
-          )
-        }
+      def respond_to_missing?(name, include_private = false)
+        CONVENIENCE_METHODS.include?(name) || _value.respond_to?(name, include_private) || super
       end
     end
   end