sevgi-graphics 0.95.0 → 0.98.2

data/lib/sevgi/graphics/element.rb

@@ -5,51 +5,113 @@ module Sevgi
     # SVG element node used by the graphics DSL.
     #
     # @!method self.valid?(name)
-    #   Reports whether an SVG element name is known.
-    #   @param name [Symbol] SVG element name
+    #   Reports whether a candidate can dispatch as an SVG element name.
+    #   With Standard loaded, the name must be known; standalone Graphics accepts any valid XML name.
+    #   @param name [Object] candidate element name
     #   @return [Boolean]
+    #
+    # Dynamic SVG element methods accept text, content objects, and any number of attribute Hashes in one call. Hashes
+    # are applied from left to right; later values replace earlier values unless their names use the `+` update suffix.
     class Element
       # Builds an element node.
       # @param name [Symbol, String] SVG element name
+      # @param arguments [Array<Hash, String, Sevgi::Graphics::Content>] ordered content and attribute channels; every
+      #   Hash is applied through {Sevgi::Graphics::Attributes} from left to right
       # @param parent [Sevgi::Graphics::Element] parent element
       # @yield evaluates the drawing DSL in the new element
       # @yieldreturn [Object] ignored block result
       # @return [Sevgi::Graphics::Element]
       # @raise [Sevgi::ArgumentError] when an argument cannot be parsed as attributes or content
+      # @raise [Sevgi::ArgumentError] when the parent has a different concrete element class
       # @raise [Sevgi::ArgumentError] when the element name or an attribute is not valid XML
-      def self.element(name, *, parent:, &block) = new(name, **Dispatch.parse(name, *), parent:, &block)
+      def self.element(name, *arguments, parent:, &block)
+        validate_parent_class(self, parent)
+        new(name, **Dispatch.parse(name, *arguments), parent:, &block)
+      end
 
       # Builds an SVG root element.
+      # @param arguments [Array<Hash, String, Sevgi::Graphics::Content>] ordered content and attribute channels
       # @yield evaluates the drawing DSL in the root element
       # @yieldreturn [Object] ignored block result
       # @return [Sevgi::Graphics::Element]
-      # @raise [Sevgi::ArgumentError] when a root attribute is not valid XML
-      def self.root(*, &block) = element(:svg, *, parent: RootParent, &block)
+      # @raise [Sevgi::ArgumentError] when an argument is not a Hash, String, or Content
+      # @raise [Sevgi::ArgumentError] when a root attribute or content value is not valid XML
+      def self.root(*arguments, &block) = element(:svg, *arguments, parent: RootParent, &block)
 
       # Reports whether an element is the root element.
       # @param element [Sevgi::Graphics::Element] element to test
       # @return [Boolean]
-      def self.root?(element) = element.parent == RootParent
+      def self.root?(element) = Element.send(:tree_parent, element).equal?(RootParent)
+
+      def self.element_method?(name) = Dispatch.cached?(name)
+
+      private_class_method :element_method?
+
+      class << self
+        private
+
+        def attach(element, parent, index: nil)
+          children = tree_children(parent)
+          index ? children.insert(index, element) : children << element
+          element.instance_variable_set(:@parent, parent)
+        end
+
+        def detach(element)
+          parent = tree_parent(element)
+          tree_children(parent).delete(element) if parent.is_a?(element.class)
+          element.instance_variable_set(:@parent, DetachedParent)
+        end
+
+        def tree_children(element) = element.instance_variable_get(:@children)
+
+        def tree_parent(element) = element.instance_variable_get(:@parent)
+
+        def validate_parent(element, parent)
+          validate_parent_class(element.class, parent)
+        end
+
+        def validate_parent_class(element_class, parent)
+          return if parent.equal?(RootParent) || parent.instance_of?(element_class)
+
+          ArgumentError.("Element type does not match the parent type: #{element_class}")
+        end
+      end
 
       class << self
         require "sevgi/standard"
 
-        # Reports whether an SVG element name is known.
-        # @param name [Symbol] SVG element name
+        # Reports whether a candidate can dispatch as a known SVG element name.
+        # @param name [Object] candidate element name
         # @return [Boolean]
