sevgi-graphics 0.95.0 → 0.98.2

data/lib/sevgi/graphics/auxiliary/scalar.rb

@@ -2,13 +2,13 @@
 
 module Sevgi
   module Graphics
-    # Validates finite real numeric values used by graphics auxiliaries.
+    # Validates finite real numeric values used by Graphics APIs.
     # @api private
     module Scalar
       # Converts one finite real value.
       # @param value [Numeric] value to validate
       # @param context [String] error context
-      # @param field [Symbol] field name
+      # @param field [Symbol, Integer] field name or position
       # @param positive [Boolean] require a strictly positive value
       # @param nonnegative [Boolean] require a non-negative value
       # @return [Float] validated value
@@ -24,15 +24,44 @@ module Sevgi
         invalid(context, field, value)
       end
 
-      def self.real?(value) = value.is_a?(::Numeric) && !value.is_a?(::Complex)
+      # Converts one finite real value to an SVG number.
+      # @param value [Numeric] value to validate
+      # @param context [String] error context
+      # @param field [Symbol, Integer] field name or position
+      # @param positive [Boolean] require a strictly positive value
+      # @param nonnegative [Boolean] require a non-negative value
+      # @return [Integer, Float] normalized number with integral values represented as Integer
+      # @raise [Sevgi::ArgumentError] when value is not a finite real number
+      def self.number(value, context:, field:, positive: false, nonnegative: false)
+        if value.is_a?(::Integer)
+          invalid(context, field, value) unless valid?(value, positive:, nonnegative:)
+          return value
+        end
+
+        value = finite(value, context:, field:, positive:, nonnegative:)
+        value == value.to_i ? value.to_i : value
+      end
 
-      def self.valid?(number, positive:, nonnegative:)
-        number.finite? && (!positive || number.positive?) && (!nonnegative || number >= 0)
+      # Converts indexed finite real values to SVG numbers.
+      # @param values [Array<Numeric>] values to normalize
+      # @param context [String] error context
+      # @return [Array<(Integer, Float)>] normalized SVG numbers
+      # @raise [Sevgi::ArgumentError] when a value is not a finite real number
+      def self.numbers(values, context:)
+        values.each_with_index.map { |value, index| number(value, context:, field: index) }
       end
 
-      def self.invalid(context, field, value) = ArgumentError.("Invalid #{context} #{field}: #{value.inspect}")
+      class << self
+        private
+
+        def real?(value) = value.is_a?(::Numeric) && !value.is_a?(::Complex)
 
-      private_class_method :invalid, :real?, :valid?
+        def valid?(number, positive:, nonnegative:)
+          number.finite? && (!positive || number.positive?) && (!nonnegative || number >= 0)
+        end
+
+        def invalid(context, field, value) = ArgumentError.("Invalid #{context} #{field}: #{value.inspect}")
+      end
     end
 
     private_constant :Scalar

data/lib/sevgi/graphics/auxiliary.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "auxiliary/scalar"
+require_relative "auxiliary/path"
 require_relative "auxiliary/margin"
 require_relative "auxiliary/sizes"
 require_relative "auxiliary/paper"

data/lib/sevgi/graphics/document/base.rb

@@ -3,9 +3,11 @@
 module Sevgi
   module Graphics
     module Document
-      # Standard document profile with the full common DSL mixture set.
+      # Abstract common document layer with the profile-independent DSL mixture set. It is not registered as a
+      # selectable profile. Advanced extensions may target this class through {Sevgi::Graphics::Mixtures.mixin}; doing
+      # so changes every descendant profile process-wide. Subclass it first when an extension should remain scoped.
       class Base < Proto
-        document :base
+        document nil, register: false
 
         mixture :Call
         mixture :Duplicate
@@ -21,6 +23,8 @@ module Sevgi
 
         # Runs pre-render validation and lint checks.
         # @param options [Hash] pre-render options
+        # @option options [Boolean] :validate run SVG standard validation
+        # @option options [Boolean] :lint run document lint checks
         # @return [void]
         # @raise [Sevgi::ValidationError] when validation fails
         # @raise [Sevgi::Graphics::LintError] when linting fails

data/lib/sevgi/graphics/document/default.rb

@@ -4,7 +4,7 @@ module Sevgi
   module Graphics
     module Document
       # Default SVG document profile with XML preamble and SVG namespace.
