sevgi-graphics 0.73.2 → 0.93.1

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,166 @@
 
 module Sevgi
   module Graphics
+    # SVG document profile factory.
     module Document
+      # 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] document preamble lines
+      # @param attributes [Hash] 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
+
+        profile = Profile.new(name, attributes:, preambles:)
+
+        if (current = Profile[name])
+          unless overwrite || current.profile == profile
+            ArgumentError.("Document profile already defined differently: #{name}")
+          end
+
+          return current unless overwrite
+        end
 
-        (klass = Profile[document]).root(**klass.attributes, **attributes, **, &block)
+        Class.new(Base) { document(name, preambles:, attributes:, overwrite:) }
       end
 
+      # 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]
+
+        # 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}")
+            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
 
-        def self.register(name, klass) = (available[name] = klass)
+        # @return [Hash] default root attributes
+        attr_reader :attributes
 
-        attr_reader :name, :attributes, :preambles
+        # @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 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
+          @name = name.nil? ? nil : self.class.normalize!(name)
           @attributes = attributes || {}
           @preambles = preambles
         end
+
+        # Reports strict profile equality.
+        # @param other [Object] object to compare
+        # @return [Boolean]
+        def ==(other) = self.class == other.class && deconstruct == other.deconstruct
+
+        # Returns profile components.
+        # @return [Array<(Symbol, nil), Hash, (Array<String>, nil)>]
+        def deconstruct = [name, attributes, 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 +170,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 +184,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 +196,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 = {}, []
 

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

@@ -2,19 +2,32 @@
 
 module Sevgi
   module Graphics
+    # Callable drawing module support.
+    # @api private
     module Module
+      # Tracks newly defined public methods as callable drawing steps.
+      # @param method [Symbol] method name Ruby reports as added
+      # @return [Array<Symbol>, nil]
       def method_added(method)
         super
 
         _callables << method if public_method_defined?(method)
       end
 
+      # Class-level DSL for callable drawing modules.
+      # @api private
       module DSL
-        def call(after = false, &block) = ((after ? _after : _befores) << block)
+        # 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)
       end
 
       private_constant :DSL
 
+      # Initializes callable module state.
+      # @param base [Module] extended module
+      # @return [void]
       def self.extended(base)
         base.instance_exec do
           @_callables = []
@@ -29,6 +42,13 @@ module Sevgi
         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
       def self.call(mod, receiver, ...)
         mod._befores.each { receiver.Within(receiver, &it) } if mod.respond_to?(:_befores) && mod._befores
         # return last callable return value
@@ -37,15 +57,27 @@ module Sevgi
         end
       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)
-        raise ArgumentError, "Must be a module: #{mod}" unless mod.instance_of?(::Module)
+        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) }
       end
     end
 
     module Mixtures
+      # DSL helpers for invoking callable drawing modules.
       module Call
+        # @overload Call(mod, *args, **kwargs)
+        #   Runs a callable drawing module in the current element context.
+        #   @param mod [Module] callable 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
         def Call(mod, ...)
           Graphics::Module.call(mod, self, ...)
         end
@@ -54,7 +86,7 @@ module Sevgi
 
         # rubocop:disable Metrics/MethodLength
         def CallWithin(mod, container, element, *args, **kwargs, &block)
-          raise ArgumentError, "Must be a module: #{mod}" unless mod.instance_of?(::Module)
+          ArgumentError.("Must be a module: #{mod}") unless mod.instance_of?(::Module)
 
           kwargs = kwargs.merge(id: F.demodulize(mod).to_sym) unless kwargs.key?(:id)