-        def valid?(name) = Standard.element?(name)
+        def valid?(name)
+          Standard.element?(name)
+        rescue Sevgi::ArgumentError
+          false
+        end
+
       rescue ::LoadError => e
         raise unless e.path == "sevgi/standard"
 
-        # Reports whether an SVG element name is known.
+        # Reports whether a candidate can dispatch as a valid XML element name.
+        # @param name [Object] candidate element name
         # @return [Boolean]
-        def valid?(...) = true
+        def valid?(name)
+          return false unless name.is_a?(::String) || name.is_a?(::Symbol)
+
+          XML.name(name, context: "SVG element name")
+          true
+        rescue Sevgi::ArgumentError
+          false
+        end
       end
 
       private_class_method :new
 
-      # Sentinel parent used by root SVG elements.
+      # Sentinel parents used by root and detached elements.
       RootParent = Object.new.tap { def it.inspect = "RootParent" }.freeze
+      DetachedParent = Object.new.tap { def it.inspect = "DetachedParent" }.freeze
+
+      private_constant :DetachedParent, :RootParent
 
       # SVG element method-name normalization.
       # @api private
@@ -61,6 +123,8 @@ module Sevgi
       end
 
       extend Ident
+      private_class_method :id
+      private_constant :Ident
 
       # Returns the SVG element name.
       # @return [Symbol]
@@ -70,17 +134,20 @@ module Sevgi
       # @return [Sevgi::Graphics::Attributes]
       attr_reader :attributes
 
-      # Returns child elements.
-      # @return [Array<Sevgi::Graphics::Element>]
-      attr_reader :children
+      # Returns a read-only snapshot of child elements in rendering order.
+      # @return [Array<Sevgi::Graphics::Element>] frozen child snapshot
+      def children = @children.dup.freeze
 
-      # Returns element content objects.
-      # @return [Array<Sevgi::Graphics::Content>]
-      attr_reader :contents
+      # Returns a read-only snapshot of element content objects in rendering order.
+      # @return [Array<Sevgi::Graphics::Content>] frozen content snapshot
+      def contents = @contents.dup.freeze
 
-      # Returns the parent element or root sentinel.
-      # @return [Sevgi::Graphics::Element, Object] parent element or root sentinel
-      attr_reader :parent
+      # Returns the parent element.
+      # @return [Sevgi::Graphics::Element, nil] parent element, or nil for a root or detached element
+      # @note Use `Root?` to distinguish a document root from a detached subtree root.
+      def parent
+        @parent if @parent.is_a?(self.class)
+      end
 
       # Creates an element.
       # @param name [Symbol] SVG element name
@@ -90,8 +157,12 @@ module Sevgi
       # @yield evaluates the drawing DSL in the new element
       # @yieldreturn [Object] ignored block result
       # @return [void]
+      # @raise [Sevgi::ArgumentError] when the parent has a different concrete element class
       # @raise [Sevgi::ArgumentError] when the element name or an attribute is not valid XML
+      # @api private
       def initialize(name, parent:, attributes: {}, contents: [], &block)
+        Element.send(:validate_parent, self, parent)
+
         unless name.is_a?(::String) || name.is_a?(::Symbol)
           ArgumentError.("XML element name must be a String or Symbol")
         end
@@ -99,23 +170,25 @@ module Sevgi
         @name = XML.name(name, context: "XML element name").to_sym
         @attributes = Attributes.new(attributes)
         @children = []
-        @contents = contents
+        @contents = contents.dup
         @parent = parent
 
-        parent.children << self unless self.class.root?(self)
+        Element.send(:attach, self, parent) unless Element.root?(self)
 
         instance_exec(&block) if block
       end
 
       # Dispatches SVG element DSL calls and caches valid element methods.
       # @param name [Symbol] missing method name
+      # @param arguments [Array<Hash, String, Sevgi::Graphics::Content>] ordered content and attribute channels; later
+      #   Hashes replace or update attributes assigned by earlier Hashes
       # @yield evaluates the drawing DSL in the dispatched child element
       # @yieldreturn [Object] ignored block result
       # @return [Sevgi::Graphics::Element]
       # @raise [NameError] when the name is not a valid SVG element
       # @raise [Sevgi::ArgumentError] when an argument cannot be parsed as attributes or content
