sevgi-graphics 0.73.2 → 0.94.0

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Graphics
+    # Paper size and unit profile.
+    Paper = Data.define(:width, :height, :unit, :name) do
+      include Comparable
+
+      # @!attribute [r] width
+      #   @return [Float] paper width
+      # @!attribute [r] height
+      #   @return [Float] paper height
+      # @!attribute [r] unit
+      #   @return [Symbol] SVG unit
+      # @!attribute [r] name
+      #   @return [Symbol] profile name
+
+      # Creates a paper profile.
+      # @param width [Numeric] paper width
+      # @param height [Numeric] paper height
+      # @param unit [Symbol, String] SVG unit
+      # @param name [Symbol, String] profile name
+      # @return [void]
+      # @raise [Sevgi::ArgumentError] when dimensions, unit, or profile name are invalid
+      def initialize(width:, height:, unit: "mm", name: :custom)
+        super(
+          width: self.class.send(:dimension!, :width, width),
+          height: self.class.send(:dimension!, :height, height),
+          unit: self.class.send(:symbol!, :unit, unit),
+          name: self.class.send(:symbol!, :name, name)
+        )
+      end
+
+      # Compares papers by width, height, unit, then name.
+      # @param other [Sevgi::Graphics::Paper] paper to compare
+      # @return [Integer, nil]
+      def <=>(other) = deconstruct <=> other.deconstruct
+
+      # Reports strict paper equality.
+      # @param other [Object] object to compare
+      # @return [Boolean]
+      def eql?(other) = self.class == other.class && deconstruct == other.deconstruct
+
+      # Returns a hash compatible with strict equality.
+      # @return [Integer]
+      def hash = [self.class, *deconstruct].hash
+
+      # Returns the longer side.
+      # @return [Float]
+      def longest = [width, height].max
+
+      # Returns the shorter side.
+      # @return [Float]
+      def shortest = [width, height].min
+
+      alias_method :==, :eql?
+
+      @profiles = {}
+
+      # Reports whether a named paper profile exists.
+      # @param name [Object] profile name
+      # @return [Boolean]
+      def self.exist?(name) = name.respond_to?(:to_sym) && profiles.key?(name.to_sym)
+
+      # Defines or replaces a named paper profile.
+      # @param name [Symbol, String] profile name
+      # @param spec [Hash] paper dimensions and unit
+      # @option spec [Numeric] :width paper width
+      # @option spec [Numeric] :height paper height
+      # @option spec [Symbol, String] :unit SVG unit
+      # @return [Sevgi::Graphics::Paper]
+      # @raise [Sevgi::ArgumentError] when the profile name is reserved or invalid
+      def self.define(name, **spec)
+        name = symbol!(:name, name)
+
+        ArgumentError.("Paper name is reserved: #{name}") if reserved?(name) && !exist?(name)
+
+        singleton_class.remove_method(name) if singleton_class.method_defined?(name, false)
+        singleton_class.attr_reader(name)
+        profiles[name] = instance_variable_set("@#{name}", new(name:, **spec))
+      end
+
+      def self.reserved?(name) = @reserved.include?(name.to_sym)
+
+      def self.profiles = @profiles
+
+      def self.dimension!(field, value)
+        Float(value)
+      rescue ::ArgumentError, ::TypeError
+        ArgumentError.("Invalid paper #{field}: #{value.inspect}")
+      end
+
+      def self.symbol!(field, value)
+        value.to_sym
+      rescue ::NoMethodError, ::TypeError
+        ArgumentError.("Invalid paper #{field}: #{value.inspect}")
+      end
+
+      @reserved = methods.map(&:to_sym).freeze
+
+      private_class_method :dimension!, :profiles, :reserved?, :symbol!
+
+      {
+        a0: [841, 1189, "mm"],
+        a1: [594, 841, "mm"],
+        a2: [420, 594, "mm"],
+        a3: [297, 420, "mm"],
+        a4: [210, 297, "mm"],
+        a5: [148, 210, "mm"],
+        a6: [105, 148, "mm"],
+        a7: [74, 105, "mm"],
+        a8: [52, 74, "mm"],
+        a9: [37, 52, "mm"],
+        a10: [26, 37, "mm"],
+
+        b0: [1000, 1414, "mm"],
+        b1: [707, 1000, "mm"],
+        b2: [500, 707, "mm"],
+        b3: [353, 500, "mm"],
+        b4: [250, 353, "mm"],
+        b5: [176, 250, "mm"],
+        b6: [125, 176, "mm"],
+        b7: [88, 125, "mm"],
+        b8: [62, 88, "mm"],
+        b9: [44, 62, "mm"],
+        b10: [31, 44, "mm"],
+
+        c0: [917, 1297, "mm"],
+        c1: [648, 917, "mm"],
+        c2: [458, 648, "mm"],
+        c3: [324, 458, "mm"],
+        c4: [229, 324, "mm"],
+        c5: [162, 229, "mm"],
+        c6: [114, 162, "mm"],
+        c7: [81, 114, "mm"],
+        c8: [57, 81, "mm"],
+        c9: [40, 57, "mm"],
+        c10: [28, 40, "mm"],
+
+        business: [85, 55, "mm"],
+        large: [130, 210, "mm"],
+        passport: [88, 125, "mm"],
+        pocket: [90, 140, "mm"],
+        travelers: [110, 210, "mm"],
+        us: [216, 279, "mm"],
+        xlarge: [190, 250, "mm"],
+
+        icon16: [16, 16, "px"],
+        icon32: [32, 32, "px"],
+        icon64: [64, 64, "px"],
+        icon128: [128, 128, "px"],
+        icon256: [256, 256, "px"],
+        icon512: [512, 512, "px"]
+      }.each { |name, (width, height, unit)| define(name, width:, height:, unit:) }
+
+      class << self
+        alias_method :default, :a4
+      end
+
+      profiles[:default] = profiles.fetch(:a4)
+    end
+  end
+end

