sevgi-graphics 0.93.1 → 0.95.0

data/lib/sevgi/graphics/document.rb

@@ -4,11 +4,89 @@ module Sevgi
   module Graphics
     # SVG document profile factory.
     module Document
+      # Defensive copy helper for profile metadata snapshots.
+      # @api private
+      module Snapshot
+        class << self
+          # Captures recursively immutable profile metadata. Mutable non-container values are stringified once.
+          # @param value [Object] value to capture
+          # @param seen [Hash] container identities on the current traversal path
+          # @return [Object] immutable captured value
+          # @raise [Sevgi::ArgumentError] when metadata is cyclic, has colliding keys, or cannot be stringified
+          def capture(value, seen = {}.compare_by_identity)
+            case value
+            when ::Hash
+              nested(value, seen) { capture_hash(value, seen) }.freeze
+            when ::Array
+              nested(value, seen) { value.map { capture(it, seen) } }.freeze
+            else
+              capture_value(value)
+            end
+          end
+
+          # Returns a recursively caller-owned copy of captured metadata.
+          # @param value [Object] captured value to copy
+          # @return [Object] caller-owned copy
+          def copy(value)
+            case value
+            when ::String
+              value.dup
+            when ::Hash
+              value.to_h { |key, item| [copy(key), copy(item)] }
+            when ::Array
+              value.map { copy(it) }
+            else
+              value
+            end
+          end
+
+          private
+
+          def capture_hash(value, seen)
+            value.each_with_object({}) do |(key, item), captured|
+              key = capture(key, seen)
+              ArgumentError.("Document profile metadata keys collide after stringification") if captured.key?(key)
+
+              captured[key] = capture(item, seen)
+            end
+          end
+
+          def nested(value, seen)
+            ArgumentError.("Cyclic document profile metadata is not supported") if seen.key?(value)
+
+            seen[value] = true
+            yield
+          ensure
+            seen.delete(value)
+          end
+
+          def capture_value(value)
+            case value
+            when ::String
+              XML.text(value, context: "Document profile metadata").freeze
+            when ::Numeric, ::Symbol, ::NilClass, ::TrueClass, ::FalseClass
+              XML.text(value, context: "Document profile metadata")
+              value
+            else
+              stringify(value).freeze
+            end
+          end
+
+          def stringify(value)
+            XML.text(value, context: "Document profile metadata")
+          end
+        end
+      end
+
+      private_constant :Snapshot
+
       # Builds a root SVG element from a document profile.
       # @param document [Symbol, String, Class] profile name or document class
       # @param canvas [Sevgi::Graphics::Canvas, Sevgi::Graphics::Paper, Symbol, String, Sevgi::Undefined, nil] canvas input
+      # @yield evaluates the drawing DSL in the new root element
+      # @yieldreturn [Object] ignored block result
       # @return [Sevgi::Graphics::Document::Proto] SVG root element
-      # @raise [Sevgi::ArgumentError] when the document profile is unknown
+      # @raise [Sevgi::ArgumentError] when the document profile or root XML attributes are invalid
       def self.call(document, canvas = Undefined, **, &block)
         klass = case document
         when ::Class
@@ -36,67 +114,130 @@ module Sevgi
       private_class_method :canvas_attributes
 
       # Defines or returns a document profile class.
+      # Profile metadata is captured before class or thread-atomic registry mutation. Mutable non-container attribute
+      # values are stringified once during capture. Successful named definitions return the canonical class stored by
+      # the registry, including when identical definitions race.
       # @param name [Symbol, String, Sevgi::Undefined] profile name, or Undefined for an anonymous profile
-      # @param preambles [Array<String>, nil] document preamble lines
-      # @param attributes [Hash] default root attributes
+      # @param preambles [Array<String>, nil, Sevgi::Undefined] document preamble lines
+      # @param attributes [Hash, nil, Sevgi::Undefined] default root attributes
       # @param overwrite [Boolean] true to replace an existing profile
       # @return [Class] document class
