sevgi-graphics 0.93.1 → 0.95.0

data/README.md

@@ -1,5 +1,37 @@
 # Sevgi Graphics
 
-Provides the core SVG DSL, document profiles, and rendering behavior.
+Core SVG DSL, document profiles, and rendering behavior.
 
-See the root [README](../README.md) and the documentation site for usage.
+## Install
+
+```sh
+gem install sevgi-graphics
+```
+
+## Require
+
+```ruby
+require "sevgi/graphics"
+```
+
+## Example
+
+```ruby
+doc = Sevgi::Graphics.SVG(:minimal) { rect(width: 3, height: 5) }
+doc.call
+```
+
+## Ruby compatibility
+
+Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4.0 and the current development Ruby from `.ruby-version`.
+
+## Native prerequisites
+
+None beyond Ruby and this gem's Ruby dependencies.
+
+## Links
+
+- Documentation: https://sevgi.roktas.dev
+- API documentation: https://www.rubydoc.info/gems/sevgi-graphics
+- Source: https://github.com/roktas/sevgi/tree/main/graphics
+- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/lib/sevgi/graphics/attribute.rb

@@ -20,80 +20,198 @@ module Sevgi
         # @param given [String, Symbol] attribute name
         # @return [Boolean]
         def internal?(given)
-          (@internal ||= {})[given] ||= given.start_with?(ATTRIBUTE_INTERNAL_PREFIX)
+          (@internal ||= {})[given] ||= key(given).start_with?(ATTRIBUTE_INTERNAL_PREFIX)
         end
 
         # Returns the normalized attribute id.
         # @param given [String, Symbol] attribute name
         # @return [Symbol]
         def id(given)
-          (@id ||= {})[given] ||= (updateable?(given) ? given.to_s.delete_suffix(ATTRIBUTE_UPDATE_SUFFIX) : given)
-            .to_sym
+          (@id ||= {})[given] ||= begin
+            name = updateable?(given) ? key(given).delete_suffix(ATTRIBUTE_UPDATE_SUFFIX) : key(given)
+            XML.name(name, context: "XML attribute name") unless internal?(given)
+            name.to_sym
+          end
         end
 
         # Reports whether an attribute uses merge/update syntax.
         # @param given [String, Symbol] attribute name
         # @return [Boolean]
         def updateable?(given)
-          (@updateable ||= {})[given] ||= given.end_with?(ATTRIBUTE_UPDATE_SUFFIX)
+          (@updateable ||= {})[given] ||= key(given).end_with?(ATTRIBUTE_UPDATE_SUFFIX)
+        end
+
+        private
+
+        def key(given)
+          return given.to_s if given.is_a?(::String) || given.is_a?(::Symbol)
+
+          ArgumentError.("XML attribute name must be a String or Symbol")
         end
       end
 
       extend Ident
 
