sevgi-graphics 0.94.0 → 0.95.0

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

@@ -15,12 +15,14 @@ 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
@@ -54,6 +56,9 @@ module Sevgi
       def vertical = top + bottom
 
       alias_method :==, :eql?
+
+      # Returns margin values in top, right, bottom, left order.
+      # @return [Array<Float>]
       alias_method :to_a, :deconstruct
 
       # Builds a margin from an array-like shorthand.
@@ -74,7 +79,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

@@ -15,26 +15,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 +60,111 @@ 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
 
-      # Defines or replaces a named paper profile.
+      # Defines a named paper profile after complete validation. Registration is process-global and thread-atomic.
+      # Existing profiles are replaced by default; with `overwrite: false`, identical definitions return the canonical
+      # profile and conflicting definitions raise. Names that are not Ruby call syntax remain accessible through
+      # `public_send`.
       # @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
+      def self.define(name, overwrite: true, **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)
+      def self.install(name)
+        return if @accessors.key?(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))
+        define_singleton_method(name) { @mutex.synchronize { @profiles.fetch(name) } }
+        @accessors[name] = true
       end
 
-      def self.reserved?(name) = @reserved.include?(name.to_sym)
+      def self.register(name, profile, overwrite:)
+        @mutex.synchronize do
+          if !overwrite && (current = @profiles[name])
+            ArgumentError.("Paper already defined differently: #{name}") unless current == profile
 
-      def self.profiles = @profiles
+            next current
+          end
+
+          install(name)
+          @profiles[name] = profile
+        end
+      end
+
+      def self.reserved?(name) = @reserved.include?(name)
 
       def self.dimension!(field, value)
-        Float(value)
-      rescue ::ArgumentError, ::TypeError
-        ArgumentError.("Invalid paper #{field}: #{value.inspect}")
+        Scalar.finite(value, context: "paper", field:, positive: true)
       end
 
-      def self.symbol!(field, value)
-        value.to_sym
-      rescue ::NoMethodError, ::TypeError
-        ArgumentError.("Invalid paper #{field}: #{value.inspect}")
+      def self.options!(options)
+        return if options.empty?
+
+        ArgumentError.("Unknown paper options: #{options.keys.join(", ")}")
+      end
+
+      def self.overwrite!(value)
+        return value if [true, false].include?(value)
+
+        ArgumentError.("Paper overwrite must be true or false")
+      end
+
+      def self.normalize(value)
+        normalized = value.to_sym if value.respond_to?(:to_sym)
+        normalized if normalized.is_a?(::Symbol)
+      rescue ::StandardError
+        nil
+      end
+
+      def self.normalize!(field, value)
+        normalize(value) || ArgumentError.("Invalid paper #{field}")
       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
+      private_class_method(
+        :dimension!,
+        :install,
+        :normalize,
+        :normalize!,
+        :options!,
+        :overwrite!,
+        :register,
+        :reserved?
+      )
+
+      PAPER_SIZES.each { |name, (width, height, unit)| define(name, width:, height:, unit:) }
+
+      # 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/scalar.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Graphics
+    # Validates finite real numeric values used by graphics auxiliaries.
+    # @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 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
+
+      def self.real?(value) = value.is_a?(::Numeric) && !value.is_a?(::Complex)
+
+      def self.valid?(number, positive:, nonnegative:)
+        number.finite? && (!positive || number.positive?) && (!nonnegative || number >= 0)
+      end
+
+      def self.invalid(context, field, value) = ArgumentError.("Invalid #{context} #{field}: #{value.inspect}")
+
+      private_class_method :invalid, :real?, :valid?
+    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,8 @@
 # frozen_string_literal: true
 
+require_relative "auxiliary/scalar"
 require_relative "auxiliary/margin"
+require_relative "auxiliary/sizes"
 require_relative "auxiliary/paper"
 
 require_relative "auxiliary/canvas"