-      def method_missing(name, *, &block)
-        Element.valid?(tag = Element.id(name)) ? Dispatch.(self, name, tag, *, &block) : super
+      def method_missing(name, *arguments, &block)
+        Element.valid?(tag = Element.send(:id, name)) ? Dispatch.(self, name, tag, *arguments, &block) : super
       end
 
       # Reports whether a missing method can dispatch to an SVG element.
@@ -124,9 +197,11 @@ module Sevgi
       # @return [Boolean]
       # @api private
       def respond_to_missing?(name, include_private = false)
-        Element.valid?(Element.id(name)) || super
+        Element.valid?(Element.send(:id, name)) || super
       end
 
+      private :method_missing, :respond_to_missing?
+
       # Element method-missing parser and cache.
       # @api private
       module Dispatch
@@ -142,33 +217,41 @@ module Sevgi
             Element.class_exec do
               define_method(method) { |*args, &block| self.class.element(tag, *args, parent: self, &block) }
             end
+
+            (@methods ||= {})[method] = Element.instance_method(method)
           end
 
           element.public_send(method, *, &)
         end
 
+        def cached?(method)
+          cached = @methods&.[](method)
+
+          cached && Element.method_defined?(method) && Element.instance_method(method) == cached
+        end
+
         # Parses element DSL arguments.
         # @param name [Symbol] SVG element name
-        # @param args [Array<Object>] positional DSL arguments
+        # @param args [Array<Object>] positional DSL arguments; Hashes are imported from left to right
         # @return [Hash] parsed :attributes and :contents
         # @raise [Sevgi::ArgumentError] when an argument is not a Hash, String, or Content
         def parse(name, *args)
-          attributes, contents = {}, []
+          attributes, contents = Attributes.new, []
 
           args.each do |arg|
             case arg
             when ::Hash
-              attributes = arg
+              attributes.merge!(arg)
             when ::String
               contents << Content.encoded(arg)
             when Content
               contents << arg
             else
-              ArgumentError.("Argument of element '#{name}' must be a Hash or String: #{arg}")
+              ArgumentError.("Argument of element '#{name}' must be a Hash, String, or Content: #{arg}")
             end
           end
 
-          {attributes:, contents:}
+          {attributes: attributes.to_h, contents:}
         end
       end
 

data/lib/sevgi/graphics/mixtures/call.rb

@@ -3,95 +3,281 @@
 module Sevgi
   module Graphics
     # Callable drawing module support.
-    # Extend a plain Ruby module with this API to make its public instance methods callable drawing steps.
+    # Extend a plain Ruby module with this API to make its public instance methods callable drawing steps. Name the
+    # method `call` when the module has a single drawing step; use descriptive method names when it has multiple steps.
+    # Base blocks add argument-independent shared SVG content once per invocation before the public drawing methods.
+    # Invocation does not change the configured module, so it may be frozen after its drawing steps are defined. A
+    # duplicate or clone owns an independent configuration snapshot; freezing a callable module prevents later base
+    # registration while leaving invocation available.
     # @example Define and call a drawing module
     #   Widget = Module.new do
     #     extend Sevgi::Graphics::Module
     #
-    #     def item(id)
-    #       rect(id:)
+    #     base { css ".widget" => { fill: "red" } }
+    #
+    #     def call(id)
+    #       draw id
     #     end
+    #
+    #     private
+    #
+    #     def draw(id) = rect id:, class: "widget"
     #   end
     #
-    #   SVG { Call(Widget, "box") }
+    #   Sevgi::Graphics.SVG { Call Widget, "box" }
     module Module
-      # Tracks newly defined methods as callable drawing candidates.
-      # Invocation runs unique methods that are still public, preserving tracked definition order.
-      # @param method [Symbol] method name Ruby reports as added
-      # @return [Array<Symbol>, nil]
-      def method_added(method)
-        super
+      # Ephemeral callable receiver that preserves a module's normal method lookup while forwarding drawing operations
+      # to the current element.
+      # @api private
+      class Context < ::BasicObject
+        # Creates a delegated callable receiver.
+        # @param callable [Module] callable module
+        # @param receiver [Sevgi::Graphics::Element] current drawing element
+        # @return [void]
+        def initialize(callable, receiver)
+          @callable = callable
+          @receiver = receiver
+        end
+
+        # Reports methods available through either callable composition or the drawing element.
+        # @param name [Symbol, String] method name
+        # @param include_private [Boolean] whether private methods count
+        # @return [Boolean]
+        def respond_to?(name, include_private = false) = respond_to_missing?(name, include_private)
 