-      # @raise [Sevgi::ArgumentError] when a named profile conflicts with an existing profile
-      def self.define(name = Undefined, preambles: [], attributes: {}, overwrite: false)
-        return Class.new(Base) { document(name, preambles:, attributes:, register: false) } if name == Undefined
+      # @raise [Sevgi::ArgumentError] when a name conflicts or metadata is invalid XML, cyclic, or cannot be stringified
+      def self.define(name = Undefined, preambles: Undefined, attributes: Undefined, overwrite: false)
+        return anonymous(attributes:, preambles:) if name == Undefined
 
-        profile = Profile.new(name, attributes:, preambles:)
+        return lookup(name) if preambles == Undefined && attributes == Undefined
 
-        if (current = Profile[name])
-          unless overwrite || current.profile == profile
-            ArgumentError.("Document profile already defined differently: #{name}")
-          end
+        name = Profile.normalize!(name)
 
+        if (current = Profile[name])
+          reject_conflict(name, current, attributes:, preambles:) unless overwrite
           return current unless overwrite
         end
 
+        attributes, preambles = defaults(attributes:, preambles:)
         Class.new(Base) { document(name, preambles:, attributes:, overwrite:) }
+        Registry[name]
+      end
+
+      def self.anonymous(attributes:, preambles:)
+        attributes, preambles = defaults(attributes:, preambles:)
+        Class.new(Base) { document(Undefined, preambles:, attributes:, register: false) }
+      end
+
+      def self.lookup(name)
+        name = Profile.normalize!(name)
+        Profile[name] || ArgumentError.("Unknown document profile: #{name}")
+      end
+
+      def self.defaults(attributes:, preambles:)
+        [attributes == Undefined ? {} : attributes, preambles == Undefined ? nil : preambles]
       end
 
-      # Immutable document profile metadata.
+      def self.reject_conflict(name, current, attributes:, preambles:)
+        return if compatible?(current, attributes:, preambles:)
+
+        ArgumentError.("Document profile already defined differently: #{name}")
+      end
+
+      def self.compatible?(klass, attributes:, preambles:)
+        profile = klass.profile
+
+        (attributes == Undefined || Profile.new(nil, attributes:).attributes == profile.attributes) &&
+          (preambles == Undefined || Profile.new(nil, preambles:).preambles == profile.preambles)
+      end
+
+      private_class_method :anonymous, :compatible?, :defaults, :lookup, :reject_conflict
+
+      # Process-global document profile registry.
       # @api private
-      class Profile
+      module Registry
         @available = {}
+        @mutex = ::Mutex.new
 
         class << self
-          # @return [Hash<Symbol, Class>] registered profile classes
-          attr_reader :available
-        end
+          def [](name) = @mutex.synchronize { @available[name] }
 
-        # Returns a profile class by name.
-        # @param name [Object] profile name
-        # @return [Class, nil]
-        def self.[](name) = (name = normalize(name)) && available[name]
+          def available = @mutex.synchronize { @available.dup.freeze }
 
-        # Registers a profile class.
-        # @param name [Object] profile name
-        # @param klass [Class] document class
-        # @param overwrite [Boolean] true to replace an existing profile
-        # @return [Class] registered class
-        # @raise [Sevgi::ArgumentError] when name is invalid or conflicts with an existing profile
-        def self.register(name, klass, overwrite: false)
-          name = normalize!(name)
-
-          if (current = available[name])
-            unless overwrite || current.profile == klass.profile
-              ArgumentError.("Document profile already defined differently: #{name}")
+          def register(name, klass, profile: nil, overwrite: false)
+            name = Profile.normalize!(name)
+            validate!(name, klass, profile)
+
+            @mutex.synchronize { store(name, klass, profile, overwrite) }
+          end
+
+          private
+
+          def store(name, klass, profile, overwrite)
+            if (current = @available[name])
+              unless overwrite || current.profile == profile
+                ArgumentError.("Document profile already defined differently: #{name}")
+              end
+
+              return current unless overwrite
             end
 
-            return current unless overwrite
+            @available[name] = klass
           end
 