+      # Owned mutable snapshots for values entering an attribute store.
+      # @api private
+      module Snapshot
+        class << self
+          def capture(value, normalize_keys: false, seen: {}.compare_by_identity)
+            case value
+            when ::Hash
+              nested(value, seen) { capture_hash(value, normalize_keys:, seen:) }
+            when ::Array
+              nested(value, seen) { value.map { capture(it, seen:) } }
+            else
+              capture_value(value)
+            end
+          end
+
+          private
+
+          def capture_hash(value, normalize_keys:, seen:)
+            identities = {}
+            value.each_with_object({}) do |(key, item), captured|
+              key = normalize_keys ? normalize_key(key) : capture(key, seen:)
+              identity = normalize_keys ? key : XML.snapshot(key, context: "XML attribute value")
+              if captured.key?(key) || identities.key?(identity)
+                ArgumentError.("Attribute keys collide after normalization or stringification")
+              end
+
+              identities[identity] = true
+              captured[key] = capture(item, seen:)
+            end
+          end
+
+          def capture_value(value)
+            text = XML.text(value, context: "XML attribute value")
+            case value
+            when ::Numeric, ::Symbol, ::NilClass, ::TrueClass, ::FalseClass
+              value
+            else
+              text
+            end
+          end
+
+          def nested(value, seen)
+            ArgumentError.("Cyclic XML attribute value is not supported") if seen.key?(value)
+
+            seen[value] = true
+            yield
+          ensure
+            seen.delete(value)
+          end
+
+          def normalize_key(key)
+            normalized = key.to_sym if key.respond_to?(:to_sym)
+            return normalized if normalized.is_a?(::Symbol)
+
+            ArgumentError.("Attribute Hash keys must normalize to Symbols")
+          rescue Sevgi::ArgumentError
+            raise
+          rescue ::StandardError => e
+            ArgumentError.("Attribute Hash key cannot be normalized: #{e.class}: #{e.message}")
+          end
+        end
+      end
+
+      private_constant :Snapshot
+
+      # Captures a caller-independent attribute value.
+      # @param value [Object] value to capture
+      # @param normalize_keys [Boolean] normalize direct Hash keys to Symbols
+      # @return [Object] owned mutable snapshot
+      # @raise [Sevgi::ArgumentError] when value is invalid, cyclic, collides, or cannot be converted
+      # @api private
+      def self.capture(value, normalize_keys: false) = Snapshot.capture(value, normalize_keys:)
+
+      # Returns the text form used for an XML attribute value before escaping.
+      # @param value [Object] attribute value
+      # @return [String]
+      # @raise [Sevgi::ArgumentError] when value is invalid, cyclic, or cannot be stringified as XML
+      # @api private
+      def self.xml_text(value)
+        value = XML.snapshot(value, context: "XML attribute value")
+        text = case value
+        when ::Hash
+          value.map { |key, attr_value| "#{key}:#{attr_value}" }.join("; ")
+        when ::Array
+          value.join(" ")
+        else
+          value.to_s
+        end
+
+        XML.text(text, context: "XML attribute value")
+      end
+
       # Mutable SVG attribute store with Sevgi update syntax.
       class Store
-        # Creates an attribute store.
+        # Creates an attribute store from recursively owned snapshots. Mutable non-container leaves are stringified
+        # once; later caller mutation cannot change the store.
         # @param attributes [Hash] initial attributes
         # @return [void]
+        # @raise [Sevgi::ArgumentError] when input is not a Hash or a name/value is invalid, cyclic, colliding, or cannot
+        #   be converted
         def initialize(attributes = {})
           @store = {}
 
           import(attributes)
         end
 
-        # Imports attributes into the store.
+        # Atomically imports recursively owned attribute snapshots.
         # @param attributes [Hash] attributes to merge
         # @return [Hash] internal store
+        # @raise [Sevgi::ArgumentError] when input is not a Hash or a name/value is invalid, cyclic, colliding, or cannot
+        #   be converted
         def import(attributes)
-          hash = attributes
-            .compact
-            .to_a
-            .to_h do |key, value|
-              [key.to_sym, value.is_a?(::Hash) ? value.transform_keys(&:to_sym) : value]
-            end
+          ArgumentError.("Attributes must be imported from a Hash") unless attributes.is_a?(::Hash)
+
+          hash = attributes.each_with_object({}) do |(key, value), captured|
+            next if value.nil?
+
+            id = Attribute.id(key)
+            ArgumentError.("Attribute names collide after normalization: #{id}") if captured.key?(id)
+
+            captured[id] = Attribute.capture(value, normalize_keys: value.is_a?(::Hash))
+          end
 
           @store.merge!(hash)
         end
 
-        # Returns an attribute by normalized key.
+        # Returns a live stored attribute value. Mutating a returned container intentionally mutates this store; rendering
+        # revalidates the resulting value.
         # @param key [String, Symbol] attribute key
         # @return [Object, nil]
+        # @raise [Sevgi::ArgumentError] when key is not a valid XML attribute name
         def [](key)
           @store[Attribute.id(key)]
         end
 
-        # Assigns an attribute value.
+        # Assigns a recursively owned attribute snapshot. Mutable non-container leaves are stringified once.
         # @param key [String, Symbol] attribute key
         # @param value [Object, nil] attribute value; nil is ignored
-        # @return [Object, nil] assigned value or nil
+        # @return [Object, nil] stored snapshot or nil
         # @raise [Sevgi::ArgumentError] when update syntax receives incompatible values
         # @raise [Sevgi::ArgumentError] when update syntax receives an unsupported value type