-        _callables << method if public_method_defined?(method)
+        private
+
+        # Reports methods available through callable composition or receiver delegation.
+        # @param name [Symbol, String] method name
+        # @param include_private [Boolean] whether private methods count
+        # @return [Boolean]
+        def respond_to_missing?(name, include_private = false)
+          @callable.public_method_defined?(name) ||
+            (include_private &&
+              (@callable.protected_method_defined?(name) || @callable.private_method_defined?(name))) ||
+            @receiver.respond_to?(name, include_private)
+        end
+
+        # Forwards operations outside the callable module's lookup chain to the drawing element.
+        # @param name [Symbol] missing method name
+        # @param arguments [Array<Object>] positional arguments
+        # @param keywords [Hash] keyword arguments
+        # @param block [Proc, nil] forwarded block
+        # @return [Object] delegated result
+        def method_missing(name, *arguments, **keywords, &block)
+          @receiver.__send__(name, *arguments, **keywords, &block)
+        end
       end
 
-      # Class-level DSL for callable drawing modules.
-      # @api private
-      module DSL
-        # Registers a before or after hook.
-        # @param after [Boolean] true to register an after hook
-        # @return [Array<Proc>] hook list
-        def call(after = false, &block) = ((after ? _afters : _befores) << block)
+      private_constant :Context
+
+      # Registers argument-independent shared drawing steps. Every invocation runs inherited base blocks parent-first,
+      # then locally registered base blocks in registration order, before the module's public drawing methods. The block
+      # runs once in the current element context and does not receive the invocation arguments.
+      # @yield evaluates the drawing DSL in the current element context
+      # @yieldreturn [Object] ignored block result
+      # @return [nil]
+      # @raise [Sevgi::ArgumentError] when no block is given
+      # @raise [FrozenError] when the callable module is frozen
+      def base(&block)
+        raise ::FrozenError, "can't modify frozen callable module" if frozen?
+
+        ArgumentError.("Block required") unless block
+
+        own_configuration
+        @sevgi_bases << block
+        nil
       end
 
-      private_constant :DSL
+      class << self
+        private
 
-      # Initializes callable module state.
-      # @param base [Module] extended module
-      # @return [void]
-      def self.extended(base)
-        base.instance_exec do
-          @_callables = []
-          @_befores = []
-          @_afters = []
-
-          class << self
-            attr_reader :_callables, :_befores, :_afters
+        # Initializes callable module state.
+        # @param base [Module] extended module
+        # @return [void]
+        def extended(base)
+          base.instance_variable_set(:@sevgi_bases, [])
+          base.instance_variable_set(:@sevgi_callables, base.public_instance_methods(false))
+          base.instance_variable_set(:@sevgi_configuration_owner, base.object_id)
+        end
+
+        # Returns an owned snapshot of inherited and local base blocks in execution order.
+        # @param mod [Module] module extended with {Sevgi::Graphics::Module}
+        # @return [Array<Proc>] parent-first base blocks followed by local base blocks
+        # @raise [Sevgi::ArgumentError] when mod is not a callable drawing module
+        def bases(mod)
+          validate(mod)
+
+          mod
+            .ancestors
+            .reverse_each
+            .filter_map do |ancestor|
+              ancestor.instance_variable_get(:@sevgi_bases) if ancestor.instance_variable_defined?(:@sevgi_bases)
+            end
+            .flatten
+        end
+
+        # @overload call(mod, receiver, *args, **kwargs)
+        #   Runs module bases and callables against a receiver.
+        #   @param mod [Module] module extended with {Sevgi::Graphics::Module}
+        #   @param receiver [Sevgi::Graphics::Element] receiver element
+        #   @param args [Array<Object>] callable arguments
+        #   @param kwargs [Hash] callable keyword arguments
+        #   @return [Object, nil] last callable return value
+        #   @raise [Sevgi::ArgumentError] when mod is not a callable drawing module
+        def call(mod, receiver, ...)
+          methods = callables(mod)
+          context = context(mod, receiver)
+          bases(mod).each { context.instance_exec(&it) }
+
+          invoke(context, receiver, methods, ...)
+        end
+
+        # Returns the methods that should be executed for a callable module.
+        # @param mod [Module] module extended with {Sevgi::Graphics::Module}
+        # @return [Array<UnboundMethod>]
+        # @raise [Sevgi::ArgumentError] when mod is not a callable drawing module
+        def callables(mod)
+          validate(mod)
+
+          callable_names(mod).uniq.filter_map do |name|
+            mod.instance_method(name) if mod.public_method_defined?(name)
           end