-          available[name] = klass
+          def validate!(name, klass, profile)
+            unless klass.is_a?(::Class) && klass <= Proto
+              ArgumentError.("Document profile class must inherit Document::Proto: #{klass}")
+            end
+
+            return if profile.is_a?(Profile) && profile.name == name
+
+            ArgumentError.("Document profile class has invalid metadata: #{klass}")
+          end
         end
+      end
+
+      private_constant :Registry
+
+      # Immutable, read-only document profile metadata exposed by document classes. Process-global lookup and registration
+      # are thread-atomic. Metadata containers and strings are captured recursively; other mutable attribute values are
+      # stringified once during construction.
+      # @see Sevgi::Graphics.document
+      class Profile
+        # Returns a thread-coherent immutable snapshot of registered profile classes.
+        # @return [Hash<Symbol, Class>]
+        def self.available = Registry.available
+
+        # Returns a profile class by name from the process-global registry.
+        # @param name [Object] profile name
+        # @return [Class, nil]
+        def self.[](name) = (name = normalize(name)) && Registry[name]
 
         # Normalizes a profile name.
         # @param name [Object] profile name
         # @return [Symbol, nil]
-        def self.normalize(name) = name.respond_to?(:to_sym) ? name.to_sym : nil
+        def self.normalize(name)
+          normalized = name.to_sym if name.respond_to?(:to_sym)
+          normalized if normalized.is_a?(::Symbol)
+        rescue ::StandardError
+          nil
+        end
 
         # Normalizes a profile name or raises.
         # @param name [Object] profile name
@@ -107,22 +248,17 @@ module Sevgi
         # @return [Symbol, nil] profile name
         attr_reader :name
 
-        # @return [Hash] default root attributes
-        attr_reader :attributes
-
-        # @return [Array<String>, nil] preamble lines
-        attr_reader :preambles
-
         # Creates profile metadata.
         # @param name [Object, nil] profile name
-        # @param attributes [Hash, nil] default root attributes
+        # @param attributes [Hash, nil] default root attributes; nil means an empty Hash
         # @param preambles [Array<String>, nil] preamble lines
         # @return [void]
-        # @raise [Sevgi::ArgumentError] when name cannot be normalized
+        # @raise [Sevgi::ArgumentError] when name or metadata is invalid XML, cyclic, or cannot be stringified
         def initialize(name, attributes: nil, preambles: nil)
           @name = name.nil? ? nil : self.class.normalize!(name)
-          @attributes = attributes || {}
-          @preambles = preambles
+          validate_attributes!(attributes)
+          @attributes = Snapshot.capture(attributes || {})
+          @preambles = capture_preambles(preambles)
         end
 
         # Reports strict profile equality.
@@ -130,31 +266,71 @@ module Sevgi
         # @return [Boolean]
         def ==(other) = self.class == other.class && deconstruct == other.deconstruct
 
+        # Returns default root attributes.
+        # @return [Hash] mutation-isolated attribute snapshot
+        def attributes = Snapshot.copy(@attributes)
+
         # Returns profile components.
         # @return [Array<(Symbol, nil), Hash, (Array<String>, nil)>]
         def deconstruct = [name, attributes, preambles]
-      end
 
-      private_constant :Profile
+        # Returns preamble lines.
+        # @return [Array<String>, nil] mutation-isolated preamble snapshot
+        def preambles = Snapshot.copy(@preambles)
+
+        private
+
+        def validate_attributes!(attributes)
+          return if attributes.nil?
+
+          ArgumentError.("Document profile attributes must be a Hash") unless attributes.is_a?(::Hash)
+
+          normalized = {}
+          attributes.each_key do |key|
+            id = normalize_attribute!(key)
+            ArgumentError.("Document profile attribute names collide after normalization: #{id}") if normalized.key?(id)
+
+            normalized[id] = true
+          end
+        end
+
+        def normalize_attribute!(key)
+          if key.is_a?(::String) || key.is_a?(::Symbol)
+            return XML.name(key, context: "Document profile attribute name").to_sym
+          end
+
+          ArgumentError.("Document profile attribute names must be Strings or Symbols")
+        end
+
+        def capture_preambles(preambles)
+          return if preambles.nil?
+
+          unless preambles.is_a?(::Array) && preambles.all?(::String)
+            ArgumentError.("Document profile preambles must be an Array of Strings")
+          end
+
+          Snapshot.capture(preambles)
+        end
+      end
 
       # Class-level DSL used while defining document classes.
       # @api private
       module DSL