-      class Default < Minimal
+      class Default < Base
         document(
           :default,
           attributes: {

data/lib/sevgi/graphics/document.rb

@@ -2,7 +2,27 @@
 
 module Sevgi
   module Graphics
-    # SVG document profile factory.
+    # SVG document profile factory and process-global named-profile registry.
+    #
+    # A profile owns SVG root attributes and optional preamble lines, but not canvas size. Built-in and named profiles
+    # can be passed to {Sevgi::Graphics.SVG}; an anonymous profile class is useful when library code needs one-off
+    # metadata without adding a global name.
+    #
+    # | Profile | Preamble | Root metadata | Additional DSL |
+    # | --- | --- | --- | --- |
+    # | `:minimal` | none | none | common document DSL |
+    # | `:default` | XML declaration | SVG namespace | common document DSL |
+    # | `:html` | none | SVG namespace | common document DSL |
+    # | `:inkscape` | XML declaration | SVG and editor namespaces; crisp edges | `Draw`, `Hatch`, and editor/RDF helpers |
+    #
+    # The Inkscape root adds Sevgi, Inkscape, and Sodipodi namespaces plus `shape-rendering="crispEdges"`. Every
+    # selectable profile has the same validation and lint lifecycle; `:minimal` changes serialization metadata, not
+    # checking policy. {Base} is the public common extension layer rather than a selectable profile. {Minimal} and
+    # {Default} are sibling concrete profiles: Minimal contributes no metadata and is not the semantic base of the other
+    # profiles. Targeting Base through {Sevgi::Graphics::Mixtures.mixin} changes every descendant profile process-wide;
+    # subclass Base first when an extension should remain scoped.
+    #
+    # @see https://sevgi.roktas.dev/svg/#document-profiles Document profiles guide
     module Document
       # Defensive copy helper for profile metadata snapshots.
       # @api private
@@ -78,7 +98,27 @@ module Sevgi
         end
       end
 
-      private_constant :Snapshot
+      # Document profile name normalization.
+      # @api private
+      module Name
+        # Normalizes a profile name.
+        # @param name [Object] profile name
+        # @return [Symbol, 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
+        # @return [Symbol]
+        # @raise [Sevgi::ArgumentError] when name cannot be normalized
+        def self.normalize!(name) = normalize(name) || ArgumentError.("Invalid document profile: #{name}")
+      end
+
+      private_constant :Name, :Snapshot
 
       # Builds a root SVG element from a document profile.
       # @param document [Symbol, String, Class] profile name or document class
@@ -87,12 +127,15 @@ module Sevgi
       # @yieldreturn [Object] ignored block result
       # @return [Sevgi::Graphics::Document::Proto] SVG root element
       # @raise [Sevgi::ArgumentError] when the document profile or root XML attributes are invalid
+      # @example Build from a scoped Base-derived profile
+      #   Card = Class.new(Sevgi::Graphics::Document::Base)
+      #   Sevgi::Graphics::Document.(Card) { rect width: 10, height: 5 }
       def self.call(document, canvas = Undefined, **, &block)
         klass = case document
         when ::Class
           document if document <= Proto
         else
-          Profile[document]
+          fetch(document)
         end
 
         ArgumentError.("Unknown document profile: #{document}") unless klass
@@ -113,61 +156,124 @@ module Sevgi
 
       private_class_method :canvas_attributes
 
-      # Defines or returns a document profile class.
+      # Returns a registered document class by profile name.
+      # @param name [Symbol, String] profile name
+      # @return [Class] registered subclass of {Sevgi::Graphics::Document::Proto}
+      # @raise [Sevgi::ArgumentError] when name is invalid or unknown
+      # @example Look up a document class and its metadata
+      #   klass = Sevgi::Graphics::Document.fetch(:minimal)
+      #   Sevgi::Graphics::Document.profile(:minimal) # => klass.profile
+      def self.fetch(name)
+        name = Name.normalize!(name)
+        Registry[name] || ArgumentError.("Unknown document profile: #{name}")
+      end
+
+      # Reports whether a normalizable document profile name is registered.
+      # Invalid converters return false and do not change the registry.
+      # @example Check a built-in profile
+      #   Sevgi::Graphics::Document.exist?(:minimal) # => true
+      # @param name [Object] profile name
+      # @return [Boolean]
+      def self.exist?(name)
+        name = Name.normalize(name)
+        name ? !Registry[name].nil? : false
+      end
+
+      # Returns registered document profile names.
+      # @return [Array<Symbol>] frozen name snapshot
+      def self.keys = Registry.available.keys.freeze
+
+      # Returns immutable metadata for a registered document profile.
+      # @param name [Symbol, String] profile name
+      # @return [Sevgi::Graphics::Document::Profile] registered profile metadata
+      # @raise [Sevgi::ArgumentError] when name is invalid or unknown
+      def self.profile(name) = fetch(name).profile
+
+      # Defines, looks up, or returns an anonymous document profile class.
+      #
+      # A name without metadata performs lookup. A name plus either metadata
+      # keyword defines or compatibly reuses a named profile. Omitting the name
+      # creates an anonymous class and leaves the registry unchanged. Named
+      # profiles are process-global; use them for shared vocabulary rather than
+      # per-call configuration.
       # 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.
+      # values are stringified once, attribute names and nested Hash keys are normalized, and nil attributes are omitted
+      # 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, 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 name conflicts or metadata is invalid XML, cyclic, or cannot be stringified
+      # @raise [Sevgi::ArgumentError] when overwrite is not Boolean, a name conflicts, or metadata is invalid XML,
+      #   cyclic, or cannot be stringified
+      # @example Define a reusable library profile
+      #   profile = Sevgi::Graphics::Document.define(
+      #     :icon,
+      #     preambles: [],
+      #     attributes: {xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24"}
+      #   )
+      #   Sevgi::Graphics::Document.(profile) { circle cx: 12, cy: 12, r: 10 }.Render
+      # @example Build an anonymous one-off profile
+      #   profile = Sevgi::Graphics::Document.define(attributes: {viewBox: "0 0 10 10"})
+      #   profile.profile.name # => nil
       def self.define(name = Undefined, preambles: Undefined, attributes: Undefined, overwrite: false)
+        overwrite!(overwrite)
         return anonymous(attributes:, preambles:) if name == Undefined
 
         return lookup(name) if preambles == Undefined && attributes == Undefined
 
-        name = Profile.normalize!(name)
-
-        if (current = Profile[name])
-          reject_conflict(name, current, attributes:, preambles:) unless overwrite
-          return current unless overwrite
-        end
+        name = Name.normalize!(name)
+        current = reuse(name, attributes:, preambles:, overwrite:)
+        return current if current
 
         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
+      class << self
+        private
 
-      def self.lookup(name)
-        name = Profile.normalize!(name)
-        Profile[name] || ArgumentError.("Unknown document profile: #{name}")
-      end
+        def anonymous(attributes:, preambles:)
+          attributes, preambles = defaults(attributes:, preambles:)
+          Class.new(Base) { document(Undefined, preambles:, attributes:, register: false) }
+        end
 
-      def self.defaults(attributes:, preambles:)
-        [attributes == Undefined ? {} : attributes, preambles == Undefined ? nil : preambles]
-      end
+        def lookup(name)
+          fetch(name)
+        end
 
-      def self.reject_conflict(name, current, attributes:, preambles:)
-        return if compatible?(current, attributes:, preambles:)
+        def defaults(attributes:, preambles:)
+          [attributes == Undefined ? {} : attributes, preambles == Undefined ? nil : preambles]
+        end
 
-        ArgumentError.("Document profile already defined differently: #{name}")
-      end
+        def reject_conflict(name, current, attributes:, preambles:)
+          return if compatible?(current, attributes:, preambles:)
 
-      def self.compatible?(klass, attributes:, preambles:)
-        profile = klass.profile
+          ArgumentError.("Document profile already defined differently: #{name}")
+        end
 
-        (attributes == Undefined || Profile.new(nil, attributes:).attributes == profile.attributes) &&
-          (preambles == Undefined || Profile.new(nil, preambles:).preambles == profile.preambles)
-      end
+        def 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
+
+        def reuse(name, attributes:, preambles:, overwrite:)
+          return unless (current = Registry[name])
+
+          reject_conflict(name, current, attributes:, preambles:) unless overwrite
+          current unless overwrite
+        end
+
+        def overwrite!(value)
+          return value if [true, false].include?(value)
 
-      private_class_method :anonymous, :compatible?, :defaults, :lookup, :reject_conflict
+          ArgumentError.("Document overwrite must be true or false")
+        end
+      end
 
       # Process-global document profile registry.
       # @api private
@@ -181,7 +287,8 @@ module Sevgi
           def available = @mutex.synchronize { @available.dup.freeze }
 
           def register(name, klass, profile: nil, overwrite: false)
-            name = Profile.normalize!(name)
+            overwrite = Document.send(:overwrite!, overwrite)
+            name = Name.normalize!(name)
             validate!(name, klass, profile)
 
             @mutex.synchronize { store(name, klass, profile, overwrite) }
@@ -198,6 +305,7 @@ module Sevgi
               return current unless overwrite
             end
 
+            klass.instance_variable_set(:@profile, profile)
             @available[name] = klass
           end
 
@@ -217,34 +325,12 @@ module Sevgi
 
       # 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.
+      # stringified once during construction. Attribute names and nested Hash keys are normalized to Symbols, nil values
+      # are omitted, and update-suffix intent is retained for inheritance.
+      # Returned attribute and preamble collections are caller-owned snapshots,
+      # so changing them does not alter the registered profile.
       # @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)
-          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
-        # @return [Symbol]
-        # @raise [Sevgi::ArgumentError] when name cannot be normalized
-        def self.normalize!(name) = normalize(name) || ArgumentError.("Invalid document profile: #{name}")
-
         # @return [Symbol, nil] profile name
         attr_reader :name
 
@@ -255,19 +341,25 @@ module Sevgi
         # @return [void]
         # @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)
-          validate_attributes!(attributes)
-          @attributes = Snapshot.capture(attributes || {})
+          @name = name.nil? ? nil : Name.normalize!(name)
+          @attributes = capture_attributes(attributes)
           @preambles = capture_preambles(preambles)
+          freeze
         end
 
         # Reports strict profile equality.
         # @param other [Object] object to compare
         # @return [Boolean]
-        def ==(other) = self.class == other.class && deconstruct == other.deconstruct
+        def eql?(other) = self.class == other.class && deconstruct == other.deconstruct
+
+        # Returns a hash compatible with strict equality.
+        # @return [Integer]
+        def hash = [self.class, name, @attributes, @preambles].hash
 
-        # Returns default root attributes.
-        # @return [Hash] mutation-isolated attribute snapshot
+        # Returns canonical default root attributes for this profile.
+        # Names and nested Hash keys are Symbols, nil attributes are omitted, and update suffixes remain explicit for
+        # application by a document class.
+        # @return [Hash{Symbol => Object}] mutation-isolated attribute snapshot
         def attributes = Snapshot.copy(@attributes)
 
         # Returns profile components.
@@ -278,28 +370,35 @@ module Sevgi
         # @return [Array<String>, nil] mutation-isolated preamble snapshot
         def preambles = Snapshot.copy(@preambles)
 
+        alias == eql?
+
         private
 
-        def validate_attributes!(attributes)
-          return if attributes.nil?
+        def capture_attribute(key, value, identities)
+          update = Attribute.updateable?(key)
+          id = Attribute.id(key)
+          if identities.key?(id)
+            ArgumentError.("Document profile attribute names collide after normalization: #{id}")
+          end
+
+          identities[id] = true
+          key = update ? :"#{id}#{Attributes::UPDATE_SUFFIX}" : id
+          value = Snapshot.capture(value)
+          [key, Attribute.capture(value, normalize_keys: value.is_a?(::Hash))]
+        end
 
+        def capture_attributes(attributes)
+          attributes = {} 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)
+          identities = {}
+          captured = attributes.filter_map do |key, value|
+            next if value.nil?
 
-            normalized[id] = true
+            capture_attribute(key, value, identities)
           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")
+          Snapshot.capture(captured.to_h)
         end
 
         def capture_preambles(preambles)
@@ -316,9 +415,6 @@ module Sevgi
       # Class-level DSL used while defining document classes.
       # @api private
       module DSL
-        # @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, nil] default root attributes
@@ -328,9 +424,14 @@ module Sevgi
         # @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)
+          overwrite = Document.send(:overwrite!, overwrite)
           profile = Profile.new(register ? name : nil, attributes:, preambles:)
-          Registry.register(name, self, profile:, overwrite:) if register
-          @profile = profile
+          Attributes.new(superclass.attributes).merge!(profile.attributes)
+          return (@profile = profile) unless register
+
+          registered = Registry.register(name, self, profile:, overwrite:)
+          @profile = profile unless registered.equal?(self)
+          @profile
         end
 
         # Includes a graphics mixture into the document class.
@@ -342,17 +443,19 @@ module Sevgi
           include(mod = ns.const_get(mixture))
           extend(mod::ClassMethods) if defined?(mod::ClassMethods)
         end
+
+        private :document, :mixture
       end
 
       private_constant :DSL
 
       # Default render-time checks.
+      # @api private
       DEFAULTS = {lint: true, validate: true}.freeze
+      private_constant :DEFAULTS
 
       # Base document root element class.
       class Proto < Element
-        public_class_method :new
-
         extend DSL
 
         mixture :Core
@@ -360,27 +463,58 @@ module Sevgi
         mixture :Render
         mixture :Wrappers
 
-        # @overload call(*objects, **options)
-        #   Renders the document.
-        #   @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(**)
+        # Returns the nearest immutable profile metadata in the class hierarchy.
+        # @return [Sevgi::Graphics::Document::Profile, nil] nearest profile, or nil when no ancestor is configured
+        def self.profile
+          return @profile if instance_variable_defined?(:@profile)
 
-          self.PreRender(*, **options) if respond_to?(:PreRender)
+          superclass.profile if superclass.respond_to?(:profile)
+        end
+
+        # Renders this document after its optional pre-render checks.
+        # @example Render a document directly with separate check and renderer options
+        #   document = Sevgi::Graphics.SVG(:minimal) { rect width: 3 }
+        #   document.call(lint: false, style: :inline)
+        # @param options [Hash] `lint` and `validate` check switches plus renderer options accepted by
+        #   {Sevgi::Graphics::Mixtures::Render#Render}
+        # @option options [Boolean] :lint (true) run document lint checks
+        # @option options [Boolean] :validate (true) run SVG standard validation
+        # @return [String] SVG document source
+        # @raise [Sevgi::ArgumentError] when an option or XML-bound value is invalid
+        # @raise [Sevgi::ValidationError] when validation is enabled and the document violates the SVG standard
+        # @raise [Sevgi::Graphics::LintError] when linting is enabled and the document has structural conflicts
+        # @see Sevgi::Graphics::Mixtures::Render#Render
+        def call(**options)
+          checks = DEFAULTS.merge(options.select { |key, _| DEFAULTS.key?(key) })
+          self.PreRender(**checks) if respond_to?(:PreRender)
           render_options = options.reject { |key, _| DEFAULTS.key?(key) }
-          self.Render(*, **render_options)
+          self.Render(**render_options)
         end
 
-        # Returns inherited root attributes for this document class.
-        # @return [Hash{Symbol => Object}] inherited root attributes
-        def self.attributes = self == Proto ? {} : {**superclass.attributes, **profile.attributes}
+        # Returns effective inherited root attributes for this document class.
+        # Profile update suffixes are applied from the oldest configured ancestor to this class.
+        # @return [Hash{Symbol => Object}] inherited root attributes without update suffixes
+        # @raise [Sevgi::ArgumentError] when a non-Proto class has no configured ancestor
+        def self.attributes
+          return {} if self == Proto
+
+          ArgumentError.("Document class has no configured profile: #{self}") unless profile
+          return superclass.attributes unless instance_variable_defined?(:@profile)
+
+          Attributes.new(superclass.attributes).tap { it.merge!(@profile.attributes) }.to_h
+        end
 
         # Returns inherited preamble lines for this document class.
         # @return [Array<String>, nil]
-        def self.preambles = self == Proto ? nil : profile.preambles || superclass.preambles
+        # @raise [Sevgi::ArgumentError] when a non-Proto class has no configured ancestor
+        def self.preambles
+          return if self == Proto
+
+          ArgumentError.("Document class has no configured profile: #{self}") unless profile
+          return superclass.preambles unless instance_variable_defined?(:@profile)
+
+          @profile.preambles || superclass.preambles
+        end
       end
 
       require_relative "document/base"