sevgi-graphics 0.94.0 → 0.98.2

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

@@ -3,6 +3,19 @@
 module Sevgi
   module Graphics
     # Four-sided margin with CSS-like shorthand normalization.
+    # @!parse
+    #   class Margin
+    #     # Creates a margin from one to four CSS-like shorthand values.
+    #     # @param top [Numeric, nil] top value or all-sides shorthand
+    #     # @param right [Numeric, nil] right value or horizontal shorthand
+    #     # @param bottom [Numeric, nil] bottom value
+    #     # @param left [Numeric, nil] left value
+    #     # @return [Sevgi::Graphics::Margin]
+    #     # @raise [Sevgi::ArgumentError] when a supplied value is not a finite, non-negative real number
+    #     # @example Create a vertical and horizontal margin
+    #     #   Sevgi::Graphics::Margin[5, 10]
+    #     def self.[](top = nil, right = nil, bottom = nil, left = nil); end
+    #   end
     Margin = Data.define(:top, :right, :bottom, :left) do
       include Comparable
 
@@ -15,25 +28,30 @@ module Sevgi
       # @!attribute [r] left
       #   @return [Float] left margin
 
-      # Creates a margin from one to four shorthand values.
+      # Creates a margin from one to four shorthand values. Values must be finite real numbers greater than or equal to
+      # zero.
       # @param top [Numeric, nil] top value or all-sides shorthand
       # @param right [Numeric, nil] right value or horizontal shorthand
       # @param bottom [Numeric, nil] bottom value
       # @param left [Numeric, nil] left value
       # @return [void]
+      # @raise [Sevgi::ArgumentError] when a supplied margin is not a finite, non-negative real number
       def initialize(top: nil, right: nil, bottom: nil, left: nil)
         super(**normalize(top, right, bottom, left))
       end
 
       # Compares margins by top, right, bottom, then left.
-      # @param other [Sevgi::Graphics::Margin] margin to compare
-      # @return [Integer, nil]
-      def <=>(other) = deconstruct <=> other.deconstruct
+      # @param other [Object] margin to compare
+      # @return [Integer, nil] comparison result, or nil for a non-Margin operand
+      def <=>(other)
+        deconstruct <=> other.deconstruct if other.is_a?(self.class)
+      end
 
       # Returns a margin inflated horizontally and vertically.
       # @param h [Numeric] horizontal addition
       # @param v [Numeric] vertical addition
       # @return [Sevgi::Graphics::Margin]
+      # @raise [Sevgi::ArgumentError] when the adjusted margin is negative or not finite
       def adjust(h, v) = self.class[top + v, right + h, bottom + v, left + h]
 
       # Reports strict margin equality.
@@ -54,16 +72,10 @@ module Sevgi
       def vertical = top + bottom
 
       alias_method :==, :eql?
-      alias_method :to_a, :deconstruct
 
-      # Builds a margin from an array-like shorthand.
-      # @param array [Object] value converted with Array()
-      # @return [Sevgi::Graphics::Margin]
-      def self.margin(array)
-        self[
-          *(array = Array(array)[0...(size = Margin.members.size)]).fill(nil, array.size, size - array.size)
-        ]
-      end
+      # Returns margin values in top, right, bottom, left order.
+      # @return [Array<Float>]
+      alias_method :to_a, :deconstruct
 
       # Returns a zero margin.
       # @return [Sevgi::Graphics::Margin]
@@ -74,7 +86,14 @@ module Sevgi
       def normalize(top, right, bottom, left)
         values = [top, right, bottom, left]
 
-        Margin.members.zip(values_for(values.compact.size, values).map { Float(it) }).to_h
+        Margin
+          .members
+          .zip(
+            values_for(values.compact.size, values).map do |value|
+              Scalar.finite(value, context: "margin", field: :value, nonnegative: true)
+            end
+          )
+          .to_h
       end
 
       def values_for(size, values)

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

@@ -3,6 +3,19 @@
 module Sevgi
   module Graphics
     # Paper size and unit profile.
+    # @!parse
+    #   class Paper
+    #     # Creates a paper profile from dimensions and optional metadata.
+    #     # @param width [Numeric] paper width
+    #     # @param height [Numeric] paper height
+    #     # @param unit [Symbol, String] SVG unit
+    #     # @param name [Symbol, String] profile name
+    #     # @return [Sevgi::Graphics::Paper]
+    #     # @raise [Sevgi::ArgumentError] when dimensions, unit, or name are invalid
+    #     # @example Create a custom paper profile with value notation
+    #     #   Sevgi::Graphics::Paper[90, 50, :mm, :card]
+    #     def self.[](width, height, unit = "mm", name = :custom); end
+    #   end
     Paper = Data.define(:width, :height, :unit, :name) do
       include Comparable
 