-        # @return [Sevgi::Graphics::Document::Profile] document profile metadata
+        # @return [Sevgi::Graphics::Document::Profile] immutable document profile metadata
         attr_reader :profile
 
         # Sets document profile metadata on a class.
         # @param name [Object] profile name
-        # @param attributes [Hash] default root attributes
+        # @param attributes [Hash, nil] default root attributes
         # @param preambles [Array<String>, nil] preamble lines
         # @param register [Boolean] true to register the profile globally
         # @param overwrite [Boolean] true to replace an existing profile
-        # @return [Sevgi::Graphics::Document::Profile]
-        # @raise [Sevgi::ArgumentError] when registration fails
+        # @return [Sevgi::Graphics::Document::Profile] immutable document profile metadata
+        # @raise [Sevgi::ArgumentError] when registration fails or metadata is invalid XML, cyclic, or cannot be stringified
         def document(name, attributes: {}, preambles: nil, register: true, overwrite: false)
-          @profile = Profile.new(register ? name : nil, attributes:, preambles:)
-          Profile.register(name, self, overwrite:) if register
-          @profile
+          profile = Profile.new(register ? name : nil, attributes:, preambles:)
+          Registry.register(name, self, profile:, overwrite:) if register
+          @profile = profile
         end
 
         # Includes a graphics mixture into the document class.
@@ -189,15 +365,17 @@ module Sevgi
         #   @param objects [Array<Object>] optional renderer arguments
         #   @param options [Hash] render options
         #   @return [String] SVG document source
+        #   @raise [Sevgi::ArgumentError] when renderer options or XML-bound values are invalid
         def call(*, **)
           options = DEFAULTS.merge(**)
 
           self.PreRender(*, **options) if respond_to?(:PreRender)
-          self.Render(*, **options)
+          render_options = options.reject { |key, _| DEFAULTS.key?(key) }
+          self.Render(*, **render_options)
         end
 
         # Returns inherited root attributes for this document class.
-        # @return [Hash]
+        # @return [Hash{Symbol => Object}] inherited root attributes
         def self.attributes = self == Proto ? {} : {**superclass.attributes, **profile.attributes}
 
         # Returns inherited preamble lines for this document class.

data/lib/sevgi/graphics/element.rb

@@ -3,17 +3,27 @@
 module Sevgi
   module Graphics
     # 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
+    #   @return [Boolean]
     class Element
       # Builds an element node.
       # @param name [Symbol, String] SVG element name
       # @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 element name or an attribute is not valid XML
       def self.element(name, *, parent:, &block) = new(name, **Dispatch.parse(name, *), parent:, &block)
 
       # Builds an SVG root element.
-      # @param block [Proc, nil] DSL block evaluated in the root element
+      # @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)
 
       # Reports whether an element is the root element.
@@ -52,26 +62,41 @@ module Sevgi
 
       extend Ident
 