+        # @raise [Sevgi::ArgumentError] when a name/value is invalid, cyclic, colliding, or cannot be converted
         def []=(key, value)
           return if value.nil?
 
-          @store[id = Attribute.id(key)] = @store.key?(id) && Attribute.updateable?(key) ? update(id, value) : value
+          id = Attribute.id(key)
+          value = Attribute.capture(value, normalize_keys: value.is_a?(::Hash))
+          @store[id] = @store.key?(id) && Attribute.updateable?(key) ? update(id, value) : value
         end
 
         # Deletes an attribute by normalized key.
         # @param key [String, Symbol] attribute key
         # @return [Object, nil] deleted value
+        # @raise [Sevgi::ArgumentError] when key is not a valid XML attribute name
         def delete(key)
           @store.delete(Attribute.id(key))
         end
 
-        # Returns public attributes ready for rendering.
-        # @return [Hash]
+        # Returns public attributes ready for rendering. Nested values remain live store values.
+        # @return [Hash] shallow attribute view
         def export
           hash = @store.reject { |id, _| Attribute.internal?(id) }
           return hash unless hash.key?(:id)
@@ -105,16 +223,18 @@ module Sevgi
         # Reports whether an attribute exists.
         # @param key [String, Symbol] attribute key
         # @return [Boolean]
+        # @raise [Sevgi::ArgumentError] when key is not a valid XML attribute name
         def has?(key)
           @store.key?(Attribute.id(key))
         end
 
-        # Copies the attribute store.
+        # Copies the attribute store with recursively independent values.
         # @param original [Sevgi::Graphics::Attribute::Store] store to copy
         # @return [void]
+        # @raise [Sevgi::ArgumentError] when live stored values became cyclic or invalid
         def initialize_copy(original)
           @store = {}
-          original.store.each { |key, value| @store[key] = value.dup }
+          original.store.each { |key, value| @store[key] = Attribute.capture(value) }
 
           super
         end
@@ -125,14 +245,16 @@ module Sevgi
           export.keys
         end
 
-        # Returns the internal attribute hash.
-        # @return [Hash]
+        # Returns the live internal attribute Hash. Mutating it intentionally mutates this store; rendering revalidates
+        # names and values.
+        # @return [Hash] live internal store
         def to_h
           @store
         end
 
         # Returns rendered XML attribute lines.
         # @return [Array<String>]
+        # @raise [Sevgi::ArgumentError] when stored names or values are invalid, cyclic, or cannot be stringified
         def to_xml_lines
           export.map { |id, value| to_xml(id, value) }
         end
@@ -164,16 +286,8 @@ module Sevgi
         private_constant :UPDATER
 
         def to_xml(id, value)
-          text = case value
-          when ::Hash
-            value.map { |key, attr_value| "#{key}:#{attr_value}" }.join("; ")
-          when ::Array
-            value.join(" ")
-          else
-            value.to_s
-          end
-
-          "#{id}=#{text.encode(xml: :attr)}"
+          name = XML.name(id, context: "XML attribute name")
+          "#{name}=#{Attribute.xml_text(value).encode(xml: :attr)}"
         end
       end
     end

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

@@ -6,6 +6,10 @@ module Sevgi
   module Graphics
     # SVG canvas size, margins, viewport, and viewBox.
     class Canvas
+      ORIGIN_FIELDS = %i[x y].freeze
+      REPLACEMENTS = %i[width height unit name margins].freeze
+      private_constant :ORIGIN_FIELDS, :REPLACEMENTS
+
       # @overload call(arg = Undefined, **kwargs)
       #   Builds a canvas from a paper profile or explicit size.
       #   @param arg [Sevgi::Graphics::Paper, Symbol, String, Sevgi::Undefined] paper profile or paper object
@@ -48,15 +52,19 @@ module Sevgi
       def_delegators :@margin, *Margin.members
       def_delegators :@size, *Paper.members
 
-      # @!attribute [r] size
-      #   @return [Sevgi::Graphics::Paper] paper size object
-      # @!attribute [r] margin
-      #   @return [Sevgi::Graphics::Margin] canvas margins
-      # @!attribute [r] inner
-      #   @return [Sevgi::Graphics::Paper] inner paper after margins
-      attr_reader :size, :margin, :inner
+      # Returns the paper size object.
+      # @return [Sevgi::Graphics::Paper]
+      attr_reader :size
+
+      # Returns the canvas margins.
+      # @return [Sevgi::Graphics::Margin]
+      attr_reader :margin
+
+      # Returns the inner paper after margins.
+      # @return [Sevgi::Graphics::Paper]
+      attr_reader :inner
 