@@ -15,26 +28,30 @@ module Sevgi
       # @!attribute [r] name
       #   @return [Symbol] profile name
 
-      # Creates a paper profile.
+      # Creates a paper profile. Dimensions must be finite real numbers greater than zero.
       # @param width [Numeric] paper width
       # @param height [Numeric] paper height
       # @param unit [Symbol, String] SVG unit
       # @param name [Symbol, String] profile name
+      # @param options [Hash] unsupported extra options
       # @return [void]
-      # @raise [Sevgi::ArgumentError] when dimensions, unit, or profile name are invalid
-      def initialize(width:, height:, unit: "mm", name: :custom)
+      # @raise [Sevgi::ArgumentError] when dimensions, unit, name, or options are invalid
+      def initialize(width:, height:, unit: "mm", name: :custom, **options)
+        self.class.send(:options!, options)
         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)
+          unit: self.class.send(:normalize!, :unit, unit),
+          name: self.class.send(:normalize!, :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
+      # @return [Integer, nil] comparison result, or nil for a non-Paper operand
+      def <=>(other)
+        deconstruct <=> other.deconstruct if other.is_a?(self.class)
+      end
 
       # Reports strict paper equality.
       # @param other [Object] object to compare
@@ -56,108 +73,123 @@ module Sevgi
       alias_method :==, :eql?
 
       @profiles = {}
+      @accessors = {}
+      @mutex = ::Mutex.new
 
-      # Reports whether a named paper profile exists.
+      # Reports whether a normalizable named paper profile exists. Invalid converters return false.
       # @param name [Object] profile name
       # @return [Boolean]
-      def self.exist?(name) = name.respond_to?(:to_sym) && profiles.key?(name.to_sym)
+      def self.exist?(name)
+        name = normalize(name)
+        name ? @mutex.synchronize { @profiles.key?(name) } : false
+      end
+
+      # Returns a registered paper profile by name.
+      # @param name [Symbol, String] profile name, including names that are not Ruby identifiers
+      # @return [Sevgi::Graphics::Paper] registered profile
+      # @raise [Sevgi::ArgumentError] when name is invalid or no profile is registered
+      # @example Look up a non-identifier profile name
+      #   Sevgi::Graphics::Paper.define("business-card", width: 90, height: 50)
+      #   Sevgi::Graphics::Paper.fetch("business-card")
+      def self.fetch(name)
+        name = normalize!(:name, name)
+        @mutex.synchronize { @profiles.fetch(name) { ArgumentError.("Unknown paper profile: #{name}") } }
+      end
+
+      # Returns registered profile names.
+      # @return [Array<Symbol>] frozen name snapshot
+      def self.keys = @mutex.synchronize { @profiles.keys.freeze }
 
-      # Defines or replaces a named paper profile.
+      # Defines a named paper profile after complete validation. Registration is process-global and thread-atomic.
+      # Identical definitions return the canonical profile and conflicting definitions raise unless replacement is
+      # explicitly requested. Names that are not Ruby call syntax remain accessible through {.fetch}.
       # @param name [Symbol, String] profile name
+      # @param overwrite [Boolean] true to replace an existing profile
       # @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)
+      # @raise [Sevgi::ArgumentError] when the name, dimensions, unit, overwrite flag, or options are reserved or invalid,
+      #   or a non-bang definition conflicts with the registered profile
+      # @example Define or reuse a matching profile
+      #   Sevgi::Graphics::Paper.define(:card, width: 90, height: 50)
+      # @example Replace a profile explicitly
+      #   Sevgi::Graphics::Paper.define(:card, width: 100, height: 60, overwrite: true)
+      def self.define(name, overwrite: false, **spec)
+        name = normalize!(:name, name)
+        ArgumentError.("Paper name is reserved: #{name}") if reserved?(name)
+        overwrite = overwrite!(overwrite)
+        profile = new(name:, **spec)
+
+        register(name, profile, overwrite:)
+      end
 
-        ArgumentError.("Paper name is reserved: #{name}") if reserved?(name) && !exist?(name)
+      class << self
+        private
 
-        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 install(name)
+          return if @accessors.key?(name)
 
-      def self.reserved?(name) = @reserved.include?(name.to_sym)
+          define_singleton_method(name) { @mutex.synchronize { @profiles.fetch(name) } }
+          @accessors[name] = true
+        end
 
-      def self.profiles = @profiles
+        def register(name, profile, overwrite:)
+          @mutex.synchronize do
+            if !overwrite && (current = @profiles[name])
+              ArgumentError.("Paper already defined differently: #{name}") unless current == profile
 
-      def self.dimension!(field, value)
-        Float(value)
-      rescue ::ArgumentError, ::TypeError
-        ArgumentError.("Invalid paper #{field}: #{value.inspect}")
-      end
+              next current
+            end
+
+            install(name)
+            @profiles[name] = profile
+          end
+        end
 
-      def self.symbol!(field, value)
-        value.to_sym
-      rescue ::NoMethodError, ::TypeError
-        ArgumentError.("Invalid paper #{field}: #{value.inspect}")
+        def reserved?(name) = @reserved.include?(name)
+
+        def dimension!(field, value)
+          Scalar.finite(value, context: "paper", field:, positive: true)
+        end
+
+        def options!(options)
+          return if options.empty?
+
+          ArgumentError.("Unknown paper options: #{options.keys.join(", ")}")
+        end
+
+        def overwrite!(value)
+          return value if [true, false].include?(value)
+
+          ArgumentError.("Paper overwrite must be true or false")
+        end
+
+        def normalize(value)
+          normalized = value.to_sym if value.respond_to?(:to_sym)
+          normalized if normalized.is_a?(::Symbol)
+        rescue ::StandardError
+          nil
+        end
+
+        def normalize!(field, value)
+          normalize(value) || ArgumentError.("Invalid paper #{field}")
+        end
       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:) }