-      # @!attribute [r] name
-      #   @return [Symbol] SVG element name
-      # @!attribute [r] attributes
-      #   @return [Sevgi::Graphics::Attributes] attribute store
-      # @!attribute [r] children
-      #   @return [Array<Sevgi::Graphics::Element>] child elements
-      # @!attribute [r] contents
-      #   @return [Array<Sevgi::Graphics::Content>] element content objects
-      # @!attribute [r] parent
-      #   @return [Sevgi::Graphics::Element, Object] parent element or root sentinel
-      attr_reader :name, :attributes, :children, :contents, :parent
+      # Returns the SVG element name.
+      # @return [Symbol]
+      attr_reader :name
+
+      # Returns the attribute store.
+      # @return [Sevgi::Graphics::Attributes]
+      attr_reader :attributes
+
+      # Returns child elements.
+      # @return [Array<Sevgi::Graphics::Element>]
+      attr_reader :children
+
+      # Returns element content objects.
+      # @return [Array<Sevgi::Graphics::Content>]
+      attr_reader :contents
+
+      # Returns the parent element or root sentinel.
+      # @return [Sevgi::Graphics::Element, Object] parent element or root sentinel
+      attr_reader :parent
 
       # Creates an element.
       # @param name [Symbol] SVG element name
       # @param parent [Sevgi::Graphics::Element, Object] parent element or root sentinel
       # @param attributes [Hash] SVG attributes
       # @param contents [Array<Sevgi::Graphics::Content>] content objects
+      # @yield evaluates the drawing DSL in the new element
+      # @yieldreturn [Object] ignored block result
       # @return [void]
+      # @raise [Sevgi::ArgumentError] when the element name or an attribute is not valid XML
       def initialize(name, parent:, attributes: {}, contents: [], &block)
-        @name = name
+        unless name.is_a?(::String) || name.is_a?(::Symbol)
+          ArgumentError.("XML element name must be a String or Symbol")
+        end
+
+        @name = XML.name(name, context: "XML element name").to_sym
         @attributes = Attributes.new(attributes)
         @children = []
         @contents = contents
@@ -84,6 +109,8 @@ module Sevgi
 
       # Dispatches SVG element DSL calls and caches valid element methods.
       # @param name [Symbol] missing method name
+      # @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
@@ -95,6 +122,7 @@ module Sevgi
       # @param name [Symbol] queried method name
       # @param include_private [Boolean] standard Ruby respond_to? flag
       # @return [Boolean]
+      # @api private
       def respond_to_missing?(name, include_private = false)
         Element.valid?(Element.id(name)) || super
       end
@@ -110,7 +138,6 @@ module Sevgi
         # @param tag [Symbol] SVG element name
         # @return [Sevgi::Graphics::Element]
         def call(element, method, tag, *, &)
-          # Low-hanging fruit optimization: define missing method to avoid dispatching cost
           unless Element.method_defined?(method)
             Element.class_exec do
               define_method(method) { |*args, &block| self.class.element(tag, *args, parent: self, &block) }
@@ -149,7 +176,7 @@ module Sevgi
 
       protected
 
-      attr_writer :children, :attributes
+      attr_writer :attributes, :children, :contents, :parent
     end
   end
 end

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

@@ -3,9 +3,20 @@
 module Sevgi
   module Graphics
     # Callable drawing module support.
-    # @api private
+    # Extend a plain Ruby module with this API to make its public instance methods callable drawing steps.
+    # @example Define and call a drawing module
+    #   Widget = Module.new do
+    #     extend Sevgi::Graphics::Module
+    #
+    #     def item(id)
+    #       rect(id:)
+    #     end
+    #   end
+    #
+    #   SVG { Call(Widget, "box") }
     module Module
-      # Tracks newly defined public methods as callable drawing steps.
+      # 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)
@@ -49,6 +60,7 @@ module Sevgi
       #   @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
@@ -64,8 +76,22 @@ module Sevgi
       def self.callables(mod)
         ArgumentError.("Must be a module: #{mod}") unless mod.instance_of?(::Module)
 
-        (mod.respond_to?(:_callables) ? mod._callables : mod.instance_methods).map { mod.instance_method(it) }
+        callable_names(mod).uniq.filter_map do |name|
+          mod.instance_method(name) if mod.public_method_defined?(name)
+        end
       end
+
+      def self.callable_names(mod)
+        tracked = mod.ancestors.reverse_each.filter_map do |ancestor|
+          ancestor._callables if ancestor.respond_to?(:_callables)
+        end
+
+        return tracked.flatten unless tracked.empty?
+
+        mod.public_instance_methods
+      end
+
+      private_class_method :callable_names
     end
 
     module Mixtures