+        end
+
+        def callable_names(mod)
+          mod.ancestors.reverse_each.flat_map do |ancestor|
+            if ancestor.instance_variable_defined?(:@sevgi_callables)
+              ancestor.instance_variable_get(:@sevgi_callables) + ancestor.public_instance_methods(false)
+            else
+              ancestor.public_instance_methods(false)
+            end
+          end
+        end
 
-          extend(DSL)
+        def context(mod, receiver)
+          ::Class.new(Context) { include(mod) }.new(mod, receiver)
         end
-      end
 
-      # @overload call(mod, receiver, *args, **kwargs)
-      #   Runs module hooks and callables against a receiver.
-      #   @param mod [Module] callable module
-      #   @param receiver [Sevgi::Graphics::Element] receiver element
-      #   @param args [Array<Object>] callable arguments
-      #   @param kwargs [Hash] callable keyword arguments
-      #   @return [Object, nil] last callable return value
-      #   @raise [Sevgi::ArgumentError] when mod is not a plain module
-      def self.call(mod, receiver, ...)
-        mod._befores.each { receiver.Within(receiver, &it) } if mod.respond_to?(:_befores) && mod._befores
-        # return last callable return value
-        callables(mod).map { it.bind(receiver).call(...) }.last.tap do
-          mod._afters.each { receiver.Within(receiver, &it) } if mod.respond_to?(:_afters) && mod._afters
+        def invoke(context, receiver, methods, ...)
+          result = methods.map { context.__send__(it.name, ...) }.last
+          result.equal?(context) ? receiver : result
         end
+
+        def validate(mod)
+          return mod if mod.instance_of?(::Module) && mod.is_a?(Graphics::Module)
+
+          ArgumentError.("Callable drawing module must extend Sevgi::Graphics::Module: #{mod}")
+        end
+      end
+
+      private
+
+      # Gives a duplicated callable module independent configuration containers.
+      # @param original [Module] source callable module
+      # @return [void]
+      # @api private
+      def initialize_dup(original)
+        super
+        copy_configuration(original)
+      end
+
+      # Gives a cloned callable module independent configuration containers.
+      # @param original [Module] source callable module
+      # @param freeze [Boolean] whether Ruby preserves the source frozen state
+      # @return [void]
+      # @api private
+      def initialize_clone(original, freeze: true)
+        super
+        copy_configuration(original)
+      end
+
+      def copy_configuration(original)
+        @sevgi_bases = original.instance_variable_get(:@sevgi_bases).dup
+        @sevgi_callables = original.instance_variable_get(:@sevgi_callables).dup
+        @sevgi_configuration_owner = object_id
+      end
+
+      def own_configuration
+        return if @sevgi_configuration_owner == object_id
+
+        @sevgi_bases = @sevgi_bases.dup
+        @sevgi_callables = @sevgi_callables.dup
+        @sevgi_configuration_owner = object_id
+      end
+
+      # Tracks newly defined methods as callable drawing candidates.
+      # Invocation runs unique methods that are still public, preserving tracked definition order.
+      # @param method [Symbol] method name Ruby reports as added
+      # @return [Array<Symbol>, nil]
+      def method_added(method)
+        super
+
+        own_configuration
+        @sevgi_callables << method
       end
 