-      # Creates a canvas.
+      # Creates a canvas with finite real dimensions greater than zero and margins that leave a positive inner area.
       # @param width [Numeric] canvas width
       # @param height [Numeric] canvas height
       # @param unit [Symbol, String] SVG unit
@@ -75,12 +83,12 @@ module Sevgi
       # @overload attributes(origin = Undefined)
       #   Returns SVG root viewport attributes.
       #   @param origin [Numeric, Array<Numeric>, nil, Sevgi::Undefined] viewBox origin
-      #   @return [Hash]
+      #   @return [Hash{Symbol => String}] SVG viewport and viewBox attributes
       #   @raise [Sevgi::ArgumentError] when origin is invalid
       def attributes(...) = {**viewport, viewBox: viewbox(...)}
 
       # Returns SVG width and height attributes.
-      # @return [Hash]
+      # @return [Hash{Symbol => String}] SVG width and height attributes
       def viewport = {width: "#{width}#{unit}", height: "#{height}#{unit}"}
 
       # Returns the SVG viewBox string.
@@ -91,13 +99,43 @@ module Sevgi
 
       # Returns a canvas with selected fields replaced.
       # @param kwargs [Hash] replacement options
+      # @option kwargs [Numeric] :width replacement canvas width
+      # @option kwargs [Numeric] :height replacement canvas height
+      # @option kwargs [Symbol, String] :unit replacement SVG unit
+      # @option kwargs [Symbol, String] :name replacement paper name
+      # @option kwargs [Array<Numeric>] :margins replacement margin shorthand values
       # @return [Sevgi::Graphics::Canvas]
-      def with(**kwargs) = self.class.new(**size.to_h, margins: kwargs.fetch(:margins, margin.to_a))
+      # @raise [Sevgi::ArgumentError] when an unknown option is supplied
+      # @raise [Sevgi::ArgumentError] when a replacement value is invalid
+      def with(**kwargs)
+        unknown = kwargs.keys - REPLACEMENTS
+
+        ArgumentError.("Unknown canvas option: #{unknown.first}") unless unknown.empty?
+
+        margins = kwargs.fetch(:margins, margin.to_a)
+        replacements = kwargs.dup.tap { it.delete(:margins) }
+
+        self.class.new(**size.to_h, **replacements, margins:)
+      end
 
       private
 
       def compute
-        @inner = size.with(width: width - margin.left - margin.right, height: height - margin.top - margin.bottom)
+        @inner = size.with(**inner_size)
+        ensure_inner_area
+      end
+
+      def ensure_inner_area
+        return if @inner.width.positive? && @inner.height.positive?
+
+        ArgumentError.("Canvas margins must leave a positive inner area")
+      end
+
+      def inner_size
+        {
+          width: width - margin.left - margin.right,
+          height: height - margin.top - margin.bottom
+        }
       end
 
       def originate(origin)
@@ -105,7 +143,7 @@ module Sevgi
         when Undefined
           [-margin.left, -margin.top]
         when ::Numeric, ::NilClass
-          [origin.to_f, origin.to_f]
+          scalar_origin(origin)
         when ::Array
           pair(origin)
         else
@@ -113,12 +151,24 @@ module Sevgi
         end
       end
 
+      def coordinate!(field, value)
+        return 0.0 if value.nil?
+
+        Scalar.finite(value, context: "canvas origin", field:)
+      end
+
+      def scalar_origin(origin)
+        coordinate!(:origin, origin || 0).then { [it, it] }
+      end
+
       def prettify(*floats)
         floats.map { (it % 1).zero? ? it.to_i : it }
       end
 
       def pair(array)
-        array.size == 2 ? array.map(&:to_f) : ArgumentError.("Argument must be an Array of size 2")
+        ArgumentError.("Canvas origin must have exactly two coordinates") unless array.size == 2
+
+        ORIGIN_FIELDS.zip(array).map { |field, value| coordinate!(field, value) }
       end
     end
   end