data/lib/sevgi/graphics/auxiliary.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "auxiliary/margin"
+require_relative "auxiliary/paper"
+
+require_relative "auxiliary/canvas"
+require_relative "auxiliary/content"

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

@@ -3,6 +3,7 @@
 module Sevgi
   module Graphics
     module Document
+      # Standard document profile with the full common DSL mixture set.
       class Base < Proto
         document :base
 
@@ -18,6 +19,11 @@ module Sevgi
         mixture :Underscore
         mixture :Validate
 
+        # Runs pre-render validation and lint checks.
+        # @param options [Hash] pre-render options
+        # @return [void]
+        # @raise [Sevgi::ValidationError] when validation fails
+        # @raise [Sevgi::Graphics::LintError] when linting fails
         def PreRender(**options)
           self.Validate() if options[:validate]
           self.Lint() if options[:lint]

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

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

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

@@ -3,6 +3,7 @@
 module Sevgi
   module Graphics
     module Document
+      # SVG document profile intended for embedding in HTML.
       class HTML < Default
         document(
           :html,

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

@@ -3,6 +3,7 @@
 module Sevgi
   module Graphics
     module Document
+      # SVG document profile with Inkscape-oriented namespaces and mixtures.
       class Inkscape < Default
         document(
           :inkscape,

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

@@ -3,6 +3,7 @@
 module Sevgi
   module Graphics
     module Document
+      # Minimal document profile without XML preambles or default namespace attributes.
       class Minimal < Base
         document :minimal
       end

data/lib/sevgi/graphics/document.rb

@@ -2,51 +2,232 @@
 
 module Sevgi
   module Graphics
+    # SVG document profile factory.
     module Document
+      # Defensive copy helper for profile metadata snapshots.
+      # @api private
+      module Snapshot
+        # Returns a recursively independent copy of a value.
+        # @param value [Object] value to copy
+        # @return [Object] copied value
+        def self.copy(value)
+          case value
+          when ::Hash
+            hash(value)
+          when ::Array
+            value.map { copy(it) }
+          else
+            duplicate(value)
+          end
+        end
+
+        # Returns a recursively frozen independent copy of a value.
+        # @param value [Object] value to copy and freeze
+        # @return [Object] frozen copied value
+        def self.frozen(value)
+          case value
+          when ::Hash
+            value.to_h { |key, item| [frozen(key), frozen(item)] }.freeze
+          when ::Array
+            value.map { frozen(it) }.freeze
+          else
+            duplicate(value).freeze
+          end
+        end
+
+        def self.hash(value) = value.to_h { |key, item| [copy(key), copy(item)] }
+
+        def self.duplicate(value)
+          value.dup
+        rescue ::TypeError
+          value
+        end
+
+        private_class_method :duplicate, :hash
+      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
+      # @return [Sevgi::Graphics::Document::Proto] SVG root element
+      # @raise [Sevgi::ArgumentError] when the document profile is unknown
       def self.call(document, canvas = Undefined, **, &block)
+        klass = case document
+        when ::Class
+          document if document <= Proto
+        else
+          Profile[document]
+        end
+
+        ArgumentError.("Unknown document profile: #{document}") unless klass
+
+        klass.root(**klass.attributes, **canvas_attributes(canvas), **, &block)
+      end
+
+      def self.canvas_attributes(canvas)
         case canvas
         when Undefined, ::NilClass
           {}
         when Canvas
           canvas.attributes
         else
-          Canvas.(canvas).attributes
-        end => attributes
+          Canvas.from_paper(canvas).attributes
+        end
+      end
+
+      private_class_method :canvas_attributes
+
+      # Defines or returns a document profile class.
+      # @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, 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: Undefined, attributes: Undefined, overwrite: false)
+        return anonymous(attributes:, preambles:) if name == Undefined
+
+        if (current = Profile[name])
+          reject_conflict(name, current, attributes:, preambles:) unless overwrite
+          return current unless overwrite
+        end
 
-        (klass = Profile[document]).root(**klass.attributes, **attributes, **, &block)
+        attributes, preambles = defaults(attributes:, preambles:)
+        Class.new(Base) { document(name, preambles:, attributes:, overwrite:) }
       end
 
+      def self.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 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, :reject_conflict
+
+      # Immutable document profile metadata.
+      # @api private
       class Profile
         @available = {}
 
         class << self
+          # @return [Hash<Symbol, Class>] registered profile classes
           attr_reader :available
         end
 
-        def self.[](name) = 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 self.register(name, klass) = (available[name] = klass)
+        # 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)
 
-        attr_reader :name, :attributes, :preambles
+          if (current = available[name])
+            unless overwrite || current.profile == klass.profile
+              ArgumentError.("Document profile already defined differently: #{name}")
+            end
 
+            return current unless overwrite
+          end
+
+          available[name] = klass
+        end
+
+        # 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
+
+        # 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
+
+        # Creates profile metadata.
+        # @param name [Object, nil] profile name
+        # @param attributes [Hash, nil] default root attributes
+        # @param preambles [Array<String>, nil] preamble lines
+        # @return [void]
+        # @raise [Sevgi::ArgumentError] when name cannot be normalized
         def initialize(name, attributes: nil, preambles: nil)
-          @name = name
-          @attributes = attributes || {}
-          @preambles = preambles
+          @name = name.nil? ? nil : self.class.normalize!(name)
+          @attributes = Snapshot.frozen(attributes || {})
+          @preambles = preambles.nil? ? nil : Snapshot.frozen(preambles)
         end
+
+        # Reports strict profile equality.
+        # @param other [Object] object to compare
+        # @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]
+
+        # Returns preamble lines.
+        # @return [Array<String>, nil] mutation-isolated preamble snapshot
+        def preambles = Snapshot.copy(@preambles)
       end
 
       private_constant :Profile
 
+      # Class-level DSL used while defining document classes.
+      # @api private
       module DSL
+        # @return [Sevgi::Graphics::Document::Profile] document profile metadata
         attr_reader :profile
 
-        def document(name, attributes: {}, preambles: nil)
-          @profile = Profile.new(name, attributes:, preambles:).tap do
-            Profile.register(name, self)
-          end
+        # Sets document profile metadata on a class.
+        # @param name [Object] profile name
+        # @param attributes [Hash] 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
+        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
         end
 
+        # Includes a graphics mixture into the document class.
+        # @param mixture [Symbol, String] mixture constant name
+        # @param ns [Module] namespace containing mixture modules
+        # @return [Module] included mixture module
+        # @raise [NameError] when the mixture does not exist
         def mixture(mixture, ns: Graphics::Mixtures)
           include(mod = ns.const_get(mixture))
           extend(mod::ClassMethods) if defined?(mod::ClassMethods)
@@ -55,8 +236,10 @@ module Sevgi
 
       private_constant :DSL
 
+      # Default render-time checks.
       DEFAULTS = {lint: true, validate: true}.freeze
 
+      # Base document root element class.
       class Proto < Element
         public_class_method :new
 
@@ -67,6 +250,11 @@ 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
         def call(*, **)
           options = DEFAULTS.merge(**)
 
@@ -74,8 +262,12 @@ module Sevgi
           self.Render(*, **options)
         end
 
+        # Returns inherited root attributes for this document class.
+        # @return [Hash]
         def self.attributes = self == Proto ? {} : {**superclass.attributes, **profile.attributes}
 
+        # Returns inherited preamble lines for this document class.
+        # @return [Array<String>, nil]
         def self.preambles = self == Proto ? nil : profile.preambles || superclass.preambles
       end
 

data/lib/sevgi/graphics/element.rb

@@ -1,36 +1,75 @@
 # frozen_string_literal: true
 
-require "sevgi/standard"
-
 module Sevgi
   module Graphics
+    # SVG element node used by the graphics DSL.
     class Element
+      # Builds an element node.
+      # @param name [Symbol, String] SVG element name
+      # @param parent [Sevgi::Graphics::Element] parent element
+      # @return [Sevgi::Graphics::Element]
+      # @raise [Sevgi::ArgumentError] when an argument cannot be parsed as attributes or content
       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
+      # @return [Sevgi::Graphics::Element]
       def self.root(*, &block) = element(:svg, *, 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
 
       class << self
         require "sevgi/standard"
 
+        # Reports whether an SVG element name is known.
+        # @param name [Symbol] SVG element name
+        # @return [Boolean]
         def valid?(name) = Standard.element?(name)
-      rescue ::LoadError
+      rescue ::LoadError => e
+        raise unless e.path == "sevgi/standard"
+
+        # Reports whether an SVG element name is known.
+        # @return [Boolean]
         def valid?(...) = true
       end
 
       private_class_method :new
 
+      # Sentinel parent used by root SVG elements.
       RootParent = Object.new.tap { def it.inspect = "RootParent" }.freeze
 
+      # SVG element method-name normalization.
+      # @api private
       module Ident
+        # Normalizes a Ruby method name into an SVG element id.
+        # @param given [Symbol, String] method name
+        # @return [Symbol]
         def id(given) = (@id ||= {})[given] ||= given.to_s.tr("_", "-").to_sym
       end
 
       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
 
+      # 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
+      # @return [void]
       def initialize(name, parent:, attributes: {}, contents: [], &block)
         @name = name
         @attributes = Attributes.new(attributes)
@@ -43,28 +82,49 @@ module Sevgi
         instance_exec(&block) if block
       end
 
+      # Dispatches SVG element DSL calls and caches valid element methods.
+      # @param name [Symbol] missing method name
+      # @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?(id = Element.id(name)) ? Dispatch.(self, id, *, &block) : super
+        Element.valid?(tag = Element.id(name)) ? Dispatch.(self, name, tag, *, &block) : super
       end
 
+      # Reports whether a missing method can dispatch to an SVG element.
+      # @param name [Symbol] queried method name
+      # @param include_private [Boolean] standard Ruby respond_to? flag
+      # @return [Boolean]
       def respond_to_missing?(name, include_private = false)
         Element.valid?(Element.id(name)) || super
       end
 
+      # Element method-missing parser and cache.
+      # @api private
       module Dispatch
         extend self
 
-        def call(element, name, *, &)
+        # Dispatches an element DSL call.
+        # @param element [Sevgi::Graphics::Element] parent element
+        # @param method [Symbol] Ruby method name
+        # @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?(name)
+          unless Element.method_defined?(method)
             Element.class_exec do
-              define_method(name) { |*args, &block| self.class.element(name, *args, parent: self, &block) }
+              define_method(method) { |*args, &block| self.class.element(tag, *args, parent: self, &block) }
             end
           end
 
-          element.public_send(name, *, &)
+          element.public_send(method, *, &)
         end
 
+        # Parses element DSL arguments.
+        # @param name [Symbol] SVG element name
+        # @param args [Array<Object>] positional DSL arguments
+        # @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 = {}, []
 
@@ -89,7 +149,7 @@ module Sevgi
 
       protected
 
-      attr_writer :children, :attributes
+      attr_writer :attributes, :children, :contents, :parent
     end
   end
 end