-      # Returns the methods that should be executed for a callable module.
-      # @param mod [Module] callable module
-      # @return [Array<UnboundMethod>]
-      # @raise [Sevgi::ArgumentError] when mod is not a plain module
-      def self.callables(mod)
-        ArgumentError.("Must be a module: #{mod}") unless mod.instance_of?(::Module)
+      private :copy_configuration, :own_configuration
+    end
+
+    # Recursive callable drawing module support. Extend a module with this API when it and the modules defined beneath
+    # it form a callable drawing namespace. Existing and subsequently defined descendants receive the same recursive
+    # contract. Classes, autoloads, and modules aliased from another namespace are left unchanged.
+    # @example Define a callable drawing namespace
+    #   module Icons
+    #     extend Sevgi::Graphics::Modules
+    #
+    #     module Alert
+    #       base { css ".alert" => { fill: "red" } }
+    #
+    #       def call(id)
+    #         circle id:, class: "alert", r: 5
+    #       end
+    #     end
+    #   end
+    #
+    #   Sevgi::Graphics.SVG { Call Icons::Alert, "warning" }
+    # @see Sevgi::Graphics::Module
+    module Modules
+      # Propagates the recursive contract when a module constant is added.
+      # @api private
+      module Propagation
+        private
 
-        callable_names(mod).uniq.filter_map do |name|
-          mod.instance_method(name) if mod.public_method_defined?(name)
+        def const_added(name)
+          super
+          Graphics::Modules.__send__(:adopt, self, name)
         end
       end
 
-      def self.callable_names(mod)
-        tracked = mod.ancestors.reverse_each.filter_map do |ancestor|
-          ancestor._callables if ancestor.respond_to?(:_callables)
+      private_constant :Propagation
+
+      class << self
+        private
+
+        # Applies the local callable contract and adopts owned descendants.
+        # @param base [Module] extended module
+        # @return [void]
+        def extended(base)
+          base.extend(Graphics::Module)
+          base.singleton_class.prepend(Propagation) unless base.singleton_class < Propagation
+          base.constants(false).each { adopt(base, it) }
         end
 
-        return tracked.flatten unless tracked.empty?
+        # Applies this contract to an owned module constant without resolving autoloads or following aliases.
+        # @param owner [Module] constant owner
+        # @param name [Symbol] constant name
+        # @return [Module, nil] adopted module, or nil when the constant is outside the contract
+        def adopt(owner, name)
+          return if owner.autoload?(name, false)
 
-        mod.public_instance_methods
-      end
+          child = owner.const_get(name, false)
+          return unless child.instance_of?(::Module)
+          return unless child.name == "#{owner}::#{name}"
 
-      private_class_method :callable_names
+          child.extend(self) unless child.is_a?(self)
+        end
+      end
     end
 
     module Mixtures
@@ -99,40 +285,15 @@ module Sevgi
       module Call
         # @overload Call(mod, *args, **kwargs)
         #   Runs a callable drawing module in the current element context.
-        #   @param mod [Module] callable module
+        #   @param mod [Module] module extended with {Sevgi::Graphics::Module}
         #   @param args [Array<Object>] callable arguments
         #   @param kwargs [Hash] callable keyword arguments
         #   @return [Object, nil] last callable return value
-        #   @raise [Sevgi::ArgumentError] when mod is not a plain module
+        #   @raise [Sevgi::ArgumentError] when mod is not a callable drawing module
         def Call(mod, ...)
-          Graphics::Module.call(mod, self, ...)
+          Graphics::Module.__send__(:call, mod, self, ...)
         end
 
-        private
-
-        # rubocop:disable Metrics/MethodLength
-        def CallWithin(mod, container, element, *args, **kwargs, &block)
-          ArgumentError.("Must be a module: #{mod}") unless mod.instance_of?(::Module)
-
-          kwargs = kwargs.merge(id: F.demodulize(mod).to_sym) unless kwargs.key?(:id)
-
-          mod._befores.each { Within(self, &it) } if mod.respond_to?(:_befores) && mod._befores
-
-          public_send(container, **kwargs) do
-            Graphics::Module.callables(mod).each do |method|
-              public_send(element) do
-                Within(self, method.name, self, &block)
-
-                method.bind(self).call(*args)
-              end
-            end
-          end
-
-          mod._afters.each { Within(self, &it) } if mod.respond_to?(:_afters) && mod._afters
-
-          self
-        end
-        # rubocop:enable Metrics/MethodLength
       end
     end
   end