+      PAPER_SIZES.each { |name, (width, height, unit)| define(name, width:, height:, unit:) }
 
-      class << self
-        alias_method :default, :a4
+      # Returns the default paper profile.
+      # @return [Sevgi::Graphics::Paper]
+      def self.default
+        @mutex.synchronize { @profiles.fetch(:default) }
       end
 
-      profiles[:default] = profiles.fetch(:a4)
+      @accessors[:default] = true
+      @profiles[:default] = @profiles.fetch(:a4)
     end
   end
 end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Graphics
+    # Output path normalization shared by Graphics writers and exporters.
+    # @api private
+    module Path
+      # Converts a non-blank path to an expanded String.
+      # @param value [String, #to_path] raw path value
+      # @param context [String] public operation named in errors
+      # @return [String] expanded path
+      # @raise [Sevgi::ArgumentError] when value is blank, has an invalid type, or path conversion fails
+      def self.call(value, context:)
+        path = value.respond_to?(:to_path) ? value.to_path : value
+        ArgumentError.("#{context} must be a String or path-like object") unless path.is_a?(::String)
+        ArgumentError.("#{context} must be provided") if path.strip.empty?
+
+        ::File.expand_path(path)
+      rescue ::Sevgi::ArgumentError
+        raise
+      rescue ::StandardError => e
+        ArgumentError.("#{context} must be a String or path-like object: #{e.message}")
+      end
+
+      # Resolves an optional path with the writer/exporter directory convention.
+      # @param value [String, #to_path, nil] explicit path or directory
+      # @param default [String, #to_path] default output path
+      # @param context [String] public operation named in errors
+      # @return [String] expanded output file path
+      # @raise [Sevgi::ArgumentError] when a selected path/default is blank, invalid, or cannot be converted
+      def self.resolve(value, default:, context:)
+        return call(default, context: "#{context} default") if value.nil?
+
+        path = call(value, context: "#{context} path")
+        return path unless ::File.directory?(path)
+
+        default = call(default, context: "#{context} default")
+        ::File.join(path, ::File.basename(default))
+      end
+    end
+
+    private_constant :Path
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Graphics
+    # 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, 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
+      # @raise [Sevgi::ArgumentError] when value is not a finite real number in the requested range
+      def self.finite(value, context:, field:, positive: false, nonnegative: false)
+        invalid(context, field, value) unless real?(value)
+
+        number = Float(value)
+        invalid(context, field, value) unless valid?(number, positive:, nonnegative:)
+
+        number
+      rescue ::ArgumentError, ::RangeError, ::TypeError
+        invalid(context, field, value)
+      end
+
+      # 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
+
+      # 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
+
+      class << self
+        private
+
+        def real?(value) = value.is_a?(::Numeric) && !value.is_a?(::Complex)
+
+        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
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Graphics
+    # Built-in paper dimensions and units.
+    # @api private
+    PAPER_SIZES = {
+      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"]
+    }.transform_values(&:freeze).freeze
+
+    private_constant :PAPER_SIZES
+  end
+end

data/lib/sevgi/graphics/auxiliary.rb